Archivist LogoArchivist

API Reference

Complete REST API documentation for Archivist. All endpoints require the x-api-key header unless noted.

New to Archivist? Start with Core Concepts and the Data Models.

Supported Methods

Quick reference for HTTP methods supported by each resource.

ResourceGETPOSTPUTPATCHDELETE
Campaigns✓✓—✓✓
Characters✓✓—✓✓
Sessions✓——✓—
Beats✓✓—✓✓
Moments✓✓—✓✓
Factions✓✓—✓✓
Locations✓✓—✓✓
Items✓✓—✓✓
Lore Files✓✓✓—✓
Links✓✓—✓✓
Ask (RAG)—✓———

Health

GET/health

Health check for the API service (no auth required).

Request Example

curl https://api.myarchivist.ai/health

Responses

200Service is healthy
{
  "status": "healthy",
  "service": "archivist-api",
  "version": "1.0.0",
  "environment": "production",
  "port": 8000,
  "timestamp": "2025-01-15T10:30:00.123456Z"
}

Ask (RAG)

POST/v1/ask

RAG chat endpoint for campaign questions. Supports chat history and streaming.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

campaign_id*— ID of your campaign
messages*— Chat messages: [{ role, content }]
stream— Return a streaming response

Request Example

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "your-campaign-id",
    "messages": [ {"role": "user", "content": "Who is Cassius Traven?"} ]
  }' \
  https://api.myarchivist.ai/v1/ask

Responses

200Successful response (non-streaming)
{
  "answer": "Cassius Traven is a shadowy information broker who operates in the city's underground...",
  "monthlyTokensRemaining": 12345,
  "hourlyTokensRemaining": 6789
}
400Bad request - missing required fields
{
  "detail": "messages is required"
}
401Unauthorized - invalid API key
{
  "detail": "Invalid API key"
}
429Rate limit exceeded
{
  "detail": "Monthly token limit exceeded"
}

Campaigns

GET/v1/campaigns

List your campaigns.

Headers

x-api-key*— Your API key

Query Params

page— Page number
size— Page size

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/campaigns?page=1&size=10"

Responses

