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 scripting a run from start to finish. 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
• get/api/jobs/{id}/suggestionsList job suggestions
• post/api/jobs/{id}/suggestions/{suggestionId}/applyApply job suggestion
• post/api/jobs/{id}/suggestions/{suggestionId}/dismissDismiss job suggestion
• 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

Response

200 OKapplication/json

4 fields

• itemsarray of objects
  15 fields per item

  • createdAtinteger
  • cronstring or null
  • graduateboolean
  • 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

      JSON type: string, integer, number, boolean, object or array

  • 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
  • namestring
  • nextModestring

    The mode the next run starts in, which is never scripted while graduation is off

    One of explore, assisted, scripted

  • nextRunAtinteger or null
  • pausedboolean
  • 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
  • timezonestring or null
  • updatedAtinteger
• pageinteger
• pageSizeinteger
• totalinteger

Create job

post/api/jobs

Body application/json

• instructionstringrequired

  What the agent does, which it reads on every run

  1 to 20000 characters

• namestringrequired

  1 to 200 characters

• allowPrivateNetworkboolean
• allowedDomainsarray of strings or null

  at most 100 items

• concurrencystring

  What a trigger during an active run does, skip when omitted

  One of skip, queue, parallel

• cronstring

  Five-field cron expression or a descriptor such as @daily, for a job that runs on a schedule

  at most 100 characters

• graduateboolean

  Whether the job may graduate to a script that runs without the agent, true when omitted

• imagestring

  Base image of the sandbox, the workspace's default image when omitted

  at most 500 characters

• limitsobject
  5 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    Spend per run in USD, where 0 turns the limit off

    at least 0

  • maxTurnsinteger

    Model calls the agent may make per run

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • timeoutSecondsinteger

    30 to 86400

• modelIdstring

  Model that drives the agent, the workspace's agent model when omitted

• networkstring

  What the sandbox may reach, internet when omitted; allowlist limits it to allowedDomains

  One of none, internet, allowlist, unrestricted

• pausedboolean

  Whether the schedule and the webhook are paused, which leaves manual and API runs alone

• runAsRootboolean
• selfImproveboolean

  Whether reflection after runs improves the job's playbook, true when omitted

• specobject

  The spec compiled from the instruction

  10 fields

  • dockerfilestring or nullrequired

    Dockerfile for jobs that need tools beyond the default sandbox image, null otherwise

  • goalstringrequired

    One sentence on the outcome

  • inputsarray of objects or nullrequired

    Values a run reads from /ump/input.json

    3 fields per item

    • namestringrequired
    • typestringrequired

      JSON type: string, integer, number, boolean, object or array

    • descriptionstring
  • mcparray of objects or nullrequired

    MCP servers the job needs

    2 fields per item

    • serverstringrequired

      Name of a configured MCP server, or of the service when none is configured

    • whystringrequired
  • networkstringrequired

    Whether the job needs the internet

    One of none, internet

  • outputsarray of objects or nullrequired

    Small structured values each run reports

    3 fields per item

    • namestringrequired
    • typestringrequired

      JSON type: string, integer, number, boolean, object or array

    • descriptionstring
  • sideEffectsarray of strings or nullrequired

    Changes the job makes outside its sandbox and when, such as posting a message when there is something to report

  • successCriteriaarray of strings or nullrequired

    The end state a successful run leaves behind, which the agent reads with the instruction

  • titlestringrequired

    Short name for the job

  • scheduleobject

    The schedule the instruction asks for, which only takes effect through the job's cron and timezone

    2 fields

    • cronstringrequired

      Five-field cron expression

    • timezonestringrequired

      IANA time zone the expression runs in, such as Europe/Berlin

• timezonestring

  IANA time zone of the schedule, UTC when omitted

  at most 100 characters

Response

200 OKapplication/json

26 fields

• allowPrivateNetworkboolean
• allowedDomainsarray of strings or null
• concurrencystring
• createdAtinteger
• cronstring or null
• demotionstring

  Why repeated fallbacks or handovers took a graduated job back to Assisted, missing while it isn't demoted

  One of fell_back, handed_over

• graduateboolean

  Whether the job may graduate to a main script that runs without the agent

• 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
  5 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    Spend per run in USD, where 0 turns the limit off

    at least 0

  • maxTurnsinteger

    Model calls the agent may make per run

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • timeoutSecondsinteger

    30 to 86400

• modelIdstring or null
• namestring
• networkstring

  One of none, internet, allowlist, unrestricted

• nextModestring

  One of explore, assisted, scripted

• nextRunAtinteger or null
• pausedboolean

  Whether the schedule and the webhook are paused, which leaves manual and API runs alone

