Quickstart

Sign Up

Create an account to get your tenant, project, and API key. Use the form below or call the API directly with curl.

curl -X POST https://ai-story-engine.fly.dev/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

Save the api_key — this is your secret key for all API calls:

export ASE_API_KEY="sk_2628bbf8_589e3239..."
export PROJECT_ID="fac4e4b6-d786-4d93-9aff-963cd4afa852"

Create an NPC

NPCs are characters with personality, role, and world context that persist across interactions.

curl -X POST https://api.aistoryengine.dev/v1/projects/$PROJECT_ID/npcs \
  -H "Authorization: Bearer $ASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "npc_name": "Greta Ironforge",
    "npc_role": "tavern_keeper",
    "world_context": "A bustling medieval fantasy tavern called the Rusty Flagon",
    "personality_hints": ["gruff", "loyal", "secretly kind"]
  }'

Response:

{
  "npc_id": "5fab6c78-5590-450a-80ad-065ba6ed0cb2",
  "name": "Greta Ironforge",
  "project_id": "fac4e4b6-...",
  "status": "brainstorm",
  "session_id": "e452eb8b-...",
  "created_at": "2026-03-13T05:37:30Z"
}

export NPC_ID="5fab6c78-5590-450a-80ad-065ba6ed0cb2"

Generate Dialogue

Send a player action and generate a dialogue tree via the 6-node AI pipeline (ingest → propose → select → apply → render → evaluate). Generation is asynchronous — you get a session ID to poll.

curl -X POST https://api.aistoryengine.dev/v1/projects/$PROJECT_ID/npcs/$NPC_ID/generate \
  -H "Authorization: Bearer $ASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The player approaches the bar and asks about rumors of treasure beneath the tavern.",
    "pack": "game_narrative"
  }'

Response:

{
  "session_id": "fd7af465-6df3-4923-8111-024b07bb8525",
  "status": "accepted"
}

Poll for Results

Poll the session status endpoint until the generation completes (typically 15–25 seconds):

curl https://api.aistoryengine.dev/v1/sessions/$SESSION_ID/status \
  -H "Authorization: Bearer $ASE_API_KEY"

Response (when complete):

{
  "session_id": "fd7af465-...",
  "status": "completed",
  "result": {
    "session_id": "fd7af465-...",
    "status": "completed",
    "output": { ... }
  }
}

Export NPC Data

Export the NPC with its generated dialogue tree for use in your game engine:

curl -X POST https://api.aistoryengine.dev/v1/projects/$PROJECT_ID/npcs/$NPC_ID/export \
  -H "Authorization: Bearer $ASE_API_KEY"

Response:

{
  "npc_id": "5fab6c78-...",
  "name": "Greta Ironforge",
  "dialogue_tree": { ... },
  "metadata": {
    "role": "tavern_keeper",
    "personality_hints": ["gruff", "loyal", "secretly kind"]
  }
}

Set Up BYOK (Optional)

Use your own OpenAI/Anthropic API key instead of the shared platform key:

curl -X PUT https://api.aistoryengine.dev/v1/projects/$PROJECT_ID/byok \
  -H "Authorization: Bearer $ASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk-your-openai-key",
    "provider": "openai"
  }'