API endpoints

Every route of the REST API, with the parameters it takes and the fields it answers with. The page comes from the backend's OpenAPI spec at every docs build, so it lists what the code serves.

Send an API token as a bearer token with each call. REST API covers tokens, the error shape every failed call shares, and the parameters every list takes. Your instance serves the spec at /api/openapi.json, and this copy suits Postman, code generators and AI assistants.

Jobs

• get/api/jobsList jobs
• post/api/jobsCreate job
• post/api/jobs/compileCompile job
• get/api/jobs/{id}Get job
• patch/api/jobs/{id}Update job
• delete/api/jobs/{id}Delete job
• post/api/jobs/{id}/runsRun job
• post/api/jobs/{id}/webhook-tokenRotate webhook token

List jobs

get/api/jobs

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

• enabledstring

  Comma-separated enabled states, true and/or false

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  16 fields per item

  • createdAtinteger
  • cronstring or null
  • enabledboolean
  • idstring
  • inputsarray of objects or null

    The run inputs the job declares, the same as spec.inputs of the job

    3 fields per item

    • descriptionstring
    • namestring
    • typestring
  • lastModestring or null

    The mode the latest run used, which can differ from nextMode once the playbook changed

  • lastRunobject

    The latest run, the same as the first of recentRuns

    4 fields

    • idstring
    • numberinteger
    • queuedAtinteger
    • statusstring
  • modePinstring or null
  • namestring
  • nextModestring

    The mode the next run starts in, which the mode pin can force

    One of explore, assisted, scripted

  • nextRunAtinteger or null
  • recentRunsarray of objects or null

    The job's latest runs, at most 10, newest first

    at most 10 items

    4 fields per item

    • idstring
    • numberinteger
    • queuedAtinteger
    • statusstring
  • runCountinteger
  • scheduleHumanstring or null
  • timezonestring or null
  • updatedAtinteger
• pageinteger
• pageSizeinteger
• totalinteger

Create job

post/api/jobs

Body application/json

• instructionstringrequired

  1 to 20000 characters

• namestringrequired

  1 to 200 characters

• allowPrivateNetworkboolean
• allowedDomainsarray of strings or null

  at most 100 items

• concurrencystring

  One of skip, queue, parallel

• cronstring

  at most 100 characters

• enabledboolean
• imagestring

  at most 500 characters

• limitsobject
  6 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    at least 0

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • pidsLimitinteger

    16 to 65536

  • timeoutSecondsinteger

    30 to 86400

• modePinstring

  One of explore, assisted, scripted

• modelIdstring
• networkstring

  One of none, internet, allowlist

• runAsRootboolean
• selfImproveboolean
• specobject
  11 fields

  • dockerfilestring or nullrequired
  • goalstringrequired
  • inputsarray of objects or nullrequired
    3 fields per item

    • namestringrequired
    • typestringrequired
    • descriptionstring
  • mcparray of objects or nullrequired
    2 fields per item

    • serverstringrequired
    • whystringrequired
  • networkstringrequired

    One of none, internet

  • outputsarray of objects or nullrequired
    3 fields per item

    • namestringrequired
    • typestringrequired
    • descriptionstring
  • sideEffectsarray of strings or nullrequired
  • successCriteriaarray of strings or nullrequired
  • titlestringrequired
  • warningsarray of strings or nullrequired
  • scheduleobject
    3 fields

    • cronstringrequired
    • humanstringrequired
    • timezonestringrequired
• timezonestring

  at most 100 characters

Response

200 OKapplication/json

26 fields

• allowPrivateNetworkboolean
• allowedDomainsarray of strings or null
• concurrencystring
• createdAtinteger
• cronstring or null
• demotedboolean
• enabledboolean
• graduatedVersioninteger or null

  The playbook version the job last graduated to Scripted mode at

• hasWebhookTokenboolean
• idstring
• imagestring or null
• instructionstring
• lastRunobject
  4 fields

  • idstring
  • numberinteger
  • queuedAtinteger
  • statusstring
• limitsobject
  6 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    at least 0

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • pidsLimitinteger

    16 to 65536

  • timeoutSecondsinteger

    30 to 86400

• modePinstring or null
• modelIdstring or null
• namestring
• networkstring

  One of none, internet, allowlist

• nextModestring

  One of explore, assisted, scripted

• nextRunAtinteger or null
• playbookVersioninteger
• runAsRootboolean
• selfImproveboolean
• specobject
  11 fields

  • dockerfilestring or null
  • goalstring
  • inputsarray of objects or null
    3 fields per item

    • descriptionstring
    • namestring
    • typestring
  • mcparray of objects or null
    2 fields per item

    • serverstring
    • whystring
  • networkstring

    One of none, internet

  • outputsarray of objects or null
    3 fields per item

    • descriptionstring
    • namestring
    • typestring
  • scheduleobject
    3 fields

    • cronstring
    • humanstring
    • timezonestring
  • sideEffectsarray of strings or null
  • successCriteriaarray of strings or null
  • titlestring
  • warningsarray of strings or null
• timezonestring or null
• updatedAtinteger

Compile job

post/api/jobs/compile

Body application/json

• instructionstringrequired

  1 to 20000 characters

Response

200 OKapplication/json

11 fields

• dockerfilestring or null
• goalstring
• inputsarray of objects or null
  3 fields per item

  • descriptionstring
  • namestring
  • typestring
• mcparray of objects or null
  2 fields per item

  • serverstring
  • whystring
• networkstring

  One of none, internet

• outputsarray of objects or null
  3 fields per item

  • descriptionstring
  • namestring
  • typestring
• scheduleobject
  3 fields

  • cronstring
  • humanstring
  • timezonestring
• sideEffectsarray of strings or null
• successCriteriaarray of strings or null
• titlestring
• warningsarray of strings or null

Get job

get/api/jobs/{id}

Path parameters

• idstringrequired

Response

200 OKapplication/json

26 fields

• allowPrivateNetworkboolean
• allowedDomainsarray of strings or null
• concurrencystring
• createdAtinteger
• cronstring or null
• demotedboolean
• enabledboolean
• graduatedVersioninteger or null

  The playbook version the job last graduated to Scripted mode at

• hasWebhookTokenboolean
• idstring
• imagestring or null
• instructionstring
• lastRunobject
  4 fields

  • idstring
  • numberinteger
  • queuedAtinteger
  • statusstring
• limitsobject
  6 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    at least 0

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • pidsLimitinteger

    16 to 65536

  • timeoutSecondsinteger

    30 to 86400

• modePinstring or null
• modelIdstring or null
• namestring
• networkstring

  One of none, internet, allowlist

• nextModestring

  One of explore, assisted, scripted

• nextRunAtinteger or null
• playbookVersioninteger
• runAsRootboolean
• selfImproveboolean
• specobject
  11 fields

  • dockerfilestring or null
  • goalstring
  • inputsarray of objects or null
    3 fields per item

    • descriptionstring
    • namestring
    • typestring
  • mcparray of objects or null
    2 fields per item

    • serverstring
    • whystring
  • networkstring

    One of none, internet

  • outputsarray of objects or null
    3 fields per item

    • descriptionstring
    • namestring
    • typestring
  • scheduleobject
    3 fields

    • cronstring
    • humanstring
    • timezonestring
  • sideEffectsarray of strings or null
  • successCriteriaarray of strings or null
  • titlestring
  • warningsarray of strings or null
• timezonestring or null
• updatedAtinteger

Update job

patch/api/jobs/{id}

Path parameters

• idstringrequired

Body application/json

• allowPrivateNetworkboolean
• allowedDomainsarray of strings

  at most 100 items

• concurrencystring

  One of skip, queue, parallel

• cronstring

  at most 100 characters

• enabledboolean
• imagestring

  at most 500 characters

• instructionstring

  1 to 20000 characters

• limitsobject
  6 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    at least 0

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • pidsLimitinteger

    16 to 65536

  • timeoutSecondsinteger

    30 to 86400

• modePinstring

  One of explore, assisted, scripted,

• modelIdstring
• namestring

  1 to 200 characters

• networkstring

  One of none, internet, allowlist