• playbookVersioninteger
• runAsRootboolean
• selfImproveboolean
• specobject
  10 fields

  • dockerfilestring or null

    Dockerfile for jobs that need tools beyond the default sandbox image, null otherwise

  • goalstring

    One sentence on the outcome

  • inputsarray of objects or null

    Values a run reads from /ump/input.json

    3 fields per item

    • descriptionstring
    • namestring
    • typestring

      JSON type: string, integer, number, boolean, object or array

  • mcparray of objects or null

    MCP servers the job needs

    2 fields per item

    • serverstring

      Name of a configured MCP server, or of the service when none is configured

    • whystring
  • networkstring

    Whether the job needs the internet

    One of none, internet

  • outputsarray of objects or null

    Small structured values each run reports

    3 fields per item

    • descriptionstring
    • namestring
    • typestring

      JSON type: string, integer, number, boolean, object or array

  • scheduleobject

    The schedule the instruction asks for, which only takes effect through the job's cron and timezone

    2 fields

    • cronstring

      Five-field cron expression

    • timezonestring

      IANA time zone the expression runs in, such as Europe/Berlin

  • sideEffectsarray of strings or null

    Changes the job makes outside its sandbox and when, such as posting a message when there is something to report

  • successCriteriaarray of strings or null

    The end state a successful run leaves behind, which the agent reads with the instruction

  • titlestring

    Short name for the job

• timezonestring or null
• updatedAtinteger

Compile job

post/api/jobs/compile

Body application/json

• instructionstringrequired

  1 to 20000 characters

• askQuestionsboolean

  Whether the compile step may ask questions, true when omitted; false once the user answered them, so answers never lead to another round

• timezonestring

  IANA time zone of the person writing the instruction, such as Europe/Zurich, which the schedule uses when the instruction names none; UTC when omitted

  at most 100 characters

Response

200 OKapplication/json

4 fields

• questionsarray of objects or null
  2 fields per item

  • optionsarray of strings or null

    Likely answers the user can pick, empty when only the user can know

  • questionstring
• secretsarray of objects or null

  Credentials the job's commands need as environment variables

  3 fields per item

  • envNamestring
  • secretstring

    Name of the configured secret that holds the value, empty when none does

  • whystring
• skillsarray of strings or null

  Names of configured skills that fit the job

• specobject
  10 fields

  • dockerfilestring or null

    Dockerfile for jobs that need tools beyond the default sandbox image, null otherwise

  • goalstring

    One sentence on the outcome

  • inputsarray of objects or null

    Values a run reads from /ump/input.json

    3 fields per item

    • descriptionstring
    • namestring
    • typestring

      JSON type: string, integer, number, boolean, object or array

  • mcparray of objects or null

    MCP servers the job needs

    2 fields per item

    • serverstring

      Name of a configured MCP server, or of the service when none is configured

    • whystring
  • networkstring

    Whether the job needs the internet

    One of none, internet

  • outputsarray of objects or null

    Small structured values each run reports

    3 fields per item

    • descriptionstring
    • namestring
    • typestring

      JSON type: string, integer, number, boolean, object or array

  • scheduleobject

    The schedule the instruction asks for, which only takes effect through the job's cron and timezone

    2 fields

    • cronstring

      Five-field cron expression

    • timezonestring

      IANA time zone the expression runs in, such as Europe/Berlin

  • sideEffectsarray of strings or null

    Changes the job makes outside its sandbox and when, such as posting a message when there is something to report

  • successCriteriaarray of strings or null

    The end state a successful run leaves behind, which the agent reads with the instruction

  • titlestring

    Short name for the job

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
• demotionstring

  Why repeated fallbacks or handovers took a graduated job back to Assisted, missing while it isn't demoted

  One of fell_back, handed_over

• graduateboolean

  Whether the job may graduate to a main script that runs without the agent

• 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
  5 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    Spend per run in USD, where 0 turns the limit off

    at least 0

  • maxTurnsinteger

    Model calls the agent may make per run

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • timeoutSecondsinteger

    30 to 86400

• modelIdstring or null
• namestring
• networkstring

  One of none, internet, allowlist, unrestricted

• nextModestring

  One of explore, assisted, scripted

• nextRunAtinteger or null
• pausedboolean

  Whether the schedule and the webhook are paused, which leaves manual and API runs alone

