Getting started

From a new account to your first decision in a few minutes. You need a terminal with curl.

1. Create an account

Sign up at https://architect.eposyne.com/register. The hosted Director needs a Pro plan or higher; Free and Starter accounts are refused with 403 feature_not_in_plan. New accounts can earn a EUR 3 welcome credit by completing the survey shown after sign-up.

2. Add usage credits

Hosted decisions are paid from your account's usage credits. Open https://architect.eposyne.com/profile?section=credits, turn usage credits on, and buy credits. The minimum purchase is EUR 5 of credits, plus 21% Dutch VAT and the payment processing fee. Details are on Billing and limits.

3. Create a Director API key

Open https://architect.eposyne.com/profile?section=director-keys, give the key a name, and create it. The key starts with epd_ and is shown once. Copy it now. You can have up to 10 active keys.

4. Put the key in an environment variable

export EPOSYNE_API_KEY="epd_your_key_here"

$env:EPOSYNE_API_KEY = "epd_your_key_here"

5. Check that the service is up

This call needs no key.

curl https://director.eposyne.com/health

{"status": "ok"}

6. Make your first decision

Save this request as request.json. It asks whether the guards should pursue a thief or hold position, and lets the model change three variables.

{
  "schema": "eposyne.director.decision-request/v2",
  "ask": "Should the guards pursue the fleeing thief or hold position to protect the dignitary?",
  "variables": {
    "guard_stance": "patrol",
    "guard_morale": 50,
    "thief_distance": "50m",
    "dignitary_threat": "low",
    "reinforcements_available": true
  },
  "mutable": [
    {"name": "guard_stance", "allowed_values": ["patrol", "pursue", "hold", "alert"]},
    {"name": "guard_morale", "range": {"min": 0, "max": 100}},
    {"name": "dignitary_threat", "allowed_values": ["low", "medium", "high"]}
  ]
}

Send it:

curl -X POST "https://director.eposyne.com/v2/decide?rationale=true" \
  -H "Authorization: Bearer $EPOSYNE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

The reply is JSON too. rationale=true asks for a short reason per change, which helps while you try things out; leave it out in a shipped game, where nobody reads it. The text of a rationale differs from call to call, and the model may change fewer variables than in this example, or none.

{
  "schema": "eposyne.director.decision-response/v2",
  "changes": [
    {
      "name": "guard_stance",
      "value": "hold",
      "rationale": "Dignitary protection takes priority over one thief."
    },
    {
      "name": "dignitary_threat",
      "value": "high",
      "rationale": "A visible theft nearby raises the threat level."
    }
  ]
}

Each entry of changes names one of your mutable variables, gives a new value that satisfies the rule you declared for it (with the same JSON type as the current value), and, because you asked, adds a short rationale. An empty changes array is a normal answer that means "no suggestions". Treat it as the cue to run your scripted behavior.

Add -i to the curl command to see the response headers, including X-LLM-Provider, X-LLM-Model, and the token counts.

The decide request page describes every member, the optional operations, validation, and metadata, and the limits.

7. Check what it cost

curl https://director.eposyne.com/v2/usage/me \
  -H "Authorization: Bearer $EPOSYNE_API_KEY"

{
  "month": "2026-09",
  "spent_eur": 1.25,
  "cap_eur": 10,
  "remaining_eur": 8.75,
  "resets_at": "2026-10-01T00:00:00Z"
}

spent_eur is what the account has spent on decisions this month, in euro. Read it after a decision. Models and usage explains every field.

8. See which models you can use

curl https://director.eposyne.com/v2/models \
  -H "Authorization: Bearer $EPOSYNE_API_KEY"

The list includes the price of each model. You do not have to choose: without a selection Director uses its default.

9. Going further: events, Plots, and Memory

A decision knows only what is in its request. To let Director follow your story, send it what happens in your game, and switch on two modules: Plots tracks story arcs, and Memory gives characters a past. Both are off by default. 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, so read Policy first.

• Events: send what happens, in batches.
• Policy: the settings and what they cost.
• Plots: upload arcs and read the verdict in a decision.
• Memory: what characters believe.

If something fails

• 401: the key is missing, mistyped, or revoked. The header must read Authorization: Bearer epd_....
• 429: your balance is under EUR 1.00, usage credits are off, or this month's limit is reached. Read the detail text.
• 415: the Content-Type is missing or is not application/json. Director takes JSON only.

The full list is on Errors and retries.