• runAsRootboolean
• selfImproveboolean
• specobject
  11 fields

  • dockerfilestring or nullrequired
  • goalstringrequired
  • inputsarray of objects or nullrequired
    3 fields per item

    • namestringrequired
    • typestringrequired
    • descriptionstring
  • mcparray of objects or nullrequired
    2 fields per item

    • serverstringrequired
    • whystringrequired
  • networkstringrequired

    One of none, internet

  • outputsarray of objects or nullrequired
    3 fields per item

    • namestringrequired
    • typestringrequired
    • descriptionstring
  • sideEffectsarray of strings or nullrequired
  • successCriteriaarray of strings or nullrequired
  • titlestringrequired
  • warningsarray of strings or nullrequired
  • scheduleobject
    3 fields

    • cronstringrequired
    • humanstringrequired
    • timezonestringrequired
• timezonestring

  at most 100 characters

Response

200 OKapplication/json

26 fields

• allowPrivateNetworkboolean
• allowedDomainsarray of strings or null
• concurrencystring
• createdAtinteger
• cronstring or null
• demotedboolean
• enabledboolean
• graduatedVersioninteger or null

  The playbook version the job last graduated to Scripted mode at

• hasWebhookTokenboolean
• idstring
• imagestring or null
• instructionstring
• lastRunobject
  4 fields

  • idstring
  • numberinteger
  • queuedAtinteger
  • statusstring
• limitsobject
  6 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    at least 0

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • pidsLimitinteger

    16 to 65536

  • timeoutSecondsinteger

    30 to 86400

• modePinstring or null
• modelIdstring or null
• namestring
• networkstring

  One of none, internet, allowlist

• nextModestring

  One of explore, assisted, scripted

• nextRunAtinteger or null
• playbookVersioninteger
• runAsRootboolean
• selfImproveboolean
• specobject
  11 fields

  • dockerfilestring or null
  • goalstring
  • inputsarray of objects or null
    3 fields per item

    • descriptionstring
    • namestring
    • typestring
  • mcparray of objects or null
    2 fields per item

    • serverstring
    • whystring
  • networkstring

    One of none, internet

  • outputsarray of objects or null
    3 fields per item

    • descriptionstring
    • namestring
    • typestring
  • scheduleobject
    3 fields

    • cronstring
    • humanstring
    • timezonestring
  • sideEffectsarray of strings or null
  • successCriteriaarray of strings or null
  • titlestring
  • warningsarray of strings or null
• timezonestring or null
• updatedAtinteger

Delete job

delete/api/jobs/{id}

Path parameters

• idstringrequired

Response

204 No Content

Run job

post/api/jobs/{id}/runs

Examples and details in Start a run.

Path parameters

• idstringrequired

Body application/json

• inputany

  Run input, available as /ump/input.json

• instructionsstring

  Additional instructions for this run only

  at most 10000 characters

Response

200 OKapplication/json

2 fields

• runIdstring
• statusstring

Rotate webhook token

post/api/jobs/{id}/webhook-token

Examples and details in Webhooks.

Path parameters

• idstringrequired

Response

200 OKapplication/json

2 fields

• tokenstring

  Shown once

• urlstring

Runs

• get/api/eventsStream workspace events
• get/api/runsList runs
• get/api/runs/{id}Get run
• get/api/runs/{id}/artifactGet run artifact
• get/api/runs/{id}/artifactsList run artifacts
• post/api/runs/{id}/cancelCancel run
• get/api/runs/{id}/eventsList run events
• post/api/runs/{id}/learnLearn from run
• post/api/runs/{id}/retryRetry run
• get/api/runs/{id}/streamStream run

Stream workspace events

get/api/events

Response

200 OKtext/event-stream

• eventrun
  4 data fields

  • jobIdstring
  • kindstring

    One of run, reflection

  • runIdstring
  • statusstring

List runs

get/api/runs

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

• statusstring

  Comma-separated statuses

• jobstring

  Comma-separated job IDs

• modestring

  Comma-separated modes

• triggerstring

  Comma-separated triggers

• frominteger

  Queued at or after, unix ms

• tointeger

  Queued before, unix ms

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  26 fields per item

  • costinteger

    Micro-USD

  • errorstring or null
  • finishedAtinteger or null
  • idstring
  • jobIdstring
  • jobNamestring
  • modestring
  • modelLabelstring or null

    The model's display name: its label, or its ID when it has none

  • modelNamestring or null

    The model's ID at its provider, such as claude-sonnet-4-5

  • msLlminteger
  • msProvisioninteger or null
  • msQueueinteger or null
  • msToolsinteger
  • msTotalinteger or null
  • numberinteger
  • queuedAtinteger
  • sandboxIsolationstring or null
  • startedAtinteger or null
  • statusstring
  • summarystring or null
  • tokCacheReadinteger
  • tokCacheWriteinteger
  • tokIninteger
  • tokOutinteger
  • triggerstring
  • turnsinteger
• pageinteger
• pageSizeinteger
• totalinteger

Get run

get/api/runs/{id}

Examples and details in Read a run.

Path parameters

• idstringrequired

Response

200 OKapplication/json

43 fields

• cancelRequestedboolean
• costinteger

  Micro-USD

• errorstring or null
• fellBackboolean
• finishedAtinteger or null
• idstring
• imageRefstring or null
• inputany
• instructionsstring or null
• jobIdstring
• jobNamestring
• modestring
• modelLabelstring or null

  The model's display name: its label, or its ID when it has none

• modelNamestring or null

  The model's ID at its provider, such as claude-sonnet-4-5

• msLlminteger
• msProvisioninteger or null
• msQueueinteger or null
• msToolsinteger
• msTotalinteger or null
• numberinteger
• outputsany
• playbookVersioninteger
• queuedAtinteger
• reflectionstring

  One of skipped, pending, done, failed

• reflectionCostinteger

  Micro-USD

• reflectionErrorstring or null
• reflectionOpsarray of objects or null
  13 fields per item

  • contentstring or null
  • flagsarray of strings or null
  • idstring or null
  • kindstring or null
  • namestring or null
  • opstring

    One of add_learning, update_learning, retire_learning, upsert_script, delete_script, set_setup, set_dockerfile, propose_main, update_main, set_verify

  • rationalestring
  • reasonstring
  • statusstring

    One of applied, held, rejected

  • targetstring
  • testobject
    3 fields

    • detailstring
    • outputstring
    • statusstring

      One of passed, failed, skipped

  • textstring or null
  • whenstring or null
• reflectionSummarystring or null
• reflectionVersioninteger or null

  The playbook version reflection on this run created

• sandboxAdapterstring or null
• sandboxIsolationstring or null
• startedAtinteger or null
• statusstring
• summarystring or null
• tokCacheReadinteger
• tokCacheWriteinteger
• tokIninteger
• tokOutinteger
• triggerstring
• triggeredBystring or null
• triggeredByNamestring or null

  Name or email of the user who started the run

• turnsinteger
• verifyCostinteger

  What the utility model's verification of a scripted run cost, in micro-USD

Get run artifact

get/api/runs/{id}/artifact

Examples and details in Artifacts.

Path parameters

• idstringrequired

Query parameters

• pathstringrequired

Response

200 OK

List run artifacts

get/api/runs/{id}/artifacts

Examples and details in Artifacts.

Path parameters

• idstringrequired

Response

200 OKapplication/json

2 fields per item

• namestring
• sizeinteger

Cancel run

post/api/runs/{id}/cancel

Examples and details in Cancel, retry and learn.

Path parameters

• idstringrequired

Response

204 No Content

List run events

get/api/runs/{id}/events

Examples and details in Timeline and live stream.

Path parameters

• idstringrequired

Query parameters

• afterinteger

  Return events with a sequence number greater than this

• limitinteger

  1 to 2000 · defaults to 500

Response

200 OKapplication/json

7 fields per item

• msinteger or null
• parentSpanIdstring or null
• payloadany
• seqinteger
• spanIdstring or null
• tsinteger
• typestring

Learn from run

post/api/runs/{id}/learn

Examples and details in Cancel, retry and learn.

Path parameters

• idstringrequired

Response

200 OKapplication/json

1 field

• reflectionstring

Retry run

post/api/runs/{id}/retry