200List of campaigns
{
  "data": [
    {
      "id": "camp_abc123",
      "title": "Shadows of Elyndor",
      "description": "A dark fantasy campaign",
      "system": "D&D 5e",
      "public": false,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}
401Unauthorized - invalid API key
{
  "detail": "Invalid API key"
}
GET/v1/campaigns/{campaign_id}

Get a specific campaign by ID.

Headers

x-api-key*— Your API key

Request Example

curl -H "x-api-key: YOUR_API_KEY" https://api.myarchivist.ai/v1/campaigns/abc123

Responses

200Campaign details
{
  "id": "camp_abc123",
  "title": "Shadows of Elyndor",
  "description": "A dark fantasy campaign",
  "system": "D&D 5e",
  "public": false,
  "created_at": "2024-01-15T10:30:00Z"
}
404Campaign not found
{
  "detail": "Campaign not found"
}
401Unauthorized - invalid API key
{
  "detail": "Invalid API key"
}
POST/v1/campaigns

Create a new campaign.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

title*— Campaign title
description— Campaign description
system— Game system (e.g. D&D 5e)

Request Example

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Epic Campaign",
    "description": "A thrilling adventure",
    "system": "D&D 5e"
  }' \
  https://api.myarchivist.ai/v1/campaigns

Responses

201Campaign created successfully
{
  "id": "camp_new123",
  "title": "My Epic Campaign",
  "description": "A thrilling adventure",
  "system": "D&D 5e",
  "public": false,
  "created_at": "2024-01-25T16:45:00Z"
}
422Validation error - missing required field
{
  "detail": "title is required"
}
401Unauthorized - invalid API key
{
  "detail": "Invalid API key"
}
PATCH/v1/campaigns/{campaign_id}

Update a campaign.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

title— Campaign title
description— Campaign description

Request Example

curl -X PATCH \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Campaign Name"}' \
  https://api.myarchivist.ai/v1/campaigns/abc123

Responses

200Campaign updated successfully
{
  "id": "camp_abc123",
  "title": "Updated Campaign Name",
  "description": "A dark fantasy campaign",
  "system": "D&D 5e",
  "public": false,
  "created_at": "2024-01-15T10:30:00Z"
}
404Campaign not found
{
  "detail": "Campaign not found"
}
401Unauthorized
{
  "detail": "Invalid API key"
}
DELETE/v1/campaigns/{campaign_id}

Permanently delete a campaign. This action cannot be undone.

Headers

x-api-key*— Your API key

Request Example

curl -X DELETE -H "x-api-key: YOUR_API_KEY" https://api.myarchivist.ai/v1/campaigns/abc123

Responses

204Campaign deleted successfully
(no content)
404Campaign not found
{
  "detail": "Campaign not found"
}
401Unauthorized - invalid API key
{
  "detail": "Invalid API key"
}
GET/v1/campaigns/{campaign_id}/stats

Get campaign statistics (character count, session count, etc).

Headers

x-api-key*— Your API key

Request Example

curl -H "x-api-key: YOUR_API_KEY" https://api.myarchivist.ai/v1/campaigns/abc123/stats

Responses

200Campaign statistics
{
  "campaignId": "camp_abc123",
  "characters": 12,
  "sessions": 24,
  "moments": 156,
  "beats": 48,
  "factions": 5,
  "locations": 18,
  "items": 32
}
404Campaign not found
{
  "detail": "Campaign not found"
}
GET/v1/campaigns/{campaign_id}/links

List links between entities in a campaign. Supports filtering by source/target entities and alias.

Headers

x-api-key*— Your API key

Query Params

page— Page number
size— Page size
from_id— Filter by source entity ID
from_type— Filter by source entity type (Character, Location, etc.)
to_id— Filter by target entity ID
to_type— Filter by target entity type
alias— Filter by relationship label/alias

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/campaigns/abc123/links?from_id=char_456&from_type=Character"

Responses

200List of entity links
{
  "data": [
    {
      "id": "link_123",
      "campaign_id": "camp_abc123",
      "from_id": "char_456",
      "from_type": "Character",
      "to_id": "char_789",
      "to_type": "Character",
      "alias": "friends",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 25,
  "page": 1,
  "size": 20,
  "pages": 2
}
POST/v1/campaigns/{campaign_id}/links

Create a link between two entities.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

from_id*— Source entity ID
from_type*— Source entity type (Character, Location, etc)
to_id*— Target entity ID
to_type*— Target entity type
alias— Relationship label

Responses

201Link created successfully
{
  "id": "link_new123",
  "campaign_id": "camp_abc123",
  "from_id": "char_456",
  "from_type": "Character",
  "to_id": "loc_789",
  "to_type": "Location",
  "alias": "home",
  "created_at": "2024-01-25T16:45:00Z"
}
422Validation error
{
  "detail": "from_id and to_id are required"
}
PATCH/v1/campaigns/{campaign_id}/links/{link_id}

Update a link.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

alias— Updated relationship label

Responses

200Link updated successfully
{
  "id": "link_123",
  "campaign_id": "camp_abc123",
  "from_id": "char_456",
  "from_type": "Character",
  "to_id": "loc_789",
  "to_type": "Location",
  "alias": "updated label",
  "created_at": "2024-01-15T10:30:00Z"
}
404Link not found
{
  "detail": "Link not found"
}
DELETE/v1/campaigns/{campaign_id}/links/{link_id}

Delete a link.

Headers

x-api-key*— Your API key

Responses

204Link deleted successfully
(no content)
404Link not found
{
  "detail": "Link not found"
}

Characters

GET/v1/characters

List characters filtered by campaign.

Headers

x-api-key*— Your API key

Query Params

campaign_id*— Campaign ID
search— Search by name
character_type— PC, NPC, etc.
approved_only— Filter approved (default true)
with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/characters?campaign_id=abc123"

Responses

200List of characters
{
  "data": [
    {
      "id": "char_123",
      "campaign_id": "camp_abc123",
      "character_name": "Thorin Ironforge",
      "player_name": "John Smith",
      "description": "A brave dwarf warrior",
      "type": "PC",
      "approved": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}
422Missing required campaign_id
{
  "detail": "campaign_id is required"
}
401Unauthorized
{
  "detail": "Invalid API key"
}
GET/v1/characters/{character_id}

Get a specific character by ID.

Headers

x-api-key*— Your API key

Query Params

with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" https://api.myarchivist.ai/v1/characters/char-123

Responses

200Character details
{
  "id": "char_123",
  "campaign_id": "camp_abc123",
  "character_name": "Thorin Ironforge",
  "player_name": "John Smith",
  "description": "A brave dwarf warrior",
  "type": "PC",
  "approved": true,
  "created_at": "2024-01-15T10:30:00Z"
}
404Character not found
{
  "detail": "Character not found"
}
POST/v1/characters

Create a new character.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

character_name*— Character name
campaign_id*— Campaign ID
player_name— Player name
description— Character description
type— PC, NPC, etc.
image— HTTPS image URL (max 2048 chars)

Request Example

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "character_name": "Thorin Ironforge",
    "player_name": "John Smith",
    "description": "A brave dwarf warrior",
    "type": "PC",
    "campaign_id": "abc123"
  }' \
  https://api.myarchivist.ai/v1/characters

Responses

201Character created successfully
{
  "id": "char_new456",
  "campaign_id": "camp_abc123",
  "character_name": "Thorin Ironforge",
  "player_name": "John Smith",
  "description": "A brave dwarf warrior",
  "type": "PC",
  "approved": false,
  "created_at": "2024-01-25T16:45:00Z"
}
422Validation error - missing required fields
{
  "detail": "character_name and campaign_id are required"
}
422Validation error - HTTP URL not allowed for image
{
  "detail": "image must be an HTTPS URL"
}
404Campaign not found
{
  "detail": "Campaign not found"
}
PATCH/v1/characters/{character_id}

Update a character.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

character_name— Character name
description— Character description
image— HTTPS image URL (max 2048 chars)

Responses

200Character updated successfully
{
  "id": "char_123",
  "campaign_id": "camp_abc123",
  "character_name": "Thorin Ironforge the Bold",
  "player_name": "John Smith",
  "description": "A brave dwarf warrior with a legendary magic axe",
  "type": "PC",
  "approved": true,
  "created_at": "2024-01-15T10:30:00Z"
}
404Character not found
{
  "detail": "Character not found"
}
DELETE/v1/characters/{character_id}

Delete a character.

Headers

x-api-key*— Your API key

Responses

204Character deleted successfully
(no content)
404Character not found
{
  "detail": "Character not found"
}

Sessions

GET/v1/sessions

List sessions in a campaign.

Headers

x-api-key*— Your API key

Query Params

campaign_id*— Campaign ID
session_type— audioUpload, playByPost, discordVoice, etc.
public_only— Show only public sessions
with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/sessions?campaign_id=abc123"

Responses

200List of game sessions
{
  "data": [
    {
      "id": "session_123",
      "campaign_id": "camp_abc123",
      "type": "audioUpload",
      "title": "The Lost Mines of Phandelver",
      "summary": "The party explored the ancient mines...",
      "session_date": "2024-01-20T19:00:00Z",
      "public": false,
      "created_at": "2024-01-20T22:30:00Z"
    }
  ],
  "total": 24,
  "page": 1,
  "size": 20,
  "pages": 2
}
422Missing required campaign_id
{
  "detail": "campaign_id is required"
}
GET/v1/sessions/{session_id}

Get a specific session by ID.

Headers

x-api-key*— Your API key

Query Params

include_beats— Include related beats
include_moments— Include related moments
with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/sessions/session-123?include_beats=true"

Responses

200Session details
{
  "id": "session_123",
  "campaign_id": "camp_abc123",
  "type": "audioUpload",
  "title": "The Lost Mines of Phandelver",
  "summary": "The party explored the ancient mines...",
  "session_date": "2024-01-20T19:00:00Z",
  "public": false,
  "created_at": "2024-01-20T22:30:00Z"
}
404Session not found
{
  "detail": "Session not found"
}
PATCH/v1/sessions/{session_id}

Update a session (title, summary, or session_date only).

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

title— Session title
summary— Session summary
session_date— ISO datetime

Responses

200Session updated successfully
{
  "id": "session_123",
  "campaign_id": "camp_abc123",
  "type": "audioUpload",
  "title": "Updated Session Title",
  "summary": "Updated summary...",
  "session_date": "2024-01-20T19:00:00Z",
  "public": false,
  "created_at": "2024-01-20T22:30:00Z"
}
404Session not found
{
  "detail": "Session not found"
}

Beats

GET/v1/beats

List beats in a campaign (ordered by index).

Headers

x-api-key*— Your API key

Query Params

campaign_id*— Campaign ID
page— Page number
size— Page size
with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/beats?campaign_id=abc123"

Responses

200List of beats
{
  "data": [
    {
      "id": "beat_123",
      "campaign_id": "camp_abc123",
      "game_session_id": "session_456",
      "label": "The Final Battle",
      "type": "major",
      "description": "The party confronts the dark lord",
      "index": 1,
      "parent_id": null,
      "created_at": "2024-01-20T22:30:00Z"
    }
  ],
  "total": 48,
  "page": 1,
  "size": 20,
  "pages": 3
}
422Missing required campaign_id
{
  "detail": "campaign_id is required"
}
GET/v1/beats/{beat_id}

Get a specific beat by ID.

Headers

x-api-key*— Your API key

Query Params

with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" https://api.myarchivist.ai/v1/beats/beat-123

Responses

200Beat details
{
  "id": "beat_123",
  "campaign_id": "camp_abc123",
  "game_session_id": "session_456",
  "label": "The Final Battle",
  "type": "major",
  "description": "The party confronts the dark lord",
  "index": 1,
  "parent_id": null,
  "created_at": "2024-01-20T22:30:00Z"
}
404Beat not found
{
  "detail": "Beat not found"
}
POST/v1/beats

Create a new beat.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

label*— Beat label
type*— major, minor, or step
campaign_id*— Campaign ID
game_session_id— Session ID
description— Beat description
index— Position within siblings
parent_id— Parent beat ID (for minor/step)

Request Example

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "The Final Battle",
    "type": "major",
    "campaign_id": "abc123",
    "game_session_id": "session-123"
  }' \
  https://api.myarchivist.ai/v1/beats

Responses

201Beat created successfully
{
  "id": "beat_new789",
  "campaign_id": "camp_abc123",
  "game_session_id": "session_456",
  "label": "The Final Battle",
  "type": "major",
  "description": null,
  "index": 1,
  "parent_id": null,
  "created_at": "2024-01-25T16:45:00Z"
}
422Validation error
{
  "detail": "label, type, and campaign_id are required"
}
PATCH/v1/beats/{beat_id}

Update a beat (uses JSON Merge Patch).

Headers

x-api-key*— Your API key
Content-Type*— application/merge-patch+json

Request Body

label— Beat label
description— Beat description
index— Position within siblings
parent_id— Parent beat ID

Responses

200Beat updated successfully
{
  "id": "beat_123",
  "campaign_id": "camp_abc123",
  "game_session_id": "session_456",
  "label": "Updated Beat Label",
  "type": "major",
  "description": "Updated description",
  "index": 2,
  "parent_id": null,
  "created_at": "2024-01-20T22:30:00Z"
}
404Beat not found
{
  "detail": "Beat not found"
}
DELETE/v1/beats/{beat_id}

Delete a beat (with hierarchy rules).

Headers

x-api-key*— Your API key

Responses

204Beat deleted successfully
(no content)
404Beat not found
{
  "detail": "Beat not found"
}

Moments

GET/v1/moments

List moments in a campaign or session.

Headers

x-api-key*— Your API key

Query Params

campaign_id— Campaign ID
session_id— Session ID
with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/moments?campaign_id=abc123"

Responses

200List of moments
{
  "data": [
    {
      "id": "moment_123",
      "campaign_id": "camp_abc123",
      "session_id": "session_456",
      "label": "Epic Quote",
      "content": "I am Thorin, son of Thrain...",
      "created_at": "2024-01-20T22:30:00Z"
    }
  ],
  "total": 156,
  "page": 1,
  "size": 20,
  "pages": 8
}
GET/v1/moments/{moment_id}

Get a specific moment by ID.

Headers

x-api-key*— Your API key

Query Params

with_links— Preserve wikilink markup

Responses

200Moment details
{
  "id": "moment_123",
  "campaign_id": "camp_abc123",
  "session_id": "session_456",
  "label": "Epic Quote",
  "content": "I am Thorin, son of Thrain...",
  "created_at": "2024-01-20T22:30:00Z"
}
404Moment not found
{
  "detail": "Moment not found"
}
POST/v1/moments

Create a new moment.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

label*— Moment label
campaign_id*— Campaign ID
session_id— Session ID
content— Moment content

Responses

201Moment created successfully
{
  "id": "moment_new999",
  "campaign_id": "camp_abc123",
  "session_id": "session_456",
  "label": "Epic Quote",
  "content": "I am Thorin...",
  "created_at": "2024-01-25T16:45:00Z"
}
422Validation error
{
  "detail": "label and campaign_id are required"
}
PATCH/v1/moments/{moment_id}

Update a moment.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Responses

200Moment updated successfully
{
  "id": "moment_123",
  "campaign_id": "camp_abc123",
  "session_id": "session_456",
  "label": "Updated Label",
  "content": "Updated content...",
  "created_at": "2024-01-20T22:30:00Z"
}
404Moment not found
{
  "detail": "Moment not found"
}
DELETE/v1/moments/{moment_id}

Delete a moment.

Headers

x-api-key*— Your API key

Responses

204Moment deleted successfully
(no content)
404Moment not found
{
  "detail": "Moment not found"
}

Factions

GET/v1/factions

List factions in a campaign.

Headers

x-api-key*— Your API key

Query Params

campaign_id*— Campaign ID
with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/factions?campaign_id=abc123"

Responses

200List of factions
{
  "data": [
    {
      "id": "faction_123",
      "campaign_id": "camp_abc123",
      "name": "The Shadow Thieves",
      "description": "A guild of thieves operating in the shadows",
      "type": "guild",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "size": 20,
  "pages": 1
}
422Missing required campaign_id
{
  "detail": "campaign_id is required"
}
GET/v1/factions/{faction_id}

Get a specific faction by ID.

Headers

x-api-key*— Your API key

Query Params

with_links— Preserve wikilink markup

Responses

200Faction details
{
  "id": "faction_123",
  "campaign_id": "camp_abc123",
  "name": "The Shadow Thieves",
  "description": "A guild of thieves operating in the shadows",
  "type": "guild",
  "created_at": "2024-01-15T10:30:00Z"
}
404Faction not found
{
  "detail": "Faction not found"
}
POST/v1/factions

Create a new faction.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

name*— Faction name
campaign_id*— Campaign ID
description— Faction description
type— Faction type
image— HTTPS image URL (max 2048 chars)

Responses

201Faction created successfully
{
  "id": "faction_new456",
  "campaign_id": "camp_abc123",
  "name": "The Iron Brotherhood",
  "description": "A mercenary company",
  "type": "guild",
  "created_at": "2024-01-25T16:45:00Z"
}
422Validation error
{
  "detail": "name and campaign_id are required"
}
PATCH/v1/factions/{faction_id}

Update a faction.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

name— Faction name
description— Faction description
type— Faction type
image— HTTPS image URL (max 2048 chars)

Responses

200Faction updated successfully
{
  "id": "faction_123",
  "campaign_id": "camp_abc123",
  "name": "Updated Faction Name",
  "description": "Updated description",
  "type": "guild",
  "created_at": "2024-01-15T10:30:00Z"
}
404Faction not found
{
  "detail": "Faction not found"
}
DELETE/v1/factions/{faction_id}

Delete a faction.

Headers

x-api-key*— Your API key

Responses

204Faction deleted successfully
(no content)
404Faction not found
{
  "detail": "Faction not found"
}

Locations

GET/v1/locations

List locations in a campaign.

Headers

x-api-key*— Your API key

Query Params

campaign_id*— Campaign ID
with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/locations?campaign_id=abc123"

Responses

200List of locations
{
  "data": [
    {
      "id": "loc_123",
      "campaign_id": "camp_abc123",
      "name": "The Prancing Pony",
      "description": "A cozy inn in Bree",
      "type": "tavern",
      "parent_id": "loc_456",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 18,
  "page": 1,
  "size": 20,
  "pages": 1
}
422Missing required campaign_id
{
  "detail": "campaign_id is required"
}
GET/v1/locations/{location_id}

Get a specific location by ID.

Headers

x-api-key*— Your API key

Query Params

with_links— Preserve wikilink markup

Responses

200Location details
{
  "id": "loc_123",
  "campaign_id": "camp_abc123",
  "name": "The Prancing Pony",
  "description": "A cozy inn in Bree",
  "type": "tavern",
  "parent_id": "loc_456",
  "created_at": "2024-01-15T10:30:00Z"
}
404Location not found
{
  "detail": "Location not found"
}
POST/v1/locations

Create a new location.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

name*— Location name
campaign_id*— Campaign ID
description— Location description
type— Location type
parent_id— Parent location ID
image— HTTPS image URL (max 2048 chars)

Responses

201Location created successfully
{
  "id": "loc_new789",
  "campaign_id": "camp_abc123",
  "name": "Rivendell",
  "description": "The Last Homely House",
  "type": "city",
  "parent_id": null,
  "created_at": "2024-01-25T16:45:00Z"
}
422Validation error
{
  "detail": "name and campaign_id are required"
}
PATCH/v1/locations/{location_id}

Update a location.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

name— Location name
description— Location description
type— Location type
parent_id— Parent location ID
image— HTTPS image URL (max 2048 chars)

Responses

200Location updated successfully
{
  "id": "loc_123",
  "campaign_id": "camp_abc123",
  "name": "Updated Location Name",
  "description": "Updated description",
  "type": "tavern",
  "parent_id": "loc_456",
  "created_at": "2024-01-15T10:30:00Z"
}
404Location not found
{
  "detail": "Location not found"
}
DELETE/v1/locations/{location_id}

Delete a location.

Headers

x-api-key*— Your API key

Responses

204Location deleted successfully
(no content)
404Location not found
{
  "detail": "Location not found"
}

Items

GET/v1/items

List items in a campaign.

Headers

x-api-key*— Your API key

Query Params

campaign_id*— Campaign ID
with_links— Preserve wikilink markup

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/items?campaign_id=abc123"

Responses

200List of items
{
  "data": [
    {
      "id": "item_123",
      "campaign_id": "camp_abc123",
      "name": "Sting",
      "description": "An elven blade that glows blue near orcs",
      "type": "weapon",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 32,
  "page": 1,
  "size": 20,
  "pages": 2
}
422Missing required campaign_id
{
  "detail": "campaign_id is required"
}
GET/v1/items/{item_id}

Get a specific item by ID.

Headers

x-api-key*— Your API key

Query Params

with_links— Preserve wikilink markup

Responses

200Item details
{
  "id": "item_123",
  "campaign_id": "camp_abc123",
  "name": "Sting",
  "description": "An elven blade that glows blue near orcs",
  "type": "weapon",
  "created_at": "2024-01-15T10:30:00Z"
}
404Item not found
{
  "detail": "Item not found"
}
POST/v1/items

Create a new item.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

name*— Item name
campaign_id*— Campaign ID
description— Item description
type— Item type (weapon, armor, etc)
image— HTTPS image URL (max 2048 chars)

Responses

201Item created successfully
{
  "id": "item_new456",
  "campaign_id": "camp_abc123",
  "name": "Anduril",
  "description": "The Flame of the West",
  "type": "weapon",
  "created_at": "2024-01-25T16:45:00Z"
}
422Validation error
{
  "detail": "name and campaign_id are required"
}
PATCH/v1/items/{item_id}

Update an item.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

name— Item name
description— Item description
type— Item type (weapon, armor, etc)
image— HTTPS image URL (max 2048 chars)

Responses

200Item updated successfully
{
  "id": "item_123",
  "campaign_id": "camp_abc123",
  "name": "Updated Item Name",
  "description": "Updated description",
  "type": "weapon",
  "created_at": "2024-01-15T10:30:00Z"
}
404Item not found
{
  "detail": "Item not found"
}
DELETE/v1/items/{item_id}

Delete an item.

Headers

x-api-key*— Your API key

Responses

204Item deleted successfully
(no content)
404Item not found
{
  "detail": "Item not found"
}

Lore Files

GET/v1/lore

List lore files in a campaign. Returns summaries without full content. Worlds have a 500,000 token cap across all lore files.

Headers

x-api-key*— Your API key

Query Params

campaign_id*— Campaign ID (world_id)
page— Page number
size— Page size

Request Example

curl -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/lore?campaign_id=abc123"

Responses

200List of lore files (content omitted)
{
  "data": [
    {
      "id": "lore_123",
      "world_id": "camp_abc123",
      "sub_type": "worldHistory",
      "file_name": "world_history.txt",
      "original_name": "World History.txt",
      "file_type": "text/plain",
      "size": 15234,
      "token_count": 3245,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 8
}
422Missing required campaign_id
{
  "detail": "campaign_id is required"
}
401Unauthorized
{
  "detail": "Invalid API key"
}
GET/v1/lore/{lore_id}

Get a specific lore file by ID including full content.

Headers

x-api-key*— Your API key

Request Example

curl -H "x-api-key: YOUR_API_KEY" https://api.myarchivist.ai/v1/lore/lore_123

Responses

200Lore file with full content
{
  "id": "lore_123",
  "world_id": "camp_abc123",
  "sub_type": "worldHistory",
  "content": "In the beginning, the gods created the world of Aetheria...",
  "file_name": "world_history.txt",
  "original_name": "World History.txt",
  "file_type": "text/plain",
  "size": 15234,
  "token_count": 3245,
  "created_at": "2024-01-15T10:30:00Z"
}
404Lore file not found
{
  "detail": "Lore file not found"
}
401Unauthorized
{
  "detail": "Invalid API key"
}
POST/v1/lore

Create a new lore file. Content is chunked (1000 tokens, 100 overlap) and embedded for RAG. Maximum 2,000,000 characters per request. World must stay under 500,000 token cap. The sub_type must be one of the valid LORE_SUBTYPES (see valid values below) or the request will be rejected.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

world_id*— Campaign ID
sub_type*— Lore subtype - must match a valid key (see Valid Subtypes below)
content*— Plain text content (max 2M chars)
file_name— File name
original_name— Original file name
file_type— MIME type (text/plain, text/markdown, etc.)
size— File size in bytes

Request Example

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "world_id": "camp_abc123",
    "sub_type": "worldHistory",
    "content": "In the beginning, the gods created the world of Aetheria...",
    "file_name": "world_history.txt",
    "file_type": "text/plain"
  }' \
  https://api.myarchivist.ai/v1/lore

Valid Subtypes (sub_type must match one of these keys):
• worldHistory, timeline, calendar, geography, climate, cosmology, magic, technology
• pantheon, religion, mythology, culture, languages, customs, festivals
• politics, nobility, guilds, laws, trade, currency
• wars, disasters, discoveries, inventions, dynasties
• races, monsters, wildlife, dragons
• artifacts, weapons, items, treasures
• prophecies, secrets, lore, research, spells, alchemy
• adventure, plots, npcs, rules, references
• other

Responses

201Lore file created successfully
{
  "id": "lore_new456",
  "world_id": "camp_abc123",
  "sub_type": "worldHistory",
  "content": "In the beginning, the gods created the world of Aetheria...",
  "file_name": "world_history.txt",
  "file_type": "text/plain",
  "token_count": 3245,
  "created_at": "2024-01-25T16:45:00Z"
}
422Validation error - missing required fields or invalid sub_type
{
  "detail": "world_id, sub_type, and content are required; sub_type must be a valid key"
}
413Content too large
{
  "detail": "Content exceeds 2,000,000 character limit"
}
400World token cap exceeded
{
  "detail": "World would exceed 500,000 token cap"
}
PUT/v1/lore

Update an existing lore file. If content is provided, embeddings are regenerated. Subject to same limits as POST. If updating sub_type, it must match a valid LORE_SUBTYPE key or the request will be rejected.

Headers

x-api-key*— Your API key
Content-Type*— application/json

Request Body

id*— Lore file ID
content— Updated content (triggers re-embedding)
file_name— Updated file name
sub_type— Updated subtype - must match a valid key (see POST for valid values)

Request Example

curl -X PUT \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "lore_123",
    "content": "Updated lore content...",
    "file_name": "world_history_v2.txt"
  }' \
  https://api.myarchivist.ai/v1/lore

Responses

200Lore file updated successfully
{
  "id": "lore_123",
  "world_id": "camp_abc123",
  "sub_type": "worldHistory",
  "content": "Updated lore content...",
  "file_name": "world_history_v2.txt",
  "token_count": 3456,
  "created_at": "2024-01-15T10:30:00Z"
}
404Lore file not found
{
  "detail": "Lore file not found"
}
422Validation error - invalid sub_type
{
  "detail": "id is required; sub_type must be a valid key if provided"
}
413Content too large
{
  "detail": "Content exceeds 2,000,000 character limit"
}
DELETE/v1/lore

Delete a lore file and its associated embeddings.

Headers

x-api-key*— Your API key

Query Params

id*— Lore file ID

Request Example

curl -X DELETE -H "x-api-key: YOUR_API_KEY" "https://api.myarchivist.ai/v1/lore?id=lore_123"

Responses

204Lore file deleted successfully
(no content)
404Lore file not found
{
  "detail": "Lore file not found"
}
401Unauthorized
{
  "detail": "Invalid API key"
}