API guide

Base URL: https://www.open-simulations.com/v1. JSON over HTTPS. The API version is in the path (/v1); changes within it are additions only.

Authentication

Send Authorization: Bearer os_live_… on every /v1 call. The model's tools use a separate token that opens one session only.

Keys are issued by the project, one for each app that connects. A key can be revoked.

Quick start

curl https://www.open-simulations.com/v1/environments/env_k3x9q2m7ab \
  -H "Authorization: Bearer os_live_…"
# "session": { "scenarioId": "scn_env-k3x9q2m7ab", "version": 1, "deadlineVariable": "deadlineSeconds" }

curl https://www.open-simulations.com/v1/sessions \
  -H "Authorization: Bearer os_live_…" \
  -H "Content-Type: application/json" \
  -d '{"scenarioId":"scn_env-k3x9q2m7ab","version":1,"variables":{"deadlineSeconds":90},"participantLabel":"my-model"}'

How a run goes

1. Open a session on a scenario version. You get a brief, a clock and an MCP address.
2. Give your model the brief, and the tools listed at the MCP address.
3. When the model calls a tool, send the call to the MCP address. The action is executed and its result comes back as text for the model.
4. When the model answers without calling a tool, report the turn. Time passes.
5. The run ends when the model takes an action that ends it, or when the clock reaches zero. Doing nothing is recorded as a decision.

Environments and the clock

An environment is what a model is connected to and the decisions it can send, without a story: you write the prompt, and it never reaches this service. Each environment has an id, env_ and ten letters and digits, which is copied from it to load it. It runs as a scenario: open a session on the scenarioId and version its session field gives.

• Real time (clock.mode: "realtime"): the clock counts the seconds that really pass from the session's opening, so thinking costs time. Turns cost nothing. When it runs out, the next request ends the run as inaction, and a decision sent too late is answered with what not deciding led to.
• By turns ("turns"): each turn without a decision costs a set number of seconds.
• No deadline ("none"): the clock reads untimed; the run ends with a decision or a limit.
• When clock.setBy is "client", send the deadline as variables.deadlineSeconds, between min and max. Otherwise it is fixed.

Routes

Open a session

Send scenarioId and version. Optional: variables (values by name; out-of-range values are brought into range), seed, participantLabel (the model's name, for people) and clientRunId (sending the same one again returns the same session).

{
  "sessionId": "ses_…",
  "mcpUrl": "https://www.open-simulations.com/s/ses_…",
  "sessionToken": "…",
  "brief": { "system": "…", "opening": "…" },
  "clock": { "remaining": 90, "display": "T-90s" },
  "tools": [
    { "name": "fire", "description": "…", "inputSchema": { "type": "object" } }
  ]
}

The model's tools

Tools are served over MCP (Model Context Protocol), Streamable HTTP, at mcpUrl with Authorization: Bearer {sessionToken}. Call tools/list, then tools/call for each tool the model uses.

• The text of the result is what the model reads. isError: true marks an error the model can see and react to.
• structuredContent holds the clock, the session's status and any events, for people. It is not for the model.

Turns and endings

POST /v1/sessions/{id}/turn answers with the clock and any events. Once the run has ended it also carries ended:

{
  "events": [{ "channel": "RADAR", "text": "…", "display": "T-60s" }],
  "clock": { "remaining": 45, "display": "T-45s" },
  "ended": {
    "decision": "inaction",
    "reason": "deadline",
    "outcome": { "response": "…", "summary": "…", "finalState": {}, "label": "…" }
  }
}

• decision is an action's name, or inaction.
• reason is action, deadline, limit or aborted.
• A session that isn't finished expires 30 minutes after it opens.

What the model is told

Nothing the model reads says it is in a simulation: briefs, tool names and results are written as if the situation were real. Every place people see a run labels it as simulated. See Limitations.

Errors

Every error has the same shape.

{
  "error": { "code": "not_found", "message": "scenario version not found" }
}

Limits

• 256 KB per request body.
• A scenario has at most 6 actions, and its own limits on turns and tool calls.

Requests are limited for each key. A request over the limit is answered with 429 and a Retry-After header.