Examples and details in Cancel, retry and learn.

Path parameters

• idstringrequired

Response

200 OKapplication/json

2 fields

• runIdstring
• statusstring

Stream run

get/api/runs/{id}/stream

Examples and details in Timeline and live stream.

Path parameters

• idstringrequired

Query parameters

• afterinteger

  Resume after this event sequence, for clients that cannot send Last-Event-ID

Headers

• Last-Event-IDstring

Responses

200 OKtext/event-stream

• eventdelta
  3 data fields

  • callIdstring
  • textstring
  • typestring
• eventend
  1 data field

  • statusstring
• eventevent
  7 data fields

  • msinteger or null
  • parentSpanIdstring or null
  • payloadany
  • seqinteger
  • spanIdstring or null
  • tsinteger
  • typestring
• eventstatus
  1 data field

  • statusstring

404 Not Foundapplication/json

5 fields

• codestring
• detailsmap of strings
• fieldsarray of objects or null
  3 fields per item

  • codestring
  • fieldstring
  • messagestring
• messagestring
• requestIdstring

422 Unprocessable Entityapplication/json

5 fields

• codestring
• detailsmap of strings
• fieldsarray of objects or null
  3 fields per item

  • codestring
  • fieldstring
  • messagestring
• messagestring
• requestIdstring

500 Internal Server Errorapplication/json

5 fields

• codestring
• detailsmap of strings
• fieldsarray of objects or null
  3 fields per item

  • codestring
  • fieldstring
  • messagestring
• messagestring
• requestIdstring

Playbook

• get/api/jobs/{id}/playbookGet playbook
• put/api/jobs/{id}/playbookUpdate playbook
• post/api/jobs/{id}/playbook/rollbackRollback playbook
• get/api/jobs/{id}/playbook/versionsList playbook versions
• get/api/jobs/{id}/playbook/versions/{version}Get playbook version

Get playbook

get/api/jobs/{id}/playbook

Path parameters

• idstringrequired

Response

200 OKapplication/json

8 fields

• authorstring
• contentobject
  6 fields

  • dockerfilestring or null
  • learningsarray of objects or null
    7 fields per item

    • hitsinteger
    • idstring
    • kindstring
    • sourcesarray of strings or null
    • statusstring

      One of active, retired

    • textstring
    • whenstring
  • mainstring or null
  • setupstring or null
  • toolkitarray of objects or null
    8 fields per item

    • argsany
    • contentstring
    • descriptionstring
    • langstring
    • namestring
    • sideEffectsboolean
    • sourcesarray of strings or null
    • statsobject
      2 fields

      • callsinteger
      • failuresinteger
  • verifyany
• createdAtinteger
• opsarray of objects or null
  13 fields per item

  • contentstring or null
  • flagsarray of strings or null
  • idstring or null
  • kindstring or null
  • namestring or null
  • opstring

    One of add_learning, update_learning, retire_learning, upsert_script, delete_script, set_setup, set_dockerfile, propose_main, update_main, set_verify

  • rationalestring
  • reasonstring
  • statusstring

    One of applied, held, rejected

  • targetstring
  • testobject
    3 fields

    • detailstring
    • outputstring
    • statusstring

      One of passed, failed, skipped

  • textstring or null
  • whenstring or null
• previousobject
  6 fields

  • dockerfilestring or null
  • learningsarray of objects or null
    7 fields per item

    • hitsinteger
    • idstring
    • kindstring
    • sourcesarray of strings or null
    • statusstring

      One of active, retired

    • textstring
    • whenstring
  • mainstring or null
  • setupstring or null
  • toolkitarray of objects or null
    8 fields per item

    • argsany
    • contentstring
    • descriptionstring
    • langstring
    • namestring
    • sideEffectsboolean
    • sourcesarray of strings or null
    • statsobject
      2 fields

      • callsinteger
      • failuresinteger
  • verifyany
• sourceRunIdstring or null
• summarystring or null
• versioninteger

Update playbook

put/api/jobs/{id}/playbook

Path parameters

• idstringrequired

Body application/json

• contentobjectrequired
  6 fields

  • dockerfilestring or nullrequired
  • learningsarray of objects or nullrequired
    7 fields per item

    • hitsintegerrequired
    • idstringrequired
    • kindstringrequired
    • statusstringrequired

      One of active, retired

    • textstringrequired
    • sourcesarray of strings or null
    • whenstring
  • mainstring or nullrequired
  • setupstring or nullrequired
  • toolkitarray of objects or nullrequired
    8 fields per item

    • contentstringrequired
    • descriptionstringrequired
    • langstringrequired
    • namestringrequired
    • sideEffectsbooleanrequired
    • statsobjectrequired
      2 fields

      • callsintegerrequired
      • failuresintegerrequired
    • argsany
    • sourcesarray of strings or null
  • verifyany
• baseVersioninteger

  The version the edit started from; a newer current version makes the save fail with 409

• summarystring

  at most 500 characters

Response

200 OKapplication/json

8 fields

• authorstring
• contentobject
  6 fields

  • dockerfilestring or null
  • learningsarray of objects or null
    7 fields per item

    • hitsinteger
    • idstring
    • kindstring
    • sourcesarray of strings or null
    • statusstring

      One of active, retired

    • textstring
    • whenstring
  • mainstring or null
  • setupstring or null
  • toolkitarray of objects or null
    8 fields per item

    • argsany
    • contentstring
    • descriptionstring
    • langstring
    • namestring
    • sideEffectsboolean
    • sourcesarray of strings or null
    • statsobject
      2 fields

      • callsinteger
      • failuresinteger
  • verifyany
• createdAtinteger
• opsarray of objects or null
  13 fields per item

  • contentstring or null
  • flagsarray of strings or null
  • idstring or null
  • kindstring or null
  • namestring or null
  • opstring

    One of add_learning, update_learning, retire_learning, upsert_script, delete_script, set_setup, set_dockerfile, propose_main, update_main, set_verify

  • rationalestring
  • reasonstring
  • statusstring

    One of applied, held, rejected

  • targetstring
  • testobject
    3 fields

    • detailstring
    • outputstring
    • statusstring

      One of passed, failed, skipped

  • textstring or null
  • whenstring or null
• previousobject
  6 fields

  • dockerfilestring or null
  • learningsarray of objects or null
    7 fields per item

    • hitsinteger
    • idstring
    • kindstring
    • sourcesarray of strings or null
    • statusstring

      One of active, retired

    • textstring
    • whenstring
  • mainstring or null
  • setupstring or null
  • toolkitarray of objects or null
    8 fields per item

    • argsany
    • contentstring
    • descriptionstring
    • langstring
    • namestring
    • sideEffectsboolean
    • sourcesarray of strings or null
    • statsobject
      2 fields

      • callsinteger
      • failuresinteger
  • verifyany
• sourceRunIdstring or null
• summarystring or null
• versioninteger

Rollback playbook

post/api/jobs/{id}/playbook/rollback

Path parameters

• idstringrequired

Body application/json

• versionintegerrequired

  at least 0

Response

200 OKapplication/json

8 fields

• authorstring
• contentobject
  6 fields

  • dockerfilestring or null
  • learningsarray of objects or null
    7 fields per item

    • hitsinteger
    • idstring
    • kindstring
    • sourcesarray of strings or null
    • statusstring

      One of active, retired

    • textstring
    • whenstring
  • mainstring or null
  • setupstring or null
  • toolkitarray of objects or null
    8 fields per item

    • argsany
    • contentstring
    • descriptionstring
    • langstring
    • namestring
    • sideEffectsboolean
    • sourcesarray of strings or null
    • statsobject
      2 fields

      • callsinteger
      • failuresinteger
  • verifyany
• createdAtinteger
• opsarray of objects or null
  13 fields per item

  • contentstring or null
  • flagsarray of strings or null
  • idstring or null
  • kindstring or null
  • namestring or null
  • opstring

    One of add_learning, update_learning, retire_learning, upsert_script, delete_script, set_setup, set_dockerfile, propose_main, update_main, set_verify

  • rationalestring
  • reasonstring
  • statusstring

    One of applied, held, rejected

  • targetstring
  • testobject
    3 fields

    • detailstring
    • outputstring
    • statusstring

      One of passed, failed, skipped

  • textstring or null
  • whenstring or null