• playbookVersioninteger
• runAsRootboolean
• selfImproveboolean
• specobject
  10 fields

  • dockerfilestring or null

    Dockerfile for jobs that need tools beyond the default sandbox image, null otherwise

  • goalstring

    One sentence on the outcome

  • inputsarray of objects or null

    Values a run reads from /ump/input.json

    3 fields per item

    • descriptionstring
    • namestring
    • typestring

      JSON type: string, integer, number, boolean, object or array

  • mcparray of objects or null

    MCP servers the job needs

    2 fields per item

    • serverstring

      Name of a configured MCP server, or of the service when none is configured

    • whystring
  • networkstring

    Whether the job needs the internet

    One of none, internet

  • outputsarray of objects or null

    Small structured values each run reports

    3 fields per item

    • descriptionstring
    • namestring
    • typestring

      JSON type: string, integer, number, boolean, object or array

  • scheduleobject

    The schedule the instruction asks for, which only takes effect through the job's cron and timezone

    2 fields

    • cronstring

      Five-field cron expression

    • timezonestring

      IANA time zone the expression runs in, such as Europe/Berlin

  • sideEffectsarray of strings or null

    Changes the job makes outside its sandbox and when, such as posting a message when there is something to report

  • successCriteriaarray of strings or null

    The end state a successful run leaves behind, which the agent reads with the instruction

  • titlestring

    Short name for the job

• 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

  Five-field cron expression or a descriptor such as @daily, where an empty string stops the schedule

  at most 100 characters

• graduateboolean
• imagestring

  at most 500 characters

• instructionstring

  What the agent does, which it reads on every run

  1 to 20000 characters

• limitsobject
  5 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    Spend per run in USD, where 0 turns the limit off

    at least 0

  • maxTurnsinteger

    Model calls the agent may make per run

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • timeoutSecondsinteger

    30 to 86400

• modelIdstring
• namestring

  1 to 200 characters

• networkstring

  One of none, internet, allowlist, unrestricted

• pausedboolean

  Whether the schedule and the webhook are paused, which leaves manual and API runs alone

• rebuildSpecboolean

  Whether a changed instruction compiles the goal, success criteria, inputs, outputs, services and side effects again, true when omitted

• runAsRootboolean
• selfImproveboolean
• specobject
  10 fields

  • dockerfilestring or nullrequired

    Dockerfile for jobs that need tools beyond the default sandbox image, null otherwise

  • goalstringrequired

    One sentence on the outcome

  • inputsarray of objects or nullrequired

    Values a run reads from /ump/input.json

    3 fields per item

    • namestringrequired
    • typestringrequired

      JSON type: string, integer, number, boolean, object or array

    • descriptionstring
  • mcparray of objects or nullrequired

    MCP servers the job needs

    2 fields per item

    • serverstringrequired

      Name of a configured MCP server, or of the service when none is configured

    • whystringrequired
  • networkstringrequired

    Whether the job needs the internet

    One of none, internet

  • outputsarray of objects or nullrequired

    Small structured values each run reports

    3 fields per item

    • namestringrequired
    • typestringrequired

      JSON type: string, integer, number, boolean, object or array

    • descriptionstring
  • sideEffectsarray of strings or nullrequired

    Changes the job makes outside its sandbox and when, such as posting a message when there is something to report

  • successCriteriaarray of strings or nullrequired

    The end state a successful run leaves behind, which the agent reads with the instruction

  • titlestringrequired

    Short name for the job

  • scheduleobject

    The schedule the instruction asks for, which only takes effect through the job's cron and timezone

    2 fields

    • cronstringrequired

      Five-field cron expression

    • timezonestringrequired

      IANA time zone the expression runs in, such as Europe/Berlin

• timezonestring

  at most 100 characters

Response

200 OKapplication/json

26 fields

• allowPrivateNetworkboolean
• allowedDomainsarray of strings or null
• concurrencystring
• createdAtinteger
• cronstring or null
• demotionstring

  Why repeated fallbacks or handovers took a graduated job back to Assisted, missing while it isn't demoted

  One of fell_back, handed_over

• graduateboolean

  Whether the job may graduate to a main script that runs without the agent

• 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
  5 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    Spend per run in USD, where 0 turns the limit off

    at least 0

  • maxTurnsinteger

    Model calls the agent may make per run

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • timeoutSecondsinteger

    30 to 86400

• modelIdstring or null
• namestring
• networkstring

  One of none, internet, allowlist, unrestricted

• nextModestring

  One of explore, assisted, scripted

• nextRunAtinteger or null
• pausedboolean

  Whether the schedule and the webhook are paused, which leaves manual and API runs alone

