Archivist Developer Docs

Quick Start

1. Sign in to Archivist and create an API key in Account Settings → API Keys.
2. Save your key securely as an environment variable.
3. Ping the health endpoint to verify connectivity.

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

Expected response:

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

Authentication

Send your API key with every request using the x-api-key header.

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

Do not embed keys in client-side code. Rotate compromised keys immediately.

Core Concepts

Data Models

Representative TypeScript interfaces for common resources. Fields may be extended over time; unknown fields should be ignored by clients.

// Common primitives
export type ID = string; // stable, opaque identifier
export type ISODate = string; // ISO 8601 timestamp

// Campaign
export interface Campaign {
  id: ID;
  title: string;
  description?: string;
  system?: string; // e.g., "D&D 5e"
  public: boolean;
  created_at: ISODate;
}

// Session
export type SessionType = 'audioUpload' | 'playByPost' | 'discordVoice' | 'other';
export interface GameSession {
  id: ID;
  campaign_id: ID;
  type: SessionType;
  title?: string;
  summary?: string;
  session_date?: ISODate;
  public: boolean;
  created_at: ISODate;
}

// Beat
export type BeatType = 'major' | 'minor' | 'step';
export interface Beat {
  id: ID;
  campaign_id: ID;
  game_session_id?: ID;
  label: string;
  type: BeatType;
  description?: string;
  index?: number; // ordering among siblings
  parent_id?: ID; // hierarchy (minor/step under a major or parent)
  created_at: ISODate;
}

// Moment
export interface Moment {
  id: ID;
  campaign_id: ID;
  session_id?: ID;
  label: string;
  content?: string; // rich text with optional wikilinks
  created_at: ISODate;
}

// Character
export type CharacterType = 'PC' | 'NPC' | 'Other';
export interface Character {
  id: ID;
  campaign_id: ID;
  character_name: string;
  player_name?: string;
  description?: string;
  type?: CharacterType;
  image?: string; // HTTPS URL, max 2048 chars
  approved: boolean;
  created_at: ISODate;
}

// Faction
export interface Faction {
  id: ID;
  campaign_id: ID;
  name: string;
  description?: string;
  type?: string;
  image?: string; // HTTPS URL, max 2048 chars
  created_at: ISODate;
}

// Location
export interface Location {
  id: ID;
  campaign_id: ID;
  name: string;
  description?: string;
  type?: string;
  parent_id?: ID;
  image?: string; // HTTPS URL, max 2048 chars
  created_at: ISODate;
}

// Item
export interface Item {
  id: ID;
  campaign_id: ID;
  name: string;
  description?: string;
  type?: string;
  image?: string; // HTTPS URL, max 2048 chars
  created_at: ISODate;
}

// Link (relationship)
export type EntityType = 'Character' | 'Faction' | 'Location' | 'Item' | 'Beat' | 'Moment';
export interface Link {
  id: ID;
  campaign_id: ID;
  from_id: ID;
  from_type: EntityType;
  to_id: ID;
  to_type: EntityType;
  alias?: string; // label shown in UI
  created_at: ISODate;
}

// Lore File
export interface LoreFile {
  id: ID;
  world_id: ID; // campaign ID
  sub_type: string; // must match a valid LORE_SUBTYPE key (see API reference)
  content: string; // plain text content
  file_name?: string;
  original_name?: string;
  file_type?: string; // e.g., "text/plain", "text/markdown"
  size?: number; // bytes
  token_count: number; // GPT-4 tokens (read-only)
  created_at: ISODate;
}
// Valid sub_type values: 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

// Ask (RAG)
export interface ChatMessage { role: 'system' | 'user' | 'assistant'; content: string; }
export interface AskRequest { campaign_id: ID; messages: ChatMessage[]; stream?: boolean; }
export interface AskChunk { id: string; type: 'delta' | 'done'; content?: string; }

Conventions

• Base URL: https://api.myarchivist.ai
• Authentication: All endpoints require x-api-key unless otherwise noted.
• Pagination: list endpoints accept page and size. The default size is server‑defined; clients should not assume a maximum.
• Timestamps: All dates are returned in ISO 8601 (UTC). Client UIs should localize for display.
• Idempotency: POST generally creates, PATCH updates via JSON Merge Patch where specified.
• Errors: JSON error body includes code, message, and optionally details.
• Filtering: Most list endpoints support simple filters (e.g., campaign_id, search, character_type).
• Image URLs: The image field for Characters, Items, Factions, and Locations must be an HTTPS URL (max 2048 characters). HTTP URLs are rejected with a validation error.

Read-Only Properties

Certain properties are system-managed and cannot be set through POST or PATCH requests. These fields appear in GET responses but are ignored if included in create/update operations.

• Campaigns: public, archived, created_at
• Sessions: public, created_at
• Characters: approved, created_at
• Locations, Factions, Items: pending, approved, created_at
• All entities: id, created_at

These properties are managed by the system based on application logic, user permissions, and moderation workflows.

Wikilinks & Relationships

Typical Workflow

A simple sequence: create a campaign, add a character, list sessions.

API_KEY="your-api-key"
BASE_URL="https://api.myarchivist.ai"

# 1) Create a campaign
curl -s -X POST \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First API Campaign",
    "description": "Created via API",
    "system": "D&D 5e"
  }' \
  "$BASE_URL/v1/campaigns"