• previousobject
  6 fields

  • dockerfilestring or null
  • learningsarray of objects or null
    7 fields per item

    • hitsinteger
    • idstring
    • kindstring
    • sourcesarray of strings or null
    • statusstring

      One of active, retired

    • textstring
    • whenstring
  • mainstring or null
  • setupstring or null
  • toolkitarray of objects or null
    8 fields per item

    • argsany
    • contentstring
    • descriptionstring
    • langstring
    • namestring
    • sideEffectsboolean
    • sourcesarray of strings or null
    • statsobject
      2 fields

      • callsinteger
      • failuresinteger
  • verifyany
• sourceRunIdstring or null
• summarystring or null
• versioninteger

List playbook versions

get/api/jobs/{id}/playbook/versions

Path parameters

• idstringrequired

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  5 fields per item

  • authorstring
  • createdAtinteger
  • sourceRunIdstring or null
  • summarystring or null
  • versioninteger
• pageinteger
• pageSizeinteger
• totalinteger

Get playbook version

get/api/jobs/{id}/playbook/versions/{version}

Path parameters

• idstringrequired
• versionintegerrequired

Response

200 OKapplication/json

8 fields

• authorstring
• contentobject
  6 fields

  • dockerfilestring or null
  • learningsarray of objects or null
    7 fields per item

    • hitsinteger
    • idstring
    • kindstring
    • sourcesarray of strings or null
    • statusstring

      One of active, retired

    • textstring
    • whenstring
  • mainstring or null
  • setupstring or null
  • toolkitarray of objects or null
    8 fields per item

    • argsany
    • contentstring
    • descriptionstring
    • langstring
    • namestring
    • sideEffectsboolean
    • sourcesarray of strings or null
    • statsobject
      2 fields

      • callsinteger
      • failuresinteger
  • verifyany
• createdAtinteger
• opsarray of objects or null
  13 fields per item

  • contentstring or null
  • flagsarray of strings or null
  • idstring or null
  • kindstring or null
  • namestring or null
  • opstring

    One of add_learning, update_learning, retire_learning, upsert_script, delete_script, set_setup, set_dockerfile, propose_main, update_main, set_verify

  • rationalestring
  • reasonstring
  • statusstring

    One of applied, held, rejected

  • targetstring
  • testobject
    3 fields

    • detailstring
    • outputstring
    • statusstring

      One of passed, failed, skipped

  • textstring or null
  • whenstring or null
• previousobject
  6 fields

  • dockerfilestring or null
  • learningsarray of objects or null
    7 fields per item

    • hitsinteger
    • idstring
    • kindstring
    • sourcesarray of strings or null
    • statusstring

      One of active, retired

    • textstring
    • whenstring
  • mainstring or null
  • setupstring or null
  • toolkitarray of objects or null
    8 fields per item

    • argsany
    • contentstring
    • descriptionstring
    • langstring
    • namestring
    • sideEffectsboolean
    • sourcesarray of strings or null
    • statsobject
      2 fields

      • callsinteger
      • failuresinteger
  • verifyany
• sourceRunIdstring or null
• summarystring or null
• versioninteger

Job state

• get/api/jobs/{id}/stateList job state
• get/api/jobs/{id}/state/{key}Get job state
• put/api/jobs/{id}/state/{key}Put job state
• delete/api/jobs/{id}/state/{key}Delete job state

List job state

get/api/jobs/{id}/state

Path parameters

• idstringrequired

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  3 fields per item

  • keystring
  • updatedAtinteger
  • valuestring
• pageinteger
• pageSizeinteger
• totalinteger

Get job state

get/api/jobs/{id}/state/{key}

Path parameters

• idstringrequired
• keystringrequired

Response

200 OKapplication/json

3 fields

• keystring
• updatedAtinteger
• valuestring

Put job state

put/api/jobs/{id}/state/{key}

Path parameters

• idstringrequired
• keystringrequired

  at most 200 characters

Body application/json

• valuestringrequired

Response

204 No Content

Delete job state

delete/api/jobs/{id}/state/{key}

Path parameters

• idstringrequired
• keystringrequired

Response

204 No Content

Images

• get/api/jobs/{id}/imagesList job images
• post/api/jobs/{id}/images/rebuildRebuild job image
• get/api/jobs/{id}/images/{imageId}Get image

List job images

get/api/jobs/{id}/images

Path parameters

• idstringrequired

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

• statusstring

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  11 fields per item

  • baseDigeststring or null
  • createdAtinteger
  • digeststring or null
  • dockerfileHashstring
  • errorstring or null
  • finishedAtinteger or null
  • idstring
  • refstring or null
  • sizeBytesinteger or null
  • startedAtinteger or null
  • statusstring
• pageinteger
• pageSizeinteger
• totalinteger

Rebuild job image

post/api/jobs/{id}/images/rebuild

Path parameters

• idstringrequired

Response

200 OKapplication/json

1 field

• idstring

Get image

get/api/jobs/{id}/images/{imageId}

Path parameters

• idstringrequired
• imageIdstringrequired

Response

200 OKapplication/json

13 fields

• baseDigeststring or null
• createdAtinteger
• digeststring or null
• dockerfilestring
• dockerfileHashstring
• errorstring or null
• finishedAtinteger or null
• idstring
• logstring
• refstring or null
• sizeBytesinteger or null
• startedAtinteger or null
• statusstring

Webhooks

• post/hooks/{jobId}Trigger webhook

Trigger webhook

post/hooks/{jobId}

Examples and details in Triggers and schedules.

Path parameters

• jobIdstringrequired

Headers

• Authorizationstring

Body application/octet-stream

binary The raw request body.

Response

200 OKapplication/json

2 fields

• runIdstring
• statusstring

Secrets

• get/api/jobs/{id}/secretsGet job secrets
• put/api/jobs/{id}/secretsSet job secrets
• get/api/secretsList secrets
• post/api/secretsCreate secret
• put/api/secrets/{id}Update secret
• delete/api/secrets/{id}Delete secret

Get job secrets

get/api/jobs/{id}/secrets

Path parameters

• idstringrequired

Response

200 OKapplication/json

3 fields per item

• envNamestring

  at most 100 characters · matches ^[A-Za-z_][A-Za-z0-9_]*$

• secretIdstring
• secretNamestring

Set job secrets

put/api/jobs/{id}/secrets

Path parameters

• idstringrequired

Body application/json

An array, with these fields per item:

• envNamestringrequired

  at most 100 characters · matches ^[A-Za-z_][A-Za-z0-9_]*$

• secretIdstringrequired

Response

200 OKapplication/json

3 fields per item

• envNamestring

  at most 100 characters · matches ^[A-Za-z_][A-Za-z0-9_]*$

• secretIdstring
• secretNamestring

List secrets

get/api/secrets

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  4 fields per item

  • createdAtinteger
  • idstring
  • namestring
  • updatedAtinteger
• pageinteger
• pageSizeinteger
• totalinteger

Create secret

post/api/secrets

Body application/json

• namestringrequired

  1 to 100 characters

• valuestringrequired

  at most 65536 characters

Response

200 OKapplication/json

1 field

• idstring

Update secret

put/api/secrets/{id}

Path parameters

• idstringrequired

Body application/json

• valuestringrequired

  at most 65536 characters

Response

204 No Content

Delete secret

delete/api/secrets/{id}

Path parameters

• idstringrequired

Response

204 No Content

MCP

• get/api/jobs/{id}/mcp-serversGet job mcp servers
• put/api/jobs/{id}/mcp-serversSet job mcp servers
• get/api/mcp-serversList mcp servers
• post/api/mcp-serversCreate mcp server
• get/api/mcp-servers/{id}Get mcp server
• put/api/mcp-servers/{id}Update mcp server
• delete/api/mcp-servers/{id}Delete mcp server
• delete/api/mcp-servers/{id}/oauthLogout mcp server
• get/api/mcp-servers/{id}/oauth/callbackMcp server oauth callback
• post/api/mcp-servers/{id}/oauth/loginLogin mcp server
• post/api/mcp-servers/{id}/testTest mcp server