• playbookVersioninteger
• runAsRootboolean
• selfImproveboolean
• specobject
  10 fields

  • dockerfilestring or null

    Dockerfile for jobs that need tools beyond the default sandbox image, null otherwise

  • goalstring

    One sentence on the outcome

  • inputsarray of objects or null

    Values a run reads from /ump/input.json

    3 fields per item

    • descriptionstring
    • namestring
    • typestring

      JSON type: string, integer, number, boolean, object or array

  • mcparray of objects or null

    MCP servers the job needs

    2 fields per item

    • serverstring

      Name of a configured MCP server, or of the service when none is configured

    • whystring
  • networkstring

    Whether the job needs the internet

    One of none, internet

  • outputsarray of objects or null

    Small structured values each run reports

    3 fields per item

    • descriptionstring
    • namestring
    • typestring

      JSON type: string, integer, number, boolean, object or array

  • scheduleobject

    The schedule the instruction asks for, which only takes effect through the job's cron and timezone

    2 fields

    • cronstring

      Five-field cron expression

    • timezonestring

      IANA time zone the expression runs in, such as Europe/Berlin

  • sideEffectsarray of strings or null

    Changes the job makes outside its sandbox and when, such as posting a message when there is something to report

  • successCriteriaarray of strings or null

    The end state a successful run leaves behind, which the agent reads with the instruction

  • titlestring

    Short name for the job

• 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

List job suggestions

get/api/jobs/{id}/suggestions

Path parameters

• idstringrequired

Response

200 OKapplication/json

11 fields per item

• createdAtinteger
• idstring
• keystring

  The suggestion's subject, which later runs that raise it again update

• kindstring

  One of limits, credentials, instruction

• limitsobject

  For kind limits: the limits applying the suggestion sets

  4 fields

  • cpusnumber

    0.1 to 64

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • timeoutSecondsinteger

    30 to 86400

• limitsBeforeobject

  For kind limits: the job's limits when the suggestion was raised

  4 fields

  • cpusnumber

    0.1 to 64

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • timeoutSecondsinteger

    30 to 86400

• runIdstring or null

  The latest run whose reflection raised it

• runNumberinteger or null

  The number of that run, null once the run was deleted

• seeninteger

  How many runs' reflections raised it

• textstring

  What to change and what in the run showed it, written by reflection

• updatedAtinteger

Apply job suggestion

post/api/jobs/{id}/suggestions/{suggestionId}/apply

Path parameters

• idstringrequired
• suggestionIdstringrequired

Response

204 No Content

Dismiss job suggestion

post/api/jobs/{id}/suggestions/{suggestionId}/dismiss

Path parameters

• idstringrequired
• suggestionIdstringrequired

Response

204 No Content

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
• post/api/runs/deleteDelete runs
• get/api/runs/{id}Get run
• delete/api/runs/{id}Delete 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
  5 data fields

  • deletedboolean
  • 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

Delete runs

post/api/runs/delete

Body application/json

• idsarray of strings or nullrequired

  The runs to delete

  1 to 100 items

Response

200 OKapplication/json

2 fields

• deletedarray of strings or null

  The runs that were deleted

• skippedarray of strings or null

  The runs that were left alone because they don't exist or haven't finished

Get run

get/api/runs/{id}

Examples and details in Read a run.

Path parameters

• idstringrequired

Response

200 OKapplication/json

47 fields

• cancelRequestedboolean
• costinteger

  Micro-USD

• errorstring or null
• fellBackboolean
• finishedAtinteger or null
• handedOverboolean

  Whether the run's main script handed a case it can't handle to the agent

• idstring
• imageRefstring or null
• inputany
• instructionsstring or null
• jobDeletedboolean

  Whether the run's job was deleted, so the run can no longer be retried

• 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, suggest

  • 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
• reflectionTokensinteger

  Input and output tokens of the reflection on this run

• 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

• verifyTokensinteger

  Input and output tokens of the utility model's verification of a scripted run

Delete run

delete/api/runs/{id}

Path parameters

• idstringrequired

Response

204 No Content

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

6 fields per item

• msinteger 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

202 Accepted

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
  6 data fields

  • msinteger 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, suggest

  • 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, suggest

  • 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, suggest

  • 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, suggest

  • 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
• baseUpdatedAtinteger

  The updatedAt of the entry the edit started from, or 0 to only add a new key; a key changed or added meanwhile makes the save fail with 409

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

  Environment variable the runs get the secret's value in, such as GITHUB_TOKEN

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

• secretIdstring

  ID of a configured secret

• secretNamestring

Set job secrets

put/api/jobs/{id}/secrets

Path parameters

• idstringrequired

Body application/json

An array, with these fields per item:

• envNamestringrequired

  Environment variable the runs get the secret's value in, such as GITHUB_TOKEN

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

• secretIdstringrequired

  ID of a configured secret

Response

200 OKapplication/json

3 fields per item

• envNamestring

  Environment variable the runs get the secret's value in, such as GITHUB_TOKEN

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

• secretIdstring

  ID of a configured secret

• 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

  ID of a configured MCP server

• 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

  ID of a configured MCP server

Response

200 OKapplication/json

3 fields per item

• allowedToolsarray of strings or null

  null exposes all tools

• serverIdstring

  ID of a configured MCP server

