Templates

Run template endpoint

Submits an owner-authenticated run for an active endpoint on a user-owned template. The API key user must own the template and endpoint, the key must have templates:run, file inputs must reference Public API fileIds, and execution may spend the owner's credits. Use Idempotency-Key so network retries do not submit duplicate jobs.

post/api/v1/templates/{template_id}/endpoints/{endpoint_id}/runs

Request

  • Base URL: https://api.studio.kaitoi.io (the document declares no server; this is the origin it was published from)
  • URL: https://api.studio.kaitoi.io/api/v1/templates/{template_id}/endpoints/{endpoint_id}/runs
  • Auth: HTTP bearer

Path parameters

template_idstring required
endpoint_idstring required

Headers

Idempotency-Keystring nullable
authorizationstring nullable

Request body

inputsobject

Input values keyed by exposed endpoint fieldName. File inputs should use {"type":"file","fileId":"..."}; primitive values may use typed wrappers or direct JSON values.

externalIdstring nullable
externalUserIdstring nullable

Developer end-user guard. Referenced files with externalUserId must match this value.

externalWorkspaceIdstring nullable

Example request

{
  "externalUserId": "user_789",
  "inputs": {
    "image": {
      "fileId": "2f8f8c5df80e4f76a5b7d1bbd6fae0ab.png",
      "type": "file"
    },
    "prompt": {
      "type": "string",
      "value": "A cinematic robot portrait"
    }
  }
}

Response

Accepted template endpoint run.

taskIdstring required

Workflow task id used to poll this template endpoint run.

sourceType'template_endpoint'
templateIdstring required
endpointIdstring required
status'queued' | 'running' | 'succeeded' | 'failed' required
progressinteger nullable
progressMessagestring nullable
nodesCountinteger nullable
nodeIndexinteger nullable
currentNodestring nullable
logsobject[]
externalIdstring nullable
externalUserIdstring nullable
externalWorkspaceIdstring nullable
outputsobject
errorobject nullable
executionTimeMsinteger nullable
createdAtstring date-time nullable
updatedAtstring date-time nullable

Changes

No recorded changes to this operation across all 1 revision of this API.