Code examples and usage patterns for the Archivist AI public REST API.
- Create an API key at app.myarchivist.ai/profile?section=dev
- Set your key as an environment variable:
export ARCHIVIST_API_KEY="your-api-key-here"
- Browse the examples below or explore the full API reference
| Example | Language | Description |
|---|---|---|
| quickstart.py | Python | List campaigns, characters, and sessions |
| quickstart.ts | TypeScript | Same flow using fetch |
| quests.py | Python | Create and manage quests |
| beats.py | Python | Fetch nested session beat hierarchy |
| entities.py | Python | Unified compendium entity picker |
| moments.py | Python | Moment list filters and fields=card |
| journals.py | Python | List journal entries with pagination and fields=card; Markdown export and content_format="markdown" create |
| ask.py | Python | Ask quota plus RAG chat over campaign knowledge |
| search.py | Python | Unified campaign search (GET /v1/campaigns/{id}/search) |
| pagination.py | Python | Iterate standard and entities list envelopes |
| images.py | Python | Image quota, AI generation, and direct upload init |
| error_handling.py | Python | Retry logic, rate limits, error parsing |
| types.ts | TypeScript | Importable response type definitions |
| curl/basics.sh | cURL | Common operations as shell commands |
https://api.myarchivist.ai
All endpoints require the x-api-key header for authentication.
Most list endpoints return the standard pagination envelope:
{ "data": [...], "total": 42, "page": 1, "size": 20, "pages": 3 }Use page and size query parameters to paginate. Examples: /v1/characters, /v1/moments, /v1/journals.
GET /v1/entities uses a different envelope suited to pickers:
{ "results": [...], "hasMore": true, "page": 1, "pages": 5, "total": 42 }Use page and limit (not size) to paginate. Each result includes id, name, type, and image.
Session beats — GET /v1/beats?session_id={id} returns a paginated flat list of beats linked to that session. Add include_hierarchy=true for a nested JSON array (not paginated); each node includes a children array and linkedEntities ID lists.
Sessions — Game sessions are system-managed on the developer API. Use GET /v1/sessions to list and PATCH or PUT /v1/sessions/{id} to update metadata (title, summary, session_date, image). There is no POST or DELETE /v1/sessions for API keys or agent OAuth; session create/delete is reserved for first-party product clients.
Campaign search — GET /v1/campaigns/{id}/search?q= returns grouped hits (max 10 per type). Optional types is a comma list of characters, factions, locations, items, sessions, recaps, quests, journals.
fields=card on GET /v1/characters, GET /v1/moments, and GET /v1/journals returns lightweight list items for pickers and feeds instead of full summaries.
MIT