• 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
    4 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

    • omitResourceboolean

      Leave the RFC 8707 resource parameter out of the login, for authorization servers like Entra ID that reject the one the server advertises

    • 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

  4 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

  • omitResourceboolean

    Leave the RFC 8707 resource parameter out of the login, for authorization servers like Entra ID that reject the one the server advertises

  • 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
  4 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

  • omitResourceboolean

    Leave the RFC 8707 resource parameter out of the login, for authorization servers like Entra ID that reject the one the server advertises

  • 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
  4 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

  • omitResourceboolean

    Leave the RFC 8707 resource parameter out of the login, for authorization servers like Entra ID that reject the one the server advertises

  • 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

  4 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

  • omitResourceboolean

    Leave the RFC 8707 resource parameter out of the login, for authorization servers like Entra ID that reject the one the server advertises

  • 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
  4 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

  • omitResourceboolean

    Leave the RFC 8707 resource parameter out of the login, for authorization servers like Entra ID that reject the one the server advertises

  • 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
  4 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

  • omitResourceboolean

    Leave the RFC 8707 resource parameter out of the login, for authorization servers like Entra ID that reject the one the server advertises

  • 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
  12 fields per item

  • apistring or null

    The API an OpenAI-compatible provider calls, null for other kinds

    One of responses, chat_completions

  • 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

• apistring

  The API an OpenAI-compatible provider calls, responses by default

  One of responses, chat_completions

• 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

• apistring

  The API an OpenAI-compatible provider calls

  One of responses, chat_completions

• 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

11 fields

• agentModelIdstring or null
• dailySpendLimitUsdnumber

  0 means no limit

• defaultImagestring
• defaultLimitsobject
  5 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    at least 0

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • 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

• usageUnitstring

  Whether the UI shows usage as a price in US dollars or as input and output tokens, while spend limits and model prices stay in US dollars

  One of price, tokens

• 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
  5 fields

  • cpusnumberrequired

    0.1 to 64

  • maxCostUsdnumberrequired

    at least 0

  • maxTurnsintegerrequired

    1 to 1000

  • memoryMbintegerrequired

    64 to 262144

  • 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

• usageUnitstring

  One of price, tokens

• utilityModelIdstring

Response

200 OKapplication/json

11 fields

• agentModelIdstring or null
• dailySpendLimitUsdnumber

  0 means no limit

• defaultImagestring
• defaultLimitsobject
  5 fields

  • cpusnumber

    0.1 to 64

  • maxCostUsdnumber

    at least 0

  • maxTurnsinteger

    1 to 1000

  • memoryMbinteger

    64 to 262144

  • 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

• usageUnitstring

  Whether the UI shows usage as a price in US dollars or as input and output tokens, while spend limits and model prices stay in US dollars

  One of price, tokens

• utilityModelIdstring or null

Test notification

post/api/settings/notifications/test

Response

204 No Content

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

10 fields

• avgCostinteger

  Average cost per run in micro-USD, including learning

• avgTokensinteger

  Average input and output tokens per run, including learning, like avgCost

• failedinteger

  Failed and timed out runs

• maxMsinteger

  Duration of the longest run

• p50Msinteger
• runCountinteger

  Runs of the range other than skipped ones

• runsarray of objects or null
  10 fields per item

  • costinteger

    Micro-USD, including learning

  • modestring
  • msTotalinteger or null
  • numberinteger
  • playbookVersioninteger
  • queuedAtinteger
  • runIdstring
  • statusstring
  • tokensinteger

    Input and output tokens, including learning, like cost

  • turnsinteger
• succeededinteger
• 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

14 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
  5 fields per item

  • costinteger

    Micro-USD, including learning

  • dayinteger

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

  • jobIdstring
  • jobNamestring
  • tokensinteger

    Input and output tokens, including learning, like cost

• currentobject
  10 fields

  • failedinteger
  • learningCostinteger

    Micro-USD

  • learningTokensinteger

    Input and output tokens of reflection and verification, like learningCost

  • p50Msinteger
  • p95Msinteger
  • runCostinteger

    Micro-USD

  • runTokensinteger

    Input and output tokens of the runs, like runCost

  • 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

  Up to five jobs whose latest successful runs cost less than their first ones, the biggest drop in cost first

  9 fields per item

  • dropPctnumber

    How much less the latest runs cost, from 0 to 1

  • firstCostinteger

    Average cost of the first three successful runs, in micro-USD

  • firstTokensinteger

    Average input and output tokens of the first three successful runs

  • jobIdstring
  • jobNamestring
  • recentCostinteger

    Average cost of the latest three successful runs, in micro-USD

  • recentTokensinteger

    Average input and output tokens of the latest three successful runs

  • runsinteger
  • tokenDropPctnumber

    How many fewer tokens the latest runs used, from 0 to 1, and negative when they used more

