# Collaborative Mythology API

The Collaborative Mythology API exposes living story worlds co-created by
community contributors. Each world blueprint captures core themes, active
quests, contributor protocols, and digital artifacts to support ethical
stewardship of collective lore.

## Endpoints

### `GET /v1/mythology/collaborations`

Returns the catalogue of collaborative mythology worlds with discovery metadata.

> **BFF proxy:** Request via the BFF (e.g.,
> `https://api.example.org/v1/mythology/collaborations`) to leverage caching,
> observability, and graceful fallbacks when the content service is unavailable.

```json
{
  "worlds": [
    {
      "slug": "mythic-archipelago",
      "title": "Mythic Archipelago",
      "tagline": "Polyphonic oceanic cosmology woven across ancestral seaways",
      "coreThemes": [
        "Oceanic lineage weaving",
        "Birth-right reparations to submerged civilizations",
        "Guardian covenants with sentient currents"
      ],
      "activeQuests": [
        "Unseal the Whale Song Archive to renegotiate migration paths",
        "Reforge delicate peace between tidecallers and storm-harvesters"
      ],
      "contributorCount": 128,
      "coreBiome": "Interconnected coral temples and floating story-barges"
    }
  ],
  "metadata": {
    "count": 3,
    "generated_at": "2025-01-01T00:00:00.000Z",
    "documentation": "docs/collaborative-mythology.md",
    "sources": [
      "MythWeaver.CommunityWorldbuildingArchives",
      "StoryCodex.SharedLoreNetworks"
    ]
  }
}
```

### `GET /v1/mythology/collaborations/:slug`

Retrieves the complete blueprint for a collaborative mythology world including
contributor protocols, narrative arcs, and integration rituals. Slug options
include `mythic-archipelago`, `starforged-diaspora`, and
`dreamtime-convergence`.

```json
{
  "slug": "mythic-archipelago",
  "title": "Mythic Archipelago",
  "tagline": "Polyphonic oceanic cosmology woven across ancestral seaways",
  "era": "Tidal Cycle 7 • Post-deluge Renegotiation",
  "primaryBiome": "Interconnected coral temples and floating story-barges",
  "coreThemes": [
    "Oceanic lineage weaving",
    "Birth-right reparations to submerged civilizations",
    "Guardian covenants with sentient currents"
  ],
  "contributorSummaries": [
    {
      "name": "Kaia “Tide-Singer” Atua",
      "role": "Cultural memory bearer",
      "highlights": [
        "Custodian of the shell-code chronicle",
        "Leads ritual accountability circles each equinox"
      ]
    }
  ],
  "collaborationProtocols": {
    "onboarding": {
      "steps": [
        "Submit lineage intention and ancestral consent statement",
        "Attend tide-dream incubation session with elder steward",
        "Offer reciprocal guardianship pledge before joining codex"
      ]
    }
  },
  "narrativeArcs": [
    {
      "id": "tidal-reclamation",
      "title": "Tidal Reclamation Accord",
      "milestones": [
        "Gather 13 lost shell-keys across archipelago",
        "Convince leviathan emissaries to lift navigation embargo",
        "Anchor reparations ceremonies across three moon cycles"
      ]
    }
  ],
  "worldBuildingArtifacts": {
    "sharedCodex": [
      "Sea-voyager dialect atlas",
      "Floating temple schematics woven with tide memory"
    ]
  },
  "integrationRituals": [
    {
      "name": "Moon-Swell Accountability Gathering",
      "frequency": "Every 28 days",
      "digitalAnchors": [
        "Holographic ripple ledger",
        "Voiceprint gratitude archive"
      ]
    }
  ]
}
```

## TypeScript SDK Integration

Typed helpers are available within the Lilith TypeScript SDK.

```ts
import { APIClient } from '@lilith/sdk-ts';

const client = new APIClient({ baseUrl: 'https://api.example.org' });

// List collaborative mythology worlds
const catalogue = await client.listCollaborativeMythologyWorlds();
catalogue.worlds.forEach((world) => {
  console.log(world.slug, world.contributorCount);
});

// Fetch a specific world blueprint
const archipelago =
  await client.getCollaborativeMythologyWorld('mythic-archipelago');
console.log(archipelago.collaborationProtocols.onboarding.steps[0]);
```

Use the detail endpoint to surface protocols, arcs, and rituals in product
experiences while maintaining contributor accountability and stewardship
context.
