Durable Chat Runs

Start a durable chat run. Returns 202 Accepted on first submission, 200 OK with idempotent: true when an idempotency key matches an existing run.

#Headers

#Body

$ curl https://api.sogni.ai/v1/chat/runs \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Storyboard a 5-shot neon teaser, 9:16, 15s."}
    ],
    "runtime_config": { "requireJobConfirmation": true }
  }'

const run = await sogni.chat.runs.create({
  messages: [{ role: 'user', content: 'Storyboard a 5-shot neon teaser, 9:16, 15s.' }],
  runtimeConfig: { requireJobConfirmation: true },
});

for await (const event of sogni.chat.runs.streamEvents(run.runId)) {
  if (event.type === 'run_awaiting_cost_confirmation') {
    await sogni.chat.runs.confirmCost(run.runId, {
      toolCallId: event.payload.toolCallId,
      decision: 'confirm',
    });
  }
}

import os, requests, uuid

resp = requests.post(
    "https://api.sogni.ai/v1/chat/runs",
    headers={
        "Authorization": f"Bearer {os.environ['SOGNI_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "messages": [{"role": "user", "content": "Storyboard a 5-shot neon teaser, 9:16, 15s."}],
        "runtime_config": {"requireJobConfirmation": True},
    },
)
run = resp.json()["data"]["run"]

#Response (HTTP 202 Accepted on first submit, HTTP 200 OK when an idempotency key matches an existing run)

{
  "status": "success",
  "data": {
    "run": {
      "runId": "run_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "ownerWalletAddress": "0x…",
      "status": "queued",
      "schemaVersion": "…",
      "backbone": { "schemaVersion": "…", "modelKnowledgeVersion": "…", "routingPolicyVersion": "…" },
      "timestamps": { "createdAt": "…", "updatedAt": "…" },
      "scope": { "ownerWalletAddress": "0x…", "appSource": "sogni-api" },
      "request": { /* request snapshot */ },
      "messages": [],
      "toolCalls": [],
      "toolResults": [],
      "mediaContext": { "images": [], "videos": [], "audio": [], "uploadedImages": [], "uploadedVideos": [], "uploadedAudio": [] },
      "events": [{ "sequence": 0, "type": "run_created", "at": "…" }],
      "createTime": 1731950400000,
      "updateTime": 1731950400000
    },
    "idempotent": false
  }
}

Read the full run snapshot — current status, request, events, and (when paused) the waiting reason.

Read the persisted event log. Use ?after=<sequence> to fetch only events past a known sequence number.

#Query parameters

Server-Sent Events stream. Replays persisted events, then polls for new ones until the run reaches a terminal status (completed, failed, partial_failure, cancelled). Supports Last-Event-ID for resume and ?after=<sequence>.

#Event types

• Lifecycle — run_created, run_resumed, run_completed, run_partial_failure, run_failed, run_cancelled
• Rounds — llm_round_started, assistant_message_delta, assistant_message_completed
• Tool calls — tool_call_dispatched, tool_call_progress, tool_call_resolved
• Media + state — media_context_updated, media_turn_intent_classified, asset_manifest_updated
• Billing — llm_spend (authoritative per-round LLM token cost: costInToken, costInUSD, tokenType, modelName, token counts; dedupe on eventId), billing_preview_updated
• Pause + resume — run_waiting_for_user, run_awaiting_cost_confirmation (emits toolCallId + estimate), run_cost_confirmation_resolved
• Synthetic — run_status frames emitted by the stream on status transitions

id: 42
event: tool_call_dispatched
data: {"runId":"run_…","sequence":42,"type":"tool_call_dispatched","payload":{…}}

id: 43
event: run_awaiting_cost_confirmation
data: {"runId":"run_…","sequence":43,"type":"run_awaiting_cost_confirmation","payload":{"toolCallId":"call_…","estimatedCapacityUnits":120}}

Cooperative cancel. Flips the run to cancelled, halts any in-flight tool calls owned by the run, and appends a run_cancelled event so any SSE listeners see the transition.

#Body

#Response

{
  "status": "success",
  "data": { "run": { "runId": "run_…", "status": "cancelled" }, "aborted": true }
}

Resume a run that paused with waiting_for_user + cost_approval_required. Records the caller's decision, flips the run back to running, and dispatches the held tool calls.

#Body