• gettingLeanerarray of objects or null

  Up to five jobs whose latest successful runs used fewer tokens than their first ones, the biggest drop in tokens first

  9 fields per item

  • dropPctnumber

    How much less the latest runs cost, from 0 to 1

  • firstCostinteger

    Average cost of the first three successful runs, in micro-USD

  • firstTokensinteger

    Average input and output tokens of the first three successful runs

  • jobIdstring
  • jobNamestring
  • recentCostinteger

    Average cost of the latest three successful runs, in micro-USD

  • recentTokensinteger

    Average input and output tokens of the latest three successful runs

  • runsinteger
  • tokenDropPctnumber

    How many fewer tokens the latest runs used, from 0 to 1, and negative when they used more

• hasRunsboolean

  Whether the workspace has any run at all, from any date

• 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

  9 fields per item

  • cancelledinteger
  • costinteger

    Micro-USD, including learning

  • dayinteger

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

  • failedinteger
  • otherinteger
  • skippedinteger
  • succeededinteger
  • timedOutinteger
  • tokensinteger

    Input and output tokens, including learning, like cost

• previousobject

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

  10 fields

  • failedinteger
  • learningCostinteger

    Micro-USD

  • learningTokensinteger

    Input and output tokens of reflection and verification, like learningCost

  • p50Msinteger
  • p95Msinteger
  • runCostinteger

    Micro-USD

  • runTokensinteger

    Input and output tokens of the runs, like runCost

  • 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
• post/api/auth/passkey/sign-inPasskey sign in
• post/api/auth/passkey/sign-in/optionsBegin passkey sign in
• post/api/auth/passkey/sign-upPasskey sign up
• post/api/auth/passkey/sign-up/optionsBegin passkey sign up
• get/api/auth/providersList login providers
• get/api/auth/setupGet setup
• post/api/auth/sign-in-linkUse sign in link
• get/api/users/meGet current user
• patch/api/users/meUpdate my profile
• get/api/users/me/passkeysList my passkeys
• post/api/users/me/passkeysAdd passkey
• post/api/users/me/passkeys/optionsBegin add passkey
• patch/api/users/me/passkeys/{id}Rename passkey
• delete/api/users/me/passkeys/{id}Delete passkey

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

Cookies

• umpteenth_sessionobject

Response

204 No Content

Passkey sign in

post/api/auth/passkey/sign-in

Cookies

• umpteenth_passkeyobject

Body application/json

• credentialanyrequired

  The PublicKeyCredential the browser created or signed with, in its JSON form

Response

200 OKapplication/json

1 field

• redirectstring

  Relative path to continue at

Begin passkey sign in

post/api/auth/passkey/sign-in/options

Body application/json

• redirectstring

  Relative path to return to after signing in

Response

200 OKapplication/json

1 field

• optionsany

  The publicKey options for navigator.credentials, in their JSON form

Passkey sign up

post/api/auth/passkey/sign-up

Cookies

• umpteenth_passkeyobject

Body application/json

• credentialanyrequired

  The PublicKeyCredential the browser created or signed with, in its JSON form

Response

200 OKapplication/json

1 field

• redirectstring

  Relative path to continue at

Begin passkey sign up

post/api/auth/passkey/sign-up/options

Body application/json

• namestringrequired

  1 to 100 characters

• emailstring

  at most 254 characters

• redirectstring

  Relative path to continue at, which is the invite page for a sign-up through an invite link

Response

200 OKapplication/json

1 field

• optionsany

  The publicKey options for navigator.credentials, in their JSON form

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, where passkey stands for passkey accounts

  One of oidc, github, passkey

Get setup

get/api/auth/setup

Response

200 OKapplication/json

1 field

• openboolean

  Whether the instance has no users yet, so whoever opens it creates its first account, an instance admin, with a passkey

Use sign in link

post/api/auth/sign-in-link

Body application/json

• tokenstringrequired

  The token at the end of the sign-in link

  at least 1 characters

Response

200 OKapplication/json

1 field

• redirectstring

  Relative path to continue at

Get current user

get/api/users/me

Response

200 OKapplication/json

11 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
• passkeyAccountboolean

  Whether the user signs in with passkeys and keeps their own name and email address, instead of a sign-in provider

• picturestring or null

  Profile picture URL from the sign-in provider

• viaTokenboolean
• workspaceobject
  4 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

  • usageUnitstring

    Whether the UI shows usage as a price in US dollars or as input and output tokens, the workspace's usageUnit setting

    One of price, tokens

• workspaceIdstring
• workspacesEnabledboolean

  Whether people can have several workspaces on this instance

Update my profile

patch/api/users/me

Body application/json

• namestringrequired

  1 to 100 characters

• emailstring

  at most 254 characters

Response

204 No Content

List my passkeys

get/api/users/me/passkeys

Response

200 OKapplication/json

4 fields per item

