Quickstart

Create and poll your first Research Agent task.

Research runs asynchronously. Creating a task returns immediately with a URL you can poll for the result.

1. Set your credentials

Keep your token and agent ID in server-side environment variables:

export SIBI_ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export RESEARCH_AGENT_ID="<AGENT_ID>"

2. Create a research task

curl --request POST \
  "https://agents.sibi.ai/api/agents/${RESEARCH_AGENT_ID}/tasks/create" \
  --header "Authorization: Bearer ${SIBI_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"message":"GE GTS18GTHWW"}'

const taskResponse = await fetch(
  `https://agents.sibi.ai/api/agents/${process.env.RESEARCH_AGENT_ID}/tasks/create`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SIBI_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message: 'GE GTS18GTHWW' }),
  },
);

if (!taskResponse.ok) {
  throw new Error(`Task creation failed: ${taskResponse.status}`);
}

const task = await taskResponse.json();

The API responds with 202 Accepted:

{
  "status": "pending",
  "taskId": "<TASK_ID>",
  "statusUrl": "https://agents.sibi.ai/api/agents/<AGENT_ID>/tasks/<TASK_ID>"
}

3. Poll the status URL

Send authenticated GET requests to the exact statusUrl from the response.

curl \
  --header "Authorization: Bearer ${SIBI_ACCESS_TOKEN}" \
  "https://agents.sibi.ai/api/agents/${RESEARCH_AGENT_ID}/tasks/<TASK_ID>"

const resultResponse = await fetch(task.statusUrl, {
  headers: {
    Authorization: `Bearer ${process.env.SIBI_ACCESS_TOKEN}`,
  },
});

if (!resultResponse.ok) {
  throw new Error(`Task lookup failed: ${resultResponse.status}`);
}

const result = await resultResponse.json();

While the research is running, the response remains:

{
  "status": "pending",
  "taskId": "<TASK_ID>"
}

Continue until status is complete or failed.

4. Read the result

A completed single-product task includes the interpreted product and its candidate replacements:

{
  "status": "complete",
  "taskId": "<TASK_ID>",
  "taskUrl": "https://agents.sibi.ai/agents/<AGENT_ID>/tasks/<TASK_ID>",
  "productBeingReplaced": {
    "manufacturer": "GE",
    "model": "GTS18GTHWW",
    "description": "Top-freezer refrigerator",
    "specifications": "Capacity, dimensions, finish, electrical requirements, and features",
    "imageUrl": "https://example.com/ge-gts18gthww.jpg"
  },
  "candidateReplacements": [
    {
      "manufacturer": "Example Manufacturer",
      "model": "EXAMPLE-18W",
      "description": "Comparable top-freezer refrigerator",
      "specifications": "Capacity, dimensions, finish, electrical requirements, and features",
      "msrp": 899,
      "sibiProductId": "sibi-example-EXAMPLE-18W",
      "sibiManufacturer": "example",
      "sibiPrice": 849,
      "sibiCheckoutLink": "https://checkout.sibipro.com/...",
      "matchReasoning": "Comparable form factor, capacity, finish, and installation requirements.",
      "availableOnSibi": true,
      "imageUrl": "https://example.com/example-18w.jpg"
    }
  ]
}

The values above are illustrative. See Result objects for the complete field contract and batch response shape.