Claim work

⚠️
Preview — this feature is being built; the design below is the spec.
POST https://app.syntic.ai/v1/runners/work/claim

Long-poll for the next item of work for this runner. The call waits up to wait_seconds and returns 204 No Content if nothing arrived. A claimed item is leased to this runner for 60 seconds.

For how this fits into a full workflow, see Self-hosted runners.

Headers

HeaderRequiredValue
AuthorizationYesBearer <runner token>: a self-hosted runner token (srt_...) issued when the runner was registered. Inference and admin keys are refused. See Self-hosted runners.
syntic-betaYes, while in previewagents-2026-11-01. Without it the call fails with 400 beta_required. See Versioning.
Content-TypeYesapplication/json

Body parameters

ParameterTypeRequiredNotes
wait_secondsintegerNo0 to 30, default 25.
kindsarray of stringsNoRestrict to some kinds, for example only tool_call.
runner_versionstringNoReported in the runner’s version.

Response

200 OK, Content-Type: application/json

204 No Content with an empty body when no work arrived in time.

{
  "id": "work_01JCD3F5H7K9M1P3R5T7",
  "type": "runner_work",
  "kind": "tool_call",
  "session_id": "sesn_01JC7M2K4P6R8T0V2X4Z",
  "thread_id": "thr_01JCC1D3F5H7K9M1P3R5",
  "tool_call": {
    "tool_call_id": "call_31",
    "name": "syntic_shell",
    "arguments": {
      "command": "python /workspace/scripts/reconcile.py --month 2026-10"
    }
  },
  "attempt": 1,
  "lease_expires_at": "2026-11-05T10:01:41Z"
}
FieldTypeDescription
kindstringsession_start (prepare a workspace), tool_call (run one tool) or session_stop (clean up).
tool_callobjectFor tool_call: the call id, tool name and arguments the agent produced.
attemptinteger1 for the first lease. After 3 expired leases the agent receives a tool error instead.
lease_expires_atstringSend a heartbeat or a result before this time or the item returns to the queue.

Examples

curl -sS "https://app.syntic.ai/v1/runners/work/claim" \
  -H "Authorization: Bearer $SYNTIC_RUNNER_TOKEN" \
  -H "syntic-beta: agents-2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{
      "wait_seconds": 25,
      "runner_version": "1.3.0"
    }'

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

StatustypecodeWhen
400invalid_request_errorbeta_requiredThe syntic-beta header is missing.
401authentication_errorinvalid_runner_tokenThe runner token is unknown or the runner was deregistered.
409conflict_errorrunner_at_capacityThe runner already holds max_concurrent_sessions sessions.
429rate_limit_errorrate_limitedToo many requests; wait for Retry-After. See Rate-limit headers.
Was this page helpful?