API Reference

All endpoints use the base URL https://api.thelivingchronicle.com. Authentication is via Authorization: Bearer YOUR_API_KEY header.

Endpoints

Method	Path	Description	Auth
GET	/api/companion/v1/chapters/current	Get the current (latest) chapter summary	API Key
GET	/api/companion/v1/chapters/:id	Get a specific chapter by ID	API Key
GET	/api/companion/v1/characters	List all named characters with faction and status	API Key
GET	/api/companion/v1/locations	List all known locations with controlling faction	API Key
GET	/api/companion/v1/factions	List all factions with member counts and territory	API Key
GET	/api/companion/v1/territories	Get current territory map with faction control percentages	API Key
POST	/api/companion/v1/query	Natural language query against the chronicle knowledge base	API Key
GET	/api/companion/v1/health	Health check — returns API status and version	None

Example Responses

GET /chapters/current

{
  "id": "ch_s2_047",
  "seasonNumber": 2,
  "chapterNumber": 47,
  "title": "The Ember Summit",
  "summary": "Representatives of all four factions gather...",
  "publishedAt": "2026-04-09T06:00:00Z",
  "voteCount": 12847,
  "wordCount": 2340,
  "decisions": [
    {
      "id": "dec_047_a",
      "text": "Accept the Iron Covenant's terms",
      "votePercent": 34.2
    },
    {
      "id": "dec_047_b",
      "text": "Propose a counter-alliance with Dawn",
      "votePercent": 41.8
    },
    {
      "id": "dec_047_c",
      "text": "Walk away from the summit",
      "votePercent": 24.0
    }
  ]
}

GET /factions

{
  "factions": [
    {
      "id": "obsidian",
      "name": "Iron Covenant",
      "memberCount": 4521,
      "territoryPercent": 31.2,
      "philosophy": "Order through control. Stability through strength."
    },
    {
      "id": "verdant",
      "name": "Ashen Communion",
      "memberCount": 3892,
      "territoryPercent": 27.8,
      "philosophy": "Growth through adaptation. Wisdom through patience."
    }
  ]
}

POST /query

// POST /api/companion/v1/query
{
  "query": "What happened at the Battle of Ashveil?",
  "maxTokens": 500,
  "context": "chapters"
}

// Response
{
  "answer": "The Battle of Ashveil occurred in Season 1, Chapter 23...",
  "sources": [
    { "type": "chapter", "id": "ch_s1_023", "title": "The Fall of Ashveil" },
    { "type": "chapter", "id": "ch_s1_024", "title": "Aftermath" }
  ],
  "tokensUsed": 342
}