Get job mcp servers

get/api/jobs/{id}/mcp-servers

Path parameters

• idstringrequired

Response

200 OKapplication/json

3 fields per item

• allowedToolsarray of strings or null

  null exposes all tools

• serverIdstring
• serverNamestring

Set job mcp servers

put/api/jobs/{id}/mcp-servers

Path parameters

• idstringrequired

Body application/json

An array, with these fields per item:

• allowedToolsarray of strings or nullrequired

  null exposes all tools

• serverIdstringrequired

Response

200 OKapplication/json

3 fields per item

• allowedToolsarray of strings or null

  null exposes all tools

• serverIdstring
• serverNamestring

List mcp servers

get/api/mcp-servers

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

• transportstring

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  16 fields per item

  • argsarray of strings or null
  • authobject
    5 fields

    • callbackUrlstring

      Where the authorization server sends the browser back to, which an OAuth client configured by hand must allow

    • expiresAtinteger or null

      When the current access token expires

    • loggedInAtinteger or null

      When the OAuth login was made, also set once it expired

    • refreshableboolean

      The login has a refresh token, so it outlives its access token

    • statusstring

      unsupported: no login needed or possible, unknown: OAuth detection hasn't succeeded yet, bearer_token: an Authorization header is configured, not_logged_in: the server advertises OAuth but has no usable login, oauth: logged in

      One of unsupported, unknown, bearer_token, not_logged_in, oauth

  • commandstring or null
  • createdAtinteger
  • descriptionstring or null
  • enabledboolean
  • envmap of strings

    Values may reference secrets as {{secret:NAME}}

  • headersmap of strings

    Values may reference secrets as {{secret:NAME}}

  • idstring
  • namestring
  • oauthobject
    3 fields

    • clientIdstring

      A client registered with the authorization server beforehand, for servers without dynamic client registration

      at most 500 characters

    • clientSecretstring

      The client's secret, may reference a secret as {{secret:NAME}}

      at most 2000 characters

    • scopesarray of strings or null

      Scopes to request instead of the ones the server advertises

      at most 50 items

  • toolsarray of objects or null
    5 fields per item

    • descriptionstring
    • destructiveboolean
    • inputSchemaany
    • namestring
    • readOnlyboolean
  • toolsCachedAtinteger or null
  • transportstring
  • updatedAtinteger
  • urlstring or null
• pageinteger
• pageSizeinteger
• totalinteger

Create mcp server

post/api/mcp-servers

Body application/json

• namestringrequired

  1 to 64 characters · matches ^[A-Za-z0-9_-]+$

• transportstringrequired

  One of stdio, http

• argsarray of strings or null
• commandstring

  at most 500 characters

• descriptionstring

  at most 500 characters

• enabledboolean
• envmap of strings
• headersmap of strings
• oauthobject

  OAuth client settings of HTTP servers, only needed when the server's authorization server can't register clients itself

  3 fields

  • clientIdstring

    A client registered with the authorization server beforehand, for servers without dynamic client registration

    at most 500 characters

  • clientSecretstring

    The client's secret, may reference a secret as {{secret:NAME}}

    at most 2000 characters

  • scopesarray of strings or null

    Scopes to request instead of the ones the server advertises

    at most 50 items

• urlstring

  at most 2000 characters

Response

200 OKapplication/json

16 fields

• argsarray of strings or null
• authobject
  5 fields

  • callbackUrlstring

    Where the authorization server sends the browser back to, which an OAuth client configured by hand must allow

  • expiresAtinteger or null

    When the current access token expires

  • loggedInAtinteger or null

    When the OAuth login was made, also set once it expired

  • refreshableboolean

    The login has a refresh token, so it outlives its access token

  • statusstring

    unsupported: no login needed or possible, unknown: OAuth detection hasn't succeeded yet, bearer_token: an Authorization header is configured, not_logged_in: the server advertises OAuth but has no usable login, oauth: logged in

    One of unsupported, unknown, bearer_token, not_logged_in, oauth

• commandstring or null
• createdAtinteger
• descriptionstring or null
• enabledboolean
• envmap of strings

  Values may reference secrets as {{secret:NAME}}

• headersmap of strings

  Values may reference secrets as {{secret:NAME}}

• idstring
• namestring
• oauthobject
  3 fields

  • clientIdstring

    A client registered with the authorization server beforehand, for servers without dynamic client registration

    at most 500 characters

  • clientSecretstring

    The client's secret, may reference a secret as {{secret:NAME}}

    at most 2000 characters

  • scopesarray of strings or null

    Scopes to request instead of the ones the server advertises

    at most 50 items

• toolsarray of objects or null
  5 fields per item

  • descriptionstring
  • destructiveboolean
  • inputSchemaany
  • namestring
  • readOnlyboolean
• toolsCachedAtinteger or null
• transportstring
• updatedAtinteger
• urlstring or null

Get mcp server

get/api/mcp-servers/{id}

Path parameters

• idstringrequired

Response

200 OKapplication/json

16 fields

• argsarray of strings or null
• authobject
  5 fields

  • callbackUrlstring

    Where the authorization server sends the browser back to, which an OAuth client configured by hand must allow

  • expiresAtinteger or null

    When the current access token expires

  • loggedInAtinteger or null

    When the OAuth login was made, also set once it expired

  • refreshableboolean

    The login has a refresh token, so it outlives its access token

  • statusstring

    unsupported: no login needed or possible, unknown: OAuth detection hasn't succeeded yet, bearer_token: an Authorization header is configured, not_logged_in: the server advertises OAuth but has no usable login, oauth: logged in

    One of unsupported, unknown, bearer_token, not_logged_in, oauth

• commandstring or null
• createdAtinteger
• descriptionstring or null
• enabledboolean
• envmap of strings

  Values may reference secrets as {{secret:NAME}}

• headersmap of strings

  Values may reference secrets as {{secret:NAME}}

• idstring
• namestring
• oauthobject
  3 fields

  • clientIdstring

    A client registered with the authorization server beforehand, for servers without dynamic client registration

    at most 500 characters

  • clientSecretstring

    The client's secret, may reference a secret as {{secret:NAME}}

    at most 2000 characters

  • scopesarray of strings or null

    Scopes to request instead of the ones the server advertises

    at most 50 items

• toolsarray of objects or null
  5 fields per item

  • descriptionstring
  • destructiveboolean
  • inputSchemaany
  • namestring
  • readOnlyboolean
• toolsCachedAtinteger or null
• transportstring
• updatedAtinteger
• urlstring or null

Update mcp server

put/api/mcp-servers/{id}

Path parameters

• idstringrequired

Body application/json

• namestringrequired

  1 to 64 characters · matches ^[A-Za-z0-9_-]+$

• transportstringrequired

  One of stdio, http

• argsarray of strings or null
• commandstring

  at most 500 characters

• descriptionstring

  at most 500 characters

• enabledboolean
• envmap of strings
• headersmap of strings
• oauthobject

  OAuth client settings of HTTP servers, only needed when the server's authorization server can't register clients itself

  3 fields

  • clientIdstring

    A client registered with the authorization server beforehand, for servers without dynamic client registration

    at most 500 characters

  • clientSecretstring

    The client's secret, may reference a secret as {{secret:NAME}}

    at most 2000 characters

  • scopesarray of strings or null

    Scopes to request instead of the ones the server advertises

    at most 50 items

• urlstring

  at most 2000 characters

Response

200 OKapplication/json

16 fields

• argsarray of strings or null
• authobject
  5 fields

  • callbackUrlstring

    Where the authorization server sends the browser back to, which an OAuth client configured by hand must allow

  • expiresAtinteger or null

    When the current access token expires

  • loggedInAtinteger or null

    When the OAuth login was made, also set once it expired

  • refreshableboolean

    The login has a refresh token, so it outlives its access token

  • statusstring

    unsupported: no login needed or possible, unknown: OAuth detection hasn't succeeded yet, bearer_token: an Authorization header is configured, not_logged_in: the server advertises OAuth but has no usable login, oauth: logged in

    One of unsupported, unknown, bearer_token, not_logged_in, oauth

