Interactive API Explorer

Browse the full OpenAPI specification with an interactive explorer. You can try endpoints directly from the browser.

Authentication

AI Story Engine uses API key authentication. Include your key in the Authorization header of every request:

Authorization: Bearer sk_your_secret_key_here

Key Types

Key Prefix	Type	Usage	Permissions
pk_	Publishable	Client-side (browsers, game clients)	Read-only: list NPCs, read dialogue history
sk_	Secret	Server-side only	Full access: create, generate, delete, export

Base URL

https://api.aistoryengine.dev/v1

All endpoints are versioned under /v1. When breaking changes are introduced, they will ship under a new version prefix. The current version will continue to work for at least 12 months after a new version is released.

Core Endpoints

Projects

Method	Endpoint	Description
POST	/v1/projects	Create a new project
GET	/v1/projects	List all projects
GET	/v1/projects/{project_id}	Get project details
PATCH	/v1/projects/{project_id}	Update project settings
DELETE	/v1/projects/{project_id}	Delete project and all associated data

NPCs

Method	Endpoint	Description
POST	/v1/projects/{project_id}/npcs	Create an NPC with personality and knowledge
GET	/v1/projects/{project_id}/npcs	List all NPCs in a project
GET	/v1/projects/{project_id}/npcs/{npc_id}	Get NPC details including knowledge graph stats
PATCH	/v1/projects/{project_id}/npcs/{npc_id}	Update NPC personality, knowledge, or backstory
DELETE	/v1/projects/{project_id}/npcs/{npc_id}	Delete an NPC

Generation

Method	Endpoint	Description
POST	/v1/projects/{project_id}/generate	Generate dialogue or narrative response
POST	/v1/projects/{project_id}/generate/batch	Generate multiple responses in parallel
GET	/v1/projects/{project_id}/events	List narrative events (event log)
GET	/v1/projects/{project_id}/events/{event_id}	Get event details with provenance metadata

Export

Method	Endpoint	Description
GET	/v1/projects/{project_id}/export/unity	Export as Unity DialogueTree JSON
GET	/v1/projects/{project_id}/export/json	Export raw narrative data as JSON
GET	/v1/projects/{project_id}/export/csv	Export dialogue lines as CSV (localization)

Knowledge Graph

Method	Endpoint	Description
GET	/v1/projects/{project_id}/kg/entities	List knowledge graph entities
GET	/v1/projects/{project_id}/kg/relationships	List knowledge graph relationships
POST	/v1/projects/{project_id}/kg/query	Query the knowledge graph (structured filter)

Rate Limiting

Rate limits are applied per API key and vary by plan:

Plan	Requests / minute	Generation calls / minute	Burst limit
Free	60	10	20
Pro	600	100	200
Enterprise	Custom	Custom	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1710324060

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

Error Responses

All errors follow a consistent JSON structure:

{
  "error": {
    "type": "validation_error",
    "message": "NPC personality.traits must be a non-empty array",
    "field": "personality.traits",
    "request_id": "req_abc123"
  }
}

HTTP Status	Error Type	Description
400	validation_error	Invalid request body or parameters
401	authentication_error	Missing or invalid API key
403	permission_error	Key does not have required permissions
404	not_found	Resource does not exist
429	rate_limit_error	Rate limit exceeded
500	internal_error	Server error (include request_id in support requests)

Pagination

List endpoints support cursor-based pagination:

GET /v1/projects/proj_a1b2c3d4/npcs?limit=20&after=npc_x7y8z9

Parameter	Type	Default	Description
limit	integer	20	Number of items to return (max 100)
after	string	—	Cursor: return items after this ID
before	string	—	Cursor: return items before this ID

The response includes a has_more boolean and the cursor values for the next page:

{
  "data": [...],
  "has_more": true,
  "next_cursor": "npc_w5x6y7"
}