• createdAtinteger
• idstring
• lastUsedAtinteger or null
• namestring

Add passkey

post/api/users/me/passkeys

Cookies

• umpteenth_passkeyobject

Body application/json

• credentialanyrequired

  The PublicKeyCredential the browser created or signed with, in its JSON form

Response

200 OKapplication/json

4 fields

• createdAtinteger
• idstring
• lastUsedAtinteger or null
• namestring

Begin add passkey

post/api/users/me/passkeys/options

Response

200 OKapplication/json

1 field

• optionsany

  The publicKey options for navigator.credentials, in their JSON form

Rename passkey

patch/api/users/me/passkeys/{id}

Path parameters

• idstringrequired

Body application/json

• namestringrequired

  1 to 100 characters

Response

204 No Content

Delete passkey

delete/api/users/me/passkeys/{id}

Path parameters

• idstringrequired

Response

204 No Content

System

• get/api/system/infoGet system info

Get system info

get/api/system/info

Response

200 OKapplication/json

4 fields

• allowPrivateNetworkTargetsboolean
• databasestring
• sandboxobject
  7 fields

  • adapterstring
  • archstring
  • capabilitiesobject
    2 fields

    • limitsobject
      3 fields

      • cpuboolean
      • memoryboolean
      • pidsboolean
    • networksarray of strings or null
  • imageBuildsboolean
  • isolationstring

    One of container, gvisor, microvm

  • runtimeErrorstring
  • versionstring
• versionstring

Admin

• get/api/admin/usersList users
• post/api/admin/usersCreate user
• patch/api/admin/users/{id}Update user
• post/api/admin/users/{id}/sign-in-linkCreate sign in link
• 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
  12 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
  • passkeyAccountboolean

    Whether the account signs in with passkeys, which instance admins manage, instead of a sign-in provider

  • 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

Create user

post/api/admin/users

Body application/json

• namestringrequired

  1 to 100 characters

• emailstring

  Counts as verified, so invites sent to it reach the account

  at most 254 characters

• isAdminboolean

  Makes the account an instance admin

Response

200 OKapplication/json

2 fields

• signInLinkobject
  2 fields

  • expiresAtinteger
  • urlstring

    Signs in the account once, so its owner can add a passkey

• userobject
  12 fields

  • 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
  • passkeyAccountboolean

    Whether the account signs in with passkeys, which instance admins manage, instead of a sign-in provider

  • 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

Update user

patch/api/admin/users/{id}

Path parameters

• idstringrequired

Body application/json

• deactivatedboolean

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

• isAdminboolean

  Makes a passkey account an instance admin or takes that away, while sign-in providers decide on their own accounts

Response

204 No Content

Create sign in link

post/api/admin/users/{id}/sign-in-link

Path parameters

• idstringrequired

Response

200 OKapplication/json

2 fields

• expiresAtinteger
• urlstring

  Signs in the account once, so its owner can add a passkey

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

Skills

• get/api/jobs/{id}/skillsGet job skills
• put/api/jobs/{id}/skillsSet job skills
• get/api/skillsList skills
• post/api/skillsCreate skill
• post/api/skills/deleteDelete skills
• post/api/skills/importImport skill
• post/api/skills/import/previewPreview skill import
• get/api/skills/{id}Get skill
• put/api/skills/{id}Replace skill
• delete/api/skills/{id}Delete skill
• get/api/skills/{id}/downloadDownload skill
• get/api/skills/{id}/fileGet skill file
• post/api/skills/{id}/importReimport skill

Get job skills

get/api/jobs/{id}/skills

Path parameters

• idstringrequired

Response

200 OKapplication/json

2 fields per item

• skillIdstring

  ID of an uploaded skill

• skillNamestring

Set job skills

put/api/jobs/{id}/skills

Path parameters

• idstringrequired

Body application/json

An array, with these fields per item:

• skillIdstringrequired

  ID of an uploaded skill

Response

200 OKapplication/json

2 fields per item

• skillIdstring

  ID of an uploaded skill

• skillNamestring

List skills

get/api/skills

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
  12 fields per item

  • archiveSizeinteger

    Size of the stored zip in bytes

  • contentHashstring
  • createdAtinteger
  • descriptionstring
  • fileCountinteger
  • filesarray of objects or null
    3 fields per item

    • executableboolean
    • pathstring
    • sizeinteger
  • idstring
  • jobCountinteger

    How many jobs use the skill

  • namestring
  • sizeinteger

    Unpacked size in bytes

  • sourceUrlstring or null

    The link the skill was imported from, null for an uploaded skill

  • updatedAtinteger
• pageinteger
• pageSizeinteger
• totalinteger

Create skill

post/api/skills

Body application/zip

binary The raw request body.

Response

200 OKapplication/json

12 fields

