Task lifecycle

Create, poll, and continue asynchronous Research Agent tasks.

Every Research Agent interaction is a task. A task preserves its conversation, so you can answer a clarification without starting the research over.

Create a task

POST /api/agents/{agentId}/tasks/create

The JSON body requires a non-empty message.

{
  "message": "18 cubic foot white refrigerator"
}

message can be a manufacturer part number, a full model designation, or a natural-language product description.

The endpoint returns 202 Accepted with status: "pending", a stable taskId, and the statusUrl to poll.

Poll a task

GET /api/agents/{agentId}/tasks/{taskId}

Keep the same bearer token, agentId, and taskId for every poll. Possible task states are:

Status	Meaning	Next action
`pending`	The task is still running, or a newly submitted follow-up has not been answered.	Poll the `statusUrl` again.
`complete`	A result or clarification question is available.	Consume the result or answer the question.
`failed`	Research did not complete.	Read `error`; decide whether to correct the request and create a new task.

Answer a clarification

Research Agent can return a structured question when the request is ambiguous:

{
  "status": "complete",
  "taskId": "<TASK_ID>",
  "taskUrl": "https://agents.sibi.ai/agents/<AGENT_ID>/tasks/<TASK_ID>",
  "context": "I found two possible product families.",
  "question": {
    "question": "Which manufacturer should I research?",
    "options": [
      {
        "label": "Manufacturer A",
        "description": "The model family used in the original installation"
      },
      {
        "label": "Manufacturer B",
        "description": null
      }
    ],
    "allowMultiple": false
  }
}

The complete status means the current turn finished; the task itself remains reusable. Send the selected answer as a new message:

curl --request POST \
  "https://agents.sibi.ai/api/agents/${RESEARCH_AGENT_ID}/tasks/<TASK_ID>/messages" \
  --header "Authorization: Bearer ${SIBI_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"message":"Manufacturer A"}'

The endpoint returns 202 Accepted and the same task identifiers. Resume polling its statusUrl.

Add attachments

Task creation and continuation accept an optional attachments array. Each item requires:

Field	Type	Description
`type`	`"file"`	Identifies the attachment as a file.
`url`	`string`	An `http(s)` URL or supported `data:` URL.
`mediaType`	`string`	The file’s media type.
`filename`	`string`	The filename presented to Research Agent.

{
  "message": "Find replacements for the products in this file.",
  "attachments": [
    {
      "type": "file",
      "url": "https://files.example.com/products.csv",
      "mediaType": "text/csv",
      "filename": "products.csv"
    }
  ]
}

Supported data: URL media types include images, PDF, CSV, legacy Excel, and XLSX. Use hosted https URLs for larger files.