API reference

Runs

Available from Phases 3 to 4b

The HTTP API is not live yet. These endpoints are the planned contract, generated from the same schema the server will use. Paths and fields can still change before they ship.

List run summaries, without state.

GET/api/v1/runs

Authorization

AuthorizationBearer <token>

An app token (sk_live_, sk_test_, pk_live_), a browser token (a 5-minute ES256 JWT) or an agent token (sa_live_).

In: header

Query Parameters

set?string
Length1 <= length
version?integer
Range0 < value <= 9007199254740991
channel?string

Value in

  • "production"
  • "staging"
  • "pinned"
  • "draft"
source?string

Value in

  • "console"
  • "playground"
  • "api"
  • "embed"
  • "extension"
  • "mcp"
  • "eval"
  • "cli"
  • "ingest"
status?string

Value in

  • "ok"
  • "error"
  • "rate_limited"
  • "quota_exceeded"
band?string

Value in

  • "high"
  • "medium"
  • "low"
action?string

Value in

  • "auto"
  • "review"
  • "fallback"
  • "escalate_to_llm"
token?string
Length1 <= length <= 200
from?string
Formatdate-time
to?string
Formatdate-time
limit?integer
Range1 <= value <= 200
Default50
cursor?string
Length1 <= length

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/runs"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "setId": "83e19bc1-5428-42b5-88ea-b28354e481f3",      "versionId": "14707576-2549-4848-82ed-f68f8a1b47c7",      "channel": "production",      "rollout": "inactive",      "source": "console",      "status": "ok",      "runBand": "high",      "overallAction": "auto",      "route": "string",      "modelRequested": "string",      "modelResolved": "string",      "latencyMs": 0,      "inputTokens": 0,      "outputTokens": 0,      "systemOneCostMicroUsd": -9007199254740991,      "counterfactualMicroUsd": -9007199254740991,      "savingsMicroUsd": -9007199254740991,      "errorCode": "string",      "actorTokenId": "edf76508-99ba-42c4-85d0-a88118af2a69",      "actorTokenName": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "nextCursor": "string"}

Read one run with its stage payloads, answers and review items.

GET/api/v1/runs/{id}

Authorization

AuthorizationBearer <token>

An app token (sk_live_, sk_test_, pk_live_), a browser token (a 5-minute ES256 JWT) or an agent token (sa_live_).

In: header

Path Parameters

id*string
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "setId": "83e19bc1-5428-42b5-88ea-b28354e481f3",  "versionId": "14707576-2549-4848-82ed-f68f8a1b47c7",  "channel": "production",  "rollout": "inactive",  "source": "console",  "status": "ok",  "runBand": "high",  "overallAction": "auto",  "route": "string",  "modelRequested": "string",  "modelResolved": "string",  "latencyMs": 0,  "inputTokens": 0,  "outputTokens": 0,  "systemOneCostMicroUsd": -9007199254740991,  "counterfactualMicroUsd": -9007199254740991,  "savingsMicroUsd": -9007199254740991,  "errorCode": "string",  "actorTokenId": "edf76508-99ba-42c4-85d0-a88118af2a69",  "actorTokenName": "string",  "createdAt": "2019-08-24T14:15:22Z",  "stages": [    {      "id": "string",      "skipped": true,      "calls": [        {          "modelResolved": "string",          "provider": "typesafe",          "providerCostUsd": 0,          "typesafeRequestId": "string",          "inputTokens": 0,          "outputTokens": 0,          "latencyMs": 0        }      ]    }  ],  "checks": {    "property1": true,    "property2": true  },  "answers": "string",  "decisions": "string",  "warnings": [    "string"  ],  "state": "string",  "reviewItems": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "decisionId": "string",      "kind": "action",      "reason": "action",      "band": "high",      "status": "open",      "resolution": "string",      "resolvedAt": "2019-08-24T14:15:22Z"    }  ]}

Record a run made by a standalone export, so the ledger, review and calibration keep working.

POST/api/v1/runs/ingest

Authorization

AuthorizationBearer <token>

An app token (sk_live_, sk_test_, pk_live_), a browser token (a 5-minute ES256 JWT) or an agent token (sa_live_).

In: header

Header Parameters

Idempotency-Key?string

Required for app and agent tokens on mutations. A replay within 24 hours returns the stored response.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/api/v1/runs/ingest" \  -H "Content-Type: application/json" \  -d '{    "setRef": "string",    "version": 1,    "model": "string",    "answers": {      "property1": {        "type": "noul",        "noul": 0,        "property1": null,        "property2": null      },      "property2": {        "type": "noul",        "noul": 0,        "property1": null,        "property2": null      }    },    "usage": {      "input_tokens": 0,      "output_tokens": 0,      "property1": null,      "property2": null    },    "latencyMs": 0,    "stateHash": "string"  }'
null

Bandwise is an independent product built on TypeSafe's System One models. It is not TypeSafe's documentation. For the System One models themselves, see docs.typesafe.ai.

Question sets

Previous Page

Current actor

Next Page