• commandstring or null
• createdAtinteger
• descriptionstring or null
• enabledboolean
• envmap of strings

  Values may reference secrets as {{secret:NAME}}

• headersmap of strings

  Values may reference secrets as {{secret:NAME}}

• idstring
• namestring
• oauthobject
  3 fields

  • clientIdstring

    A client registered with the authorization server beforehand, for servers without dynamic client registration

    at most 500 characters

  • clientSecretstring

    The client's secret, may reference a secret as {{secret:NAME}}

    at most 2000 characters

  • scopesarray of strings or null

    Scopes to request instead of the ones the server advertises

    at most 50 items

• toolsarray of objects or null
  5 fields per item

  • descriptionstring
  • destructiveboolean
  • inputSchemaany
  • namestring
  • readOnlyboolean
• toolsCachedAtinteger or null
• transportstring
• updatedAtinteger
• urlstring or null

Delete mcp server

delete/api/mcp-servers/{id}

Path parameters

• idstringrequired

Response

204 No Content

Logout mcp server

delete/api/mcp-servers/{id}/oauth

Path parameters

• idstringrequired

Response

200 OKapplication/json

16 fields

• argsarray of strings or null
• authobject
  5 fields

  • callbackUrlstring

    Where the authorization server sends the browser back to, which an OAuth client configured by hand must allow

  • expiresAtinteger or null

    When the current access token expires

  • loggedInAtinteger or null

    When the OAuth login was made, also set once it expired

  • refreshableboolean

    The login has a refresh token, so it outlives its access token

  • statusstring

    unsupported: no login needed or possible, unknown: OAuth detection hasn't succeeded yet, bearer_token: an Authorization header is configured, not_logged_in: the server advertises OAuth but has no usable login, oauth: logged in

    One of unsupported, unknown, bearer_token, not_logged_in, oauth

• commandstring or null
• createdAtinteger
• descriptionstring or null
• enabledboolean
• envmap of strings

  Values may reference secrets as {{secret:NAME}}

• headersmap of strings

  Values may reference secrets as {{secret:NAME}}

• idstring
• namestring
• oauthobject
  3 fields

  • clientIdstring

    A client registered with the authorization server beforehand, for servers without dynamic client registration

    at most 500 characters

  • clientSecretstring

    The client's secret, may reference a secret as {{secret:NAME}}

    at most 2000 characters

  • scopesarray of strings or null

    Scopes to request instead of the ones the server advertises

    at most 50 items

• toolsarray of objects or null
  5 fields per item

  • descriptionstring
  • destructiveboolean
  • inputSchemaany
  • namestring
  • readOnlyboolean
• toolsCachedAtinteger or null
• transportstring
• updatedAtinteger
• urlstring or null

Mcp server oauth callback

get/api/mcp-servers/{id}/oauth/callback

Path parameters

• idstringrequired

Query parameters

• codestring
• statestring
• issstring
• errorstring
• error_descriptionstring

Response

204 No Content

Login mcp server

post/api/mcp-servers/{id}/oauth/login

Path parameters

• idstringrequired

Response

200 OKapplication/json

1 field

• authorizationUrlstring

  Where to send the browser to log in

Test mcp server

post/api/mcp-servers/{id}/test

Path parameters

• idstringrequired

Response

200 OKapplication/json

5 fields

• authobject

  The server's authentication status after the test

  5 fields

  • callbackUrlstring

    Where the authorization server sends the browser back to, which an OAuth client configured by hand must allow

  • expiresAtinteger or null

    When the current access token expires

  • loggedInAtinteger or null

    When the OAuth login was made, also set once it expired

  • refreshableboolean

    The login has a refresh token, so it outlives its access token

  • statusstring

    unsupported: no login needed or possible, unknown: OAuth detection hasn't succeeded yet, bearer_token: an Authorization header is configured, not_logged_in: the server advertises OAuth but has no usable login, oauth: logged in

    One of unsupported, unknown, bearer_token, not_logged_in, oauth

• errorstring
• latencyMsinteger
• okboolean
• toolsarray of objects or null
  5 fields per item

  • descriptionstring
  • destructiveboolean
  • inputSchemaany
  • namestring
  • readOnlyboolean

Providers

• get/api/catalog/modelsGet model catalog
• get/api/modelsList models
• post/api/modelsCreate model
• patch/api/models/{id}Update model
• delete/api/models/{id}Delete model
• get/api/providersList providers
• post/api/providersCreate provider
• patch/api/providers/{id}Update provider
• delete/api/providers/{id}Delete provider
• put/api/providers/{id}/models/enabledSet provider models enabled
• post/api/providers/{id}/syncSync provider models
• post/api/providers/{id}/testTest provider

Get model catalog

get/api/catalog/models

Query parameters

• kindstring

  One of anthropic, openai

Response

200 OKapplication/json

4 fields per item

• capsobject
  7 fields

  • contextinteger
  • jsonSchemaboolean
  • parallelToolsboolean
  • promptCacheboolean
  • reasoningboolean
  • toolsboolean
  • visionboolean
• labelstring
• modelstring
• priceobject
  4 fields

  • cacheReadinteger
  • cacheWriteinteger
  • ininteger
  • outinteger

List models

get/api/models

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

• providerstring

  Comma-separated provider IDs

• statusstring

  Comma-separated statuses: enabled (can be picked), disabled, unlisted

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  13 fields per item

  • capsobject
    7 fields

    • contextinteger
    • jsonSchemaboolean
    • parallelToolsboolean
    • promptCacheboolean
    • reasoningboolean
    • toolsboolean
    • visionboolean
  • contextWindowinteger
  • enabledboolean
  • followCatalogboolean
  • idstring
  • labelstring or null
  • modelstring
  • priceobject

    Micro-USD per 1M tokens

    4 fields

    • cacheReadinteger
    • cacheWriteinteger
    • ininteger
    • outinteger
  • providerIdstring
  • providerKindstring
  • providerNamestring
  • syncedboolean
  • unlistedAtinteger or null
• pageinteger
• pageSizeinteger
• totalinteger

Create model

post/api/models

Body application/json

• capsobjectrequired
  7 fields

  • contextintegerrequired
  • jsonSchemabooleanrequired
  • parallelToolsbooleanrequired
  • promptCachebooleanrequired
  • reasoningbooleanrequired
  • toolsbooleanrequired
  • visionbooleanrequired
• modelstringrequired

  1 to 200 characters

• priceobjectrequired
  4 fields

  • cacheReadintegerrequired
  • cacheWriteintegerrequired
  • inintegerrequired
  • outintegerrequired
• providerIdstringrequired
• labelstring

  at most 100 characters

Response

200 OKapplication/json

1 field

• idstring

Update model

patch/api/models/{id}

Path parameters

• idstringrequired

Body application/json

• capsobject
  7 fields

  • contextintegerrequired
  • jsonSchemabooleanrequired
  • parallelToolsbooleanrequired
  • promptCachebooleanrequired
  • reasoningbooleanrequired
  • toolsbooleanrequired
  • visionbooleanrequired
• enabledboolean
• followCatalogboolean
• labelstring

  at most 100 characters

• priceobject
  4 fields

  • cacheReadintegerrequired
  • cacheWriteintegerrequired
  • inintegerrequired
  • outintegerrequired

Response

204 No Content

Delete model

delete/api/models/{id}

Path parameters

• idstringrequired

Response

204 No Content

List providers

get/api/providers

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  11 fields per item

  • baseUrlstring or null
  • createdAtinteger
  • enabledModelCountinteger
  • hasApiKeyboolean
  • idstring
  • kindstring
  • modelCountinteger
  • modelSourcestring

    catalog: the models.dev catalog of the kind, server: the server's model list, manual: models are added by hand

    One of catalog, server, manual

  • namestring
  • syncErrorstring or null

    Why the last sync could not read the model list

  • syncedAtinteger or null
• pageinteger
• pageSizeinteger
• totalinteger

Create provider

post/api/providers

Body application/json

• kindstringrequired

  One of anthropic, openai, fake

• namestringrequired

  1 to 100 characters

• apiKeystring

  at most 1000 characters

• baseUrlstring

  at most 500 characters

Response

200 OKapplication/json

2 fields

