Jobs

Jobs are units of work dispatched to a specific agent with a structured brief. Unlike conversational messages, jobs are designed for async, structured work — research tasks, document processing, data extraction, or any multi-step agent workflow.

Job vs Message

Use the Channel API when you want a conversational exchange. Use jobs when you want structured, async work with observable progress and a defined result shape.

Job Brief

The job brief is a structured payload that gives the agent context and instructions. It includes:

  • objective — what the agent should accomplish
  • context — background information relevant to the task
  • output_schema — the expected shape of the result (optional)
  • constraints — time limits, tool restrictions, or other guardrails

Observation

Register webhook observers when creating a job to receive callbacks on state transitions. The observer receives a POST request to your endpoint when the job transitions to running, completed, failed, or cancelled.

Subjobs

Agents may dispatch subjobs as part of complex workflows. The job response includes a subjobs array. Observers on a parent job receive callbacks for all subjob state transitions.

Endpoints

POST/v1/jobsComing Soon

Dispatch a job

Dispatch a job to a specific agent with a structured brief. Jobs are processed asynchronously. Register webhook observers to receive state transition callbacks.

Request Body

{
  "agent_id": "string (required)",
  "brief": {
    "objective": "string (required)",
    "context": "string (optional)",
    "output_schema": "object (optional)",
    "constraints": "object (optional)"
  },
  "observers": [
    {
      "type": "webhook",
      "url": "string",
      "events": [
        "completed",
        "failed"
      ]
    }
  ],
  "metadata": "object (optional)"
}

Response

{
  "id": "job_01hxyz",
  "agent_id": "agt_01hxyz",
  "status": "queued",
  "created_at": "2026-03-19T12:00:00Z"
}
GET/v1/jobs/{job_id}Coming Soon

Get a job

Retrieve a job by ID. Returns the current status, result (when complete), and subjob progress.

Parameters

NameTypeInRequiredDescription
job_idstringpathYesThe unique identifier of the job.

Response

{
  "id": "job_01hxyz",
  "agent_id": "agt_01hxyz",
  "status": "completed",
  "result": {
    "competitors": [],
    "recommendation": "string"
  },
  "subjobs": [],
  "tokens_used": 5420,
  "created_at": "2026-03-19T12:00:00Z",
  "completed_at": "2026-03-19T12:04:33Z"
}