trickroom / Docs
Sign in
API reference/flows

Submit a versioned flow as a job

Requires Idempotency-Key or idempotency_key, the current flow version, exact named inputs, and user-owned connections for the selected plugins. A flow is instructions for one agent job, not independently checkpointed workflow steps. Retries reuse the job while that flow version is current. After an update or archive, a repeated submission can return 409/404: retain the returned job ID and use getJob to track it.

POST/v1/applications/{id}/flows/{flowId}/run

Authorization

Authorizationstringrequired

Bearer tak_… — an application API key. Keep it on your backend; all resources are scoped to that application.

Create an application key →

Path parameters

idstringrequired

Min length: 1

flowIdstringrequired

Min length: 1

Body application/json

user_idstringrequired

Min length: 1

versionintegerrequired

Maximum: 9007199254740991

inputsobject

Default: {}

Additional keys: string

connection_idsarray<string>

Max items: 12

idempotency_keystring

Min length: 1 · Max length: 200 · Pattern: ^[\x21-\x7e]+$

Response

202Submit a versioned flow as a job
X-Request-Idstring

Server-generated request identifier for logs and support.

application/json

idstringrequired

Min length: 1

user_idstringrequired

Min length: 1

application_idstring

Min length: 1

sequenceintegerrequired

Minimum: -9007199254740991 · Maximum: 9007199254740991

taskstringrequired
statusstringrequired

Allowed: "queued""provisioning""running""waiting_approval""completed""failed""cancelled""timed_out"

execution_modestringrequired

Allowed: "computer""tools"

created_atstringrequired

Format: date-time · Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

started_atstring | nullrequired
completed_atstring | nullrequired
computer_idstring | nullrequired
instructionsstring | null
reasoning_effortstring | null
max_output_tokensinteger | null
errorstring | nullrequired
failure_classstring | null
computer_ready_atstring | null
computer_startstring | null
first_output_atstring | null
result_jsonobject | nullrequired
evaluationobjectrequired

Additional keys: any

viewer_urlstringrequired

Format: uri

is_controllerbooleanrequired
flow_idstring | null
flow_snapshot_jsonobject | null
harness_version_idstring | null
harness_jsonobject | null
Allowed shapes

object

harness_idstringrequired

Min length: 1

namestringrequired
version_idstringrequired

Min length: 1

numberintegerrequired

Minimum: -9007199254740991 · Maximum: 9007199254740991

specobjectrequired

Additional keys: any

null

valuenull
cost_nanoobject
Object fields
model_usagenumberrequired
computer_timenumberrequired
kept_computernumberrequired
totalnumberrequired

Additional keys: any

4XX400 invalid input; 401 missing/revoked credentials; 403 disallowed operation/application; 404 missing or inaccessible resource; 409 conflicting submission/version/state; 413 body too large; 415 unsupported content type. Inspect error.code, not message text.
X-Request-Idstring

Server-generated request identifier for logs and support.

application/json

errorobjectrequired
Object fields
codestringrequired
messagestringrequired
request_idstringrequired

Additional keys: any

5XX500 unexpected failure or 503 unavailable dependency. A failed response does not prove that a submission was not committed. Retry job/flow admission with the same key and body.
X-Request-Idstring

Server-generated request identifier for logs and support.

application/json

errorobjectrequired
Object fields
codestringrequired
messagestringrequired
request_idstringrequired

Additional keys: any