Submit an asynchronous job

202 acknowledges durable admission, not successful execution. Without a key each call creates a job. Application and user must match. The job pins the active version of the harness it names, or of the application's default harness; settings the request leaves out come from that version, and settings it sets win. Tool-only jobs require approval_required and cannot use file_sha256 checks. Inspect status or subscribe to events for completion.

POST/v1/jobs

Authorization

Authorizationstringrequired

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

Create an application key →

Body application/json

user_idstringrequired

Min length: 1

application_idstring

Min length: 1

taskstringrequired

Min length: 1 · Max length: 20000

modelstring

Min length: 1 · Max length: 200

model_version_idstring

Min length: 1 · Max length: 200

instructionsstring

Min length: 1 · Max length: 12000

reasoning_effortstring

Allowed: "none""minimal""low""medium""high""xhigh""max"

max_output_tokensinteger

Minimum: 1 · Maximum: 128000

samplingobject

Object fields

temperaturenumber

Minimum: 0 · Maximum: 2

top_pnumber

Maximum: 1

seedinteger

Minimum: -9007199254740991 · Maximum: 9007199254740991

logprobsboolean

top_logprobsinteger

Minimum: 0 · Maximum: 20

return_token_idsboolean

evaluationobject

Object fields

namestringrequired

Min length: 1 · Max length: 100

versionstringrequired

Min length: 1 · Max length: 100

checksarray<object>required

Min items: 1 · Max items: 20

Allowed shapes

object

idstringrequired

Pattern: ^[a-zA-Z0-9_-]{1,80}$

kind"output_contains"required

textstringrequired

Min length: 1 · Max length: 4000

object

idstringrequired

Pattern: ^[a-zA-Z0-9_-]{1,80}$

kind"file_sha256"required

pathstringrequired

Min length: 1 · Max length: 1000 · Pattern: ^\/

sha256stringrequired

Pattern: ^[a-f0-9]{64}$

capture_screenshotsboolean

execution_modestring

Allowed: "computer""tools"

connection_idsarray<string>

Max items: 12

web_accessboolean

idempotency_keystring

Pattern: ^[\x21-\x7e]{1,200}$

action_policystring

Allowed: "approval_required""unrestricted"

harnessstring

Min length: 1 · Max length: 40 · Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$

harness_version_idstring

Min length: 1 · Max length: 200

Response

202Submit an asynchronous 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

curl --fail-with-body --request POST \ "$TRICKROOM_API_URL/jobs" \ -H "Authorization: Bearer $TRICKROOM_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: request-example-123' \ --data '{ "user_id": "usr_example", "task": "Summarize this text: Our team shipped its first release.", "execution_mode": "tools" }'

{ "id": "example", "user_id": "user_example", "sequence": 1, "task": "example", "status": "queued", "execution_mode": "computer", "created_at": "2026-09-16T12:00:00Z", "started_at": null, "completed_at": null, "computer_id": null, "error": null, "result_json": null, "evaluation": {}, "viewer_url": "https://your-app.example/jobs/job_example", "is_controller": false }

Submit an asynchronous job

Authorization

Headers

Body application/json

Response

application/json

application/json

application/json