Durable Chat Runs

Returns 202 Accepted with the persisted run. Retrying with the same idempotency key returns that run instead of starting another: 200 OK with idempotent: true once it has left queued, or 202 with idempotent: false while it is still queued. Reconcile on data.run.runId. Fields may be sent in snake_case or camelCase; unknown fields return 400. Starting runs too quickly returns 429 with retryAfter (seconds) in the body.

#Headers

#Body

#Request

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 },
});

const api = 'https://api.sogni.ai/v1/chat/runs';
const headers = { Authorization: `Bearer ${process.env.SOGNI_API_KEY}`, 'Content-Type': 'application/json' };

for await (const event of sogni.chat.runs.streamEvents(run.runId)) {
  if (event.type !== 'run_waiting_for_user' || event.payload?.reason !== 'cost_approval_required') continue;
  const { toolCallId, costApprovalPreview } = event.payload.details;
  // Show costApprovalPreview to the user, then confirm or cancel.
  await fetch(`${api}/${run.runId}/confirm-cost`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ tool_call_id: toolCallId, decision: 'confirm', acceptedCostPreview: costApprovalPreview }),
  });
}

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

{
  "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
  }
}

Returns the full run snapshot: current status, request, and events. A paused run carries waiting: { reason, message, details }; chat runs pause for cost_approval_required or safety_review_required. Long conversations are trimmed from the oldest turns to fit the model's context window, without an error.

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

#Query parameters

Server-Sent Events stream. Replays persisted events, sends a run_status frame with the current status, then follows new events until the run reaches completed, failed, partial_failure, or cancelled. A waiting_for_user run keeps the stream open. Resume with Last-Event-ID (takes precedence) or ?after=<sequence>. Lines starting with : are heartbeats. Treat run_status frames as idempotent. The log keeps the newest 2,000 events.

#Event types

• Lifecycle: run_created, run_resumed, run_completed, run_partial_failure, run_failed, run_cancelled
• Rounds: llm_round_started, assistant_message_delta (each round's full text, not token deltas), assistant_message_completed
• Tool calls: tool_call_dispatched, tool_call_progress, tool_call_resolved
• Media and state: media_context_updated
• Billing: llm_spend carries the authoritative per-round LLM token cost (costInToken, costInUSD, tokenType, modelName, and token counts; dedupe on eventId), and billing_preview_updated
• Pause and resume: run_waiting_for_user, run_awaiting_cost_confirmation (emits toolCallId and an estimate), run_cost_confirmation_resolved
• Synthetic: run_status frames emitted by the stream on status transitions
• Ignore event types you don't recognize; new types may be added.

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

id: 43
event: run_awaiting_cost_confirmation
data: {"sequence":43,"type":"run_awaiting_cost_confirmation","at":"…","payload":{"toolCallId":"call_…","toolName":"generate_video","estimatedCost":120,"tokenType":"spark"}}

Cooperative cancel for a queued, running, or waiting_for_user run. Flips it to cancelled, signals active work, and appends run_cancelled. aborted reports whether active work was signalled directly. A run that is already finished returns 409.

#Body

#Response

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

Resolves a run paused with waiting_for_user and cost_approval_required. confirm returns the run to running and dispatches the held paid tool calls; cancel declines them and ends the run as completed with finalResponse.finishReason: "cancelled". One decision applies to every paid call held in the pause.

#Body