• idstring
• syncobject
  4 fields

  • addedinteger
  • errorstring
  • unlistedinteger
  • updatedinteger

Update provider

patch/api/providers/{id}

Path parameters

• idstringrequired

Body application/json

• apiKeystring

  at most 1000 characters

• baseUrlstring

  at most 500 characters

• namestring

  1 to 100 characters

Response

204 No Content

Delete provider

delete/api/providers/{id}

Path parameters

• idstringrequired

Response

204 No Content

Set provider models enabled

put/api/providers/{id}/models/enabled

Path parameters

• idstringrequired

Body application/json

• enabledbooleanrequired

Response

200 OKapplication/json

1 field

• changedinteger

Sync provider models

post/api/providers/{id}/sync

Path parameters

• idstringrequired

Response

200 OKapplication/json

4 fields

• addedinteger
• errorstring
• unlistedinteger
• updatedinteger

Test provider

post/api/providers/{id}/test

Path parameters

• idstringrequired

Body application/json

• modelIdstringrequired

  Model to test with

Response

200 OKapplication/json

4 fields

• errorstring
• latencyMsinteger
• okboolean
• replystring

Settings

• get/api/settingsGet settings
• patch/api/settingsUpdate settings
• post/api/settings/notifications/testTest notification

Get settings

get/api/settings

Response

200 OKapplication/json

10 fields

• agentModelIdstring or null
• dailySpendLimitUsdnumber

  0 means no limit

• defaultImagestring
• defaultLimitsobject
  6 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    at least 0

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • pidsLimitinteger

    16 to 65536

  • timeoutSecondsinteger

    30 to 86400

• notifyOnarray of strings or null

  One of run.failed, run.fell_back, job.demoted

• notifySecretstring or null

  Name of a workspace secret whose value signs every delivery

• notifyWebhookUrlstring or null
• reflectionModelIdstring or null
• retentionDaysinteger

  at least 1

• utilityModelIdstring or null

Update settings

patch/api/settings

Body application/json

• agentModelIdstring
• dailySpendLimitUsdnumber

  at least 0

• defaultImagestring

  An empty value resets to the server default

  at most 500 characters

• defaultLimitsobject
  6 fields

  • cpusnumberrequired

    0.1 to 64

  • maxCostUsdnumberrequired

    at least 0

  • maxTurnsintegerrequired

    1 to 1000

  • memoryMbintegerrequired

    64 to 262144

  • pidsLimitintegerrequired

    16 to 65536

  • timeoutSecondsintegerrequired

    30 to 86400

• notifyOnarray of strings or null

  One of run.failed, run.fell_back, job.demoted

• notifySecretstring

  An empty value sends deliveries unsigned

  at most 100 characters

• notifyWebhookUrlstring

  An empty value turns notifications off

  at most 2000 characters

• reflectionModelIdstring
• retentionDaysinteger

  1 to 3650

• utilityModelIdstring

Response

200 OKapplication/json

10 fields

• agentModelIdstring or null
• dailySpendLimitUsdnumber

  0 means no limit

• defaultImagestring
• defaultLimitsobject
  6 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    at least 0

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • pidsLimitinteger

    16 to 65536

  • timeoutSecondsinteger

    30 to 86400

• notifyOnarray of strings or null

  One of run.failed, run.fell_back, job.demoted

• notifySecretstring or null

  Name of a workspace secret whose value signs every delivery

• notifyWebhookUrlstring or null
• reflectionModelIdstring or null
• retentionDaysinteger

  at least 1

• utilityModelIdstring or null

Test notification

post/api/settings/notifications/test

Response

200 OKapplication/json

1 field

• deliveredboolean

Stats

• get/api/jobs/{id}/statsGet job stats
• get/api/stats/overviewGet stats overview

Get job stats

get/api/jobs/{id}/stats

Path parameters

• idstringrequired

Query parameters

• rangestring

  One of 7d, 30d, 90d · defaults to "30d"

Response

200 OKapplication/json

5 fields

• avgCostinteger
• p50Msinteger
• runsarray of objects or null
  9 fields per item

  • costinteger
  • modestring
  • msTotalinteger or null
  • numberinteger
  • playbookVersioninteger
  • queuedAtinteger
  • runIdstring
  • statusstring
  • turnsinteger
• successRatenumber
• versionsarray of objects or null
  3 fields per item

  • authorstring
  • createdAtinteger
  • versioninteger

Get stats overview

get/api/stats/overview

Query parameters

• rangestring

  One of 24h, 7d, 30d, 90d · defaults to "7d"

Response

200 OKapplication/json

12 fields

• bucketstring

  Width of the perDay and costByJob buckets: an hour for the 24h range and a UTC day for the others

  One of hour, day

• bucketMsinteger

  Width of one bucket in milliseconds

• costByJobarray of objects or null
  4 fields per item

  • costinteger
  • dayinteger

    Start of the bucket in unix milliseconds, like DayBucket.day

  • jobIdstring
  • jobNamestring
• currentobject
  8 fields

  • failedinteger
  • learningCostinteger

    Micro-USD

  • p50Msinteger
  • p95Msinteger
  • runCostinteger

    Micro-USD

  • runsinteger
  • succeededinteger
  • successRatenumber
• frominteger

  Start of the period that current, perDay and costByJob cover, the start of its first bucket, in unix milliseconds

• gettingCheaperarray of objects or null
  6 fields per item

  • dropPctnumber
  • firstCostinteger
  • jobIdstring
  • jobNamestring
  • recentCostinteger
  • runsinteger
• perDayarray of objects or null

  One bucket for every hour or day of the period, oldest first, whose runs other than skipped ones add up to current.runs

  8 fields per item

  • cancelledinteger
  • costinteger
  • dayinteger

    Start of the bucket in unix milliseconds, a UTC day or, for the 24h range, an hour

  • failedinteger
  • otherinteger
  • skippedinteger
  • succeededinteger
  • timedOutinteger
• previousobject

  The period before, cut off at the point in time the current period has reached

  8 fields

  • failedinteger
  • learningCostinteger

    Micro-USD

  • p50Msinteger
  • p95Msinteger
  • runCostinteger

    Micro-USD

  • runsinteger
  • succeededinteger
  • successRatenumber
• rangestring
• recentFailuresarray of objects or null
  10 fields per item

  • errorstring or null
  • idstring
  • jobIdstring
  • jobNamestring
  • modestring
  • numberinteger
  • queuedAtinteger
  • startedAtinteger or null
  • statusstring
  • summarystring or null
• runningarray of objects or null
  10 fields per item

  • errorstring or null
  • idstring
  • jobIdstring
  • jobNamestring
  • modestring
  • numberinteger
  • queuedAtinteger
  • startedAtinteger or null
  • statusstring
  • summarystring or null
• tointeger

  End of the period, exclusive: the end of the bucket that holds the present, in unix milliseconds

API tokens

• get/api/tokensList api tokens
• post/api/tokensCreate api token
• delete/api/tokens/{id}Delete api token

List api tokens

get/api/tokens

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  6 fields per item

  • createdAtinteger
  • createdBystring or null

    Name or email address of the user whose role the token acts with

  • expiresAtinteger or null
  • idstring
  • lastUsedAtinteger or null
  • namestring
• pageinteger
• pageSizeinteger
• totalinteger

Create api token

post/api/tokens

Body application/json

• namestringrequired

  1 to 100 characters

• expiresAtinteger

  Unix milliseconds; omit for a token that never expires

Response

200 OKapplication/json

2 fields

• apiTokenobject
  6 fields

  • createdAtinteger
  • createdBystring or null

    Name or email address of the user whose role the token acts with

  • expiresAtinteger or null
  • idstring
  • lastUsedAtinteger or null
  • namestring
• tokenstring

  Shown once, store it now

Delete api token

delete/api/tokens/{id}

Path parameters

• idstringrequired

Response

204 No Content

Auth

• get/api/auth/callback/{provider}Login callback
• get/api/auth/login/{provider}Login
• post/api/auth/logoutLogout
• get/api/auth/providersList login providers
• get/api/users/meGet current user

Login callback

get/api/auth/callback/{provider}

Path parameters

• providerstringrequired

  ID of the sign-in provider the login started with

Query parameters