• archiveSizeinteger

  Size of the stored zip in bytes

• contentHashstring
• createdAtinteger
• descriptionstring
• fileCountinteger
• filesarray of objects or null
  3 fields per item

  • executableboolean
  • pathstring
  • sizeinteger
• idstring
• jobCountinteger

  How many jobs use the skill

• namestring
• sizeinteger

  Unpacked size in bytes

• sourceUrlstring or null

  The link the skill was imported from, null for an uploaded skill

• updatedAtinteger

Delete skills

post/api/skills/delete

Body application/json

• idsarray of strings or nullrequired

  The skills to delete

  1 to 100 items

Response

200 OKapplication/json

2 fields

• deletedarray of strings or null

  The skills that were deleted

• skippedarray of strings or null

  The skills that were left alone because they don't exist, such as ones deleted meanwhile

Import skill

post/api/skills/import

Body application/json

• urlstringrequired

  A GitHub link to a skill's folder or its SKILL.md, or a link to a zip or .skill file

  1 to 2000 characters

• pathsarray of strings or null

  The skills to add from a GitHub folder of several, as folders relative to it like the preview lists them

  at most 50 items

Response

200 OKapplication/json

1 field

• skillsarray of objects or null
  12 fields per item

  • archiveSizeinteger

    Size of the stored zip in bytes

  • contentHashstring
  • createdAtinteger
  • descriptionstring
  • fileCountinteger
  • filesarray of objects or null
    3 fields per item

    • executableboolean
    • pathstring
    • sizeinteger
  • idstring
  • jobCountinteger

    How many jobs use the skill

  • namestring
  • sizeinteger

    Unpacked size in bytes

  • sourceUrlstring or null

    The link the skill was imported from, null for an uploaded skill

  • updatedAtinteger

Preview skill import

post/api/skills/import/preview

Body application/json

• urlstringrequired

  A GitHub link to a folder or repository with skills

  1 to 2000 characters

Response

200 OKapplication/json

1 field

• skillsarray of objects or null
  6 fields per item

  • descriptionstring
  • existsboolean

    Whether the workspace already has a skill with this name

  • namestring
  • pathstring

    The skill's folder, relative to the folder the link points at

  • problemstring

    Why the skill can't be added, such as a SKILL.md without a description

  • urlstring

    A link to the skill's own folder

Get skill

get/api/skills/{id}

Path parameters

• idstringrequired

Response

200 OKapplication/json

12 fields

• archiveSizeinteger

  Size of the stored zip in bytes

• contentHashstring
• createdAtinteger
• descriptionstring
• fileCountinteger
• filesarray of objects or null
  3 fields per item

  • executableboolean
  • pathstring
  • sizeinteger
• idstring
• jobCountinteger

  How many jobs use the skill

• namestring
• sizeinteger

  Unpacked size in bytes

• sourceUrlstring or null

  The link the skill was imported from, null for an uploaded skill

• updatedAtinteger

Replace skill

put/api/skills/{id}

Path parameters

• idstringrequired

Body application/zip

binary The raw request body.

Response

200 OKapplication/json

12 fields

• archiveSizeinteger

  Size of the stored zip in bytes

• contentHashstring
• createdAtinteger
• descriptionstring
• fileCountinteger
• filesarray of objects or null
  3 fields per item

  • executableboolean
  • pathstring
  • sizeinteger
• idstring
• jobCountinteger

  How many jobs use the skill

• namestring
• sizeinteger

  Unpacked size in bytes

• sourceUrlstring or null

  The link the skill was imported from, null for an uploaded skill

• updatedAtinteger

Delete skill

delete/api/skills/{id}

Path parameters

• idstringrequired

Response

204 No Content

Download skill

get/api/skills/{id}/download

Path parameters

• idstringrequired

Response

200 OK

Get skill file

get/api/skills/{id}/file

Path parameters

• idstringrequired

Query parameters

• pathstringrequired

Response

200 OK

Reimport skill

post/api/skills/{id}/import

Path parameters

• idstringrequired

Body application/json

• urlstring

  The link to import the new version from, the skill's own link when omitted

  at most 2000 characters

Response

200 OKapplication/json

12 fields

• archiveSizeinteger

  Size of the stored zip in bytes

• contentHashstring
• createdAtinteger
• descriptionstring
• fileCountinteger
• filesarray of objects or null
  3 fields per item

  • executableboolean
  • pathstring
  • sizeinteger
• idstring
• jobCountinteger

  How many jobs use the skill

• namestring
• sizeinteger

  Unpacked size in bytes

• sourceUrlstring or null

  The link the skill was imported from, null for an uploaded skill

• updatedAtinteger

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 the next time they sign in with it verified; omit it for an invite link

  at most 320 characters

Response

200 OKapplication/json

1 field

• 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