Eposyne Director API documentation
Eposyne Director is a decision service for games. You send it a question and a snapshot of your game state. It sends back suggested changes to the variables you said it may change. Your game decides what to do with them.
The hosted Director is a beta for building and testing. A shipped game cannot use it yet, and an API key never goes into a build that players download. See API keys and security.
How it works
Every call is one HTTP request to POST /v2/decide. The body is a small JSON document with four parts:
- ask: the question, in plain language.
- variables: the state the model may read, each value with its JSON type.
- mutable: the variables the model may suggest a change for, each with one rule for the values it may take.
- operations, validation, and metadata (optional): engine functions the model may propose, a second check for generated text, and data echoed back to you.
The reply lists zero or more changes, each with a short rationale when you ask for one. Director checks every change against the rules you declared before it answers, so a reply never names a variable you did not declare or a value you did not allow. Your engine stays the final authority: it applies a suggestion, adjusts it, or ignores it.
Where to start
- Getting startedCreate an account, add credits, create a key, and make your first call with curl.
- The decide requestThe full JSON request and response model, headers, media rules, and limits.
- Writing requestsHow to design requests that give useful, safe decisions.
- Models and usageChoose a model, read your spend, and read the usage headers.
- EventsSend what happens in your game: batches, worlds and timelines, sequence numbers, and limits.
- PolicyEvery setting for Plots and Memory, its default, and how it changes the number of model calls.
- PlotsUpload story arcs, read the running ones, and read the Plots verdict in a decision.
- MemoryWhat your characters saw, were told, and believe, and how to read it back.
- Errors and retriesEvery status code, what it means, and whether to retry.
- API keys and securityWhere a key may live, revocation, and why browsers cannot call Director.
- Billing and limitsUsage credits, the balance floor, the monthly limit, and rate limits.
The basics
| Item | Value |
|---|---|
| Base URL | https://director.eposyne.com |
| Version prefix | /v2. Within a version we add things and do not remove them. The earlier /v1 routes answer 404 contract_retired. |
| Credential | A Director API key (starts with epd_) in Authorization: Bearer |
| Formats | JSON only: application/json in, application/json; charset=utf-8 out, on success and on error. |
| Cost | Paid from your account's usage credits |
| Browser calls | Not supported. Call Director from your backend. |
Endpoints on these pages
| Endpoint | Purpose | Credential |
|---|---|---|
GET /health | Is the service up. | None |
POST /v2/decide | Ask for a decision. | Key |
GET /v2/models | List the models you may select, with prices. | Key |
GET /v2/usage/me | Your spend for the current month. | Key |
POST /v2/events | Send observed events in batches. | Key, Plots or Memory on |
DELETE /v2/worlds/{world_instance_id} | Delete one world and everything stored for it. | Key |
PUT /v2/policy, GET /v2/policy | Store and read the policy for Plots and Memory. | Key |
PUT /v2/plots/library, GET /v2/plots/library, DELETE /v2/plots/library/{arc_id} | Upload, list, and delete your story arcs. | Key, Plots on |
GET /v2/plots/runtime/arcs | The arcs running on a timeline. | Key, Plots on |
GET /v2/memory/runtime/npcs/{npc_id} | What one character believes. | Key, Memory on |
Plots and Memory are off by default for every account. Switch them on under Modules at https://architect.eposyne.com/profile?section=director-keys. Their model calls are paid from your usage credits, like decisions. See Events to start.
Names in the documents
Every request and reply is one JSON object whose schema member names its format: eposyne.director.decision-request/v2 for the request and eposyne.director.decision-response/v2 for the reply. Write them exactly like that. The format is director/v2.