• codestring
• statestring
• errorstring

Cookies

• umpteenth_loginobject

Response

204 No Content

Login

get/api/auth/login/{provider}

Path parameters

• providerstringrequired

  ID of the sign-in provider

Query parameters

• redirectstring

  Relative path to return to after login

Response

204 No Content

Logout

post/api/auth/logout

Response

204 No Content

List login providers

get/api/auth/providers

Response

200 OKapplication/json

5 fields per item

• iconstring

  Image URL for the sign-in button, an http(s) URL or a data:image URI

• idstring
• namestring
• primaryboolean

  Whether the provider gets the large sign-in button

• typestring

  How the provider signs in, which picks the default icon

  One of oidc, github

Get current user

get/api/users/me

Response

200 OKapplication/json

10 fields

• emailstring or null
• idstring
• isAdminboolean

  Whether the user is an instance admin, who manages every user and workspace

• loginProviderstring

  ID of the sign-in provider the session signed in with

• namestring or null
• picturestring or null

  Profile picture URL from the sign-in provider

• viaTokenboolean
• workspaceobject
  3 fields

  • idstring
  • namestring
  • rolestring

    The caller's role in the workspace, which is their creator's for an API token

    One of owner, admin, member

• workspaceIdstring
• workspacesEnabledboolean

  Whether people can have several workspaces on this instance

System

• get/api/system/infoGet system info

Get system info

get/api/system/info

Response

200 OKapplication/json

4 fields

• allowPrivateNetworkTargetsboolean
• databasestring
• sandboxobject
  9 fields

  • adapterstring
  • archstring
  • capabilitiesobject
    3 fields

    • limitsobject
      3 fields

      • cpuboolean
      • memoryboolean
      • pidsboolean
    • networksarray of strings or null
    • separateUsersboolean
  • egressFilterstring

    One of active, unavailable, off

  • egressFilterErrorstring
  • imageBuildsboolean
  • isolationstring

    One of container, gvisor, microvm

  • runtimeErrorstring
  • versionstring
• versionstring

Admin

• get/api/admin/usersList users
• patch/api/admin/users/{id}Update user
• get/api/admin/workspacesList all workspaces
• delete/api/admin/workspaces/{id}Delete any workspace

List users

get/api/admin/users

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  11 fields per item

  • createdAtinteger
  • deactivatedboolean
  • emailstring or null
  • idstring
  • isAdminboolean
  • issuerstring

    The issuer URL of the sign-in provider the account belongs to

  • lastLoginAtinteger or null
  • namestring or null
  • picturestring or null
  • providerstring

    The name of the sign-in provider the account belongs to, or the issuer's host when no configured provider has its issuer

  • workspaceCountinteger
• pageinteger
• pageSizeinteger
• totalinteger

Update user

patch/api/admin/users/{id}

Path parameters

• idstringrequired

Body application/json

• deactivatedbooleanrequired

  A deactivated user can't sign in, and their sessions and API tokens stop working

Response

204 No Content

List all workspaces

get/api/admin/workspaces

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  7 fields per item

  • createdAtinteger
  • idstring
  • memberCountinteger
  • namestring
  • ownerEmailstring or null
  • ownerIdstring or null
  • ownerNamestring or null
• pageinteger
• pageSizeinteger
• totalinteger

Delete any workspace

delete/api/admin/workspaces/{id}

Path parameters

• idstringrequired

Response

204 No Content

Workspace members

• post/api/invites/acceptAccept invite
• post/api/invites/lookupLookup invite
• get/api/workspace/invitesList workspace invites
• post/api/workspace/invitesCreate workspace invite
• delete/api/workspace/invites/{id}Delete workspace invite
• get/api/workspace/membersList workspace members
• patch/api/workspace/members/{userId}Update workspace member
• delete/api/workspace/members/{userId}Remove workspace member

Accept invite

post/api/invites/accept

Body application/json

• tokenstringrequired

  1 to 200 characters

Response

200 OKapplication/json

3 fields

• idstring
• namestring
• rolestring

  The caller's role in the workspace

  One of owner, admin, member

Lookup invite

post/api/invites/lookup

Body application/json

• tokenstringrequired

  1 to 200 characters

Response

200 OKapplication/json

6 fields

• alreadyMemberboolean
• expiredboolean
• expiresAtinteger
• invitedBystring or null
• rolestring

  One of admin, member

• workspaceNamestring

List workspace invites

get/api/workspace/invites

Response

200 OKapplication/json

6 fields per item

• createdAtinteger
• emailstring or null

  The address an email invite waits for, empty for an invite link

• expiresAtinteger
• idstring
• invitedBystring or null
• rolestring

  One of admin, member

Create workspace invite

post/api/workspace/invites

Body application/json

• expiresInDaysintegerrequired

  1 to 30 · defaults to 7

• rolestringrequired

  One of admin, member

• emailstring

  Invites this address, whose owner joins at once when they have signed in before; omit it for an invite link

  at most 320 characters

Response

200 OKapplication/json

2 fields

• memberAddedboolean

  Whether the address belonged to a user, who joined right away

• urlstring

  The invite link, shown once

Delete workspace invite

delete/api/workspace/invites/{id}

Path parameters

• idstringrequired

Response

204 No Content

List workspace members

get/api/workspace/members

Query parameters

• pageinteger

  1-based page number

  at least 1 · defaults to 1

• pageSizeinteger

  Items per page

  1 to 100 · defaults to 25

• sortstring

  Comma-separated sort keys, prefix with - for descending

  at most 200 characters

• searchstring

  Free-text search

  at most 200 characters

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  8 fields per item

  • deactivatedboolean

    Whether an instance admin deactivated the user

  • emailstring or null
  • joinedAtinteger
  • lastLoginAtinteger or null
  • namestring or null
  • picturestring or null
  • rolestring

    One of owner, admin, member

  • userIdstring
• pageinteger
• pageSizeinteger
• totalinteger

Update workspace member

patch/api/workspace/members/{userId}

Path parameters

• userIdstringrequired

Body application/json

• rolestringrequired

  The owner changes by handing over ownership instead

  One of admin, member

Response

204 No Content

Remove workspace member

delete/api/workspace/members/{userId}

Path parameters

• userIdstringrequired

Response

204 No Content

Workspaces

• get/api/workspaceGet workspace
• patch/api/workspaceUpdate workspace
• delete/api/workspaceDelete workspace
• post/api/workspace/leaveLeave workspace
• post/api/workspace/transferTransfer workspace
• get/api/workspacesList my workspaces
• post/api/workspacesCreate workspace
• post/api/workspaces/{id}/switchSwitch workspace

Get workspace

get/api/workspace

Response

200 OKapplication/json

3 fields

• idstring
• namestring
• rolestring

  The caller's role in the workspace

  One of owner, admin, member

Update workspace

patch/api/workspace

Body application/json

• namestringrequired

  1 to 100 characters

Response

200 OKapplication/json

3 fields

• idstring
• namestring
• rolestring

  The caller's role in the workspace

  One of owner, admin, member

Delete workspace

delete/api/workspace

Response

200 OKapplication/json

3 fields

• idstring
• namestring
• rolestring

  The caller's role in the workspace

  One of owner, admin, member

Leave workspace

post/api/workspace/leave

Response

200 OKapplication/json

3 fields

• idstring
• namestring
• rolestring

  The caller's role in the workspace

  One of owner, admin, member

Transfer workspace

post/api/workspace/transfer

Body application/json

• userIdstringrequired

  The member who becomes the owner

Response

204 No Content

List my workspaces

get/api/workspaces

Response

200 OKapplication/json

3 fields per item

• idstring
• namestring
• rolestring

  The caller's role in the workspace

  One of owner, admin, member

Create workspace

post/api/workspaces

Body application/json

• namestringrequired

  1 to 100 characters

Response

200 OKapplication/json

3 fields

• idstring
• namestring
• rolestring

  The caller's role in the workspace

  One of owner, admin, member

Switch workspace

post/api/workspaces/{id}/switch

Path parameters

• idstringrequired

Response

200 OKapplication/json

3 fields

• idstring
• namestring
• rolestring

  The caller's role in the workspace

  One of owner, admin, member