Skip to main content
POST
/
v1
/
session-batches
Create Session Batch
curl --request POST \
  --url https://api.dari.dev/v1/session-batches \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "idempotency_key": "<string>",
  "items": [
    {}
  ],
  "items[].agent_id": "<string>",
  "items[].version_id": "<string>",
  "items[].llm_id": "<string>",
  "items[].metadata": {},
  "items[].secrets": {},
  "items[].message.content": [
    {}
  ]
}
'
{
  "batch_id": "batch_123",
  "status": "queued",
  "sessions": [
    {
      "index": 0,
      "session_id": "sess_123",
      "status": "queued",
      "last_message_status": "queued",
      "agent_id": "agt_123",
      "version_id": "ver_9",
      "llm_id": "medium-claude",
      "metadata": {
        "managed_run_id": "run_123",
        "kind": "tester",
        "task_index": "1",
        "llm_id": "medium-claude"
      },
      "transcript_url": "/v1/sessions/sess_123/transcript",
      "error": null
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.dari.dev/llms.txt

Use this file to discover all available pages before exploring further.

Create a batch when you need to run one agent across many inputs, model choices, or test cases. All items in a batch must use the same agent_id. The request creates each session, sends its first user.message, and returns the session IDs in the same order as the input items array. 
curl -X POST https://api.dari.dev/v1/session-batches \
  -H "Authorization: Bearer $DARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "docs-run-2026-05-15",
    "items": [
      {
        "agent_id": "agt_123",
        "version_id": "ver_9",
        "llm_id": "medium-claude",
        "metadata": {
          "managed_run_id": "run_123",
          "kind": "tester",
          "task_index": "1",
          "llm_id": "medium-claude"
        },
        "message": {
          "content": [
            { "type": "text", "text": "Test task 1 with Claude." },
            { "type": "file", "file_id": "file_abc" }
          ]
        }
      }
    ]
  }'
Batch creation uses partial-failure semantics. Dari attempts each item in order. Successful items keep their created session, and failed items are returned with status: "failed" and an error string. Retry the same request with the same idempotency_key to recover from a network failure without creating duplicate sessions.

​
Headers

​
Authorization
string
required
Bearer token using your Dari API key.
​
Content-Type
string
required
Use application/json.

​
Request Body

​
idempotency_key
string
Optional client-generated key. Reusing the same key for the same organization returns the original batch instead of creating duplicate sessions.
​
items
array
required
Session requests to create. Every item must use the same agent_id. The response preserves this order with each item’s index.
​
items[].agent_id
string
required
Agent ID for this session. This must match every other item in the batch.
​
items[].version_id
string
Optional version ID. If omitted, the session uses the agent’s active version.
​
items[].llm_id
string
Optional LLM option ID from the agent manifest.
​
items[].metadata
object
Optional string key/value metadata stored on the session and included in webhook payloads.
​
items[].secrets
object
Optional session-scoped secret values, using the same rules as Create Session.
​
items[].message.content
array
required
Initial user message content. Supports the same text, image, and file parts as session events.

​
Response Fields

​
batch_id
string
Batch ID used with Get Session Batch.
​
status
string
Aggregate batch status: queued, running, completed, failed, or partial_failed.
​
sessions
array
Per-item session results in input order.
{
  "batch_id": "batch_123",
  "status": "queued",
  "sessions": [
    {
      "index": 0,
      "session_id": "sess_123",
      "status": "queued",
      "last_message_status": "queued",
      "agent_id": "agt_123",
      "version_id": "ver_9",
      "llm_id": "medium-claude",
      "metadata": {
        "managed_run_id": "run_123",
        "kind": "tester",
        "task_index": "1",
        "llm_id": "medium-claude"
      },
      "transcript_url": "/v1/sessions/sess_123/transcript",
      "error": null
    }
  ]
}