API & webhooks

API keys

Create one from the swarm's Deploy dialog. Keys look like sk_swarm_… and the secret is shown once — it is stored hashed and cannot be recovered, only rotated.

Which version your key runs

The canvas edits a draft. API keys and schedules run the published snapshot, so saving a half-finished edit cannot change what your integration receives. Creating a swarm's first key or schedule publishes the current graph automatically — a new deployment is never pointed at nothing.

After that, rolling out a change is deliberate: edit and save on the canvas, then press Publish in the Deploy dialog. Until you do, the dialog shows Draft ahead and deployed callers keep getting the previous version. Publishing pins whatever is saved, so save before you publish — the dialog says so if the canvas has unsaved edits.

Unpin is available if you want the old behaviour, where saves reach production immediately. Sub-swarms follow the same rule: an Execute Swarm node inside a headless run executes the child's published graph, not its draft.

POST /api/swarm/run

Headers

Request body

Synchronous run

curl -X POST https://your-instance.example.com/api/swarm/run \
  -H "Authorization: Bearer $AGENTSWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-48213-summary" \
  -d '{
        "input": "Summarise ticket 48213 and suggest a reply",
        "inputs": { "priority": "high" }
      }'

{
  "output": "The customer reports a faulty hinge …",
  "runId": "5f1c0f0e-…"
}

Asynchronous run

curl -X POST https://your-instance.example.com/api/swarm/run \
  -H "Authorization: Bearer $AGENTSWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "input": "Produce the weekly summary",
        "async": true,
        "callback_url": "https://api.example.com/hooks/agentswarms"
      }'

{
  "accepted": true,
  "callback_url": "https://api.example.com/hooks/agentswarms"
}

Use async for anything that takes longer than a request should — a long graph, an approval gate, a large document.

Status codes

Idempotency

Send an Idempotency-Key and a retry with the same key returns the original result instead of running the swarm again.

Idempotency records are kept for a bounded window and then purged.

Limits

Webhook callbacks

Each delivery carries these headers:

Delivery is retried up to 3 times, with a 15-second timeout per attempt.

Verifying the signature

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, headers, secret) {
  const ts  = headers["x-agentswarms-timestamp"];
  const sig = headers["x-agentswarms-signature"]; // "sha256=<hex>"

  // Reject old timestamps FIRST — this is what stops a captured
  // delivery being replayed at you weeks later.
  const age = Math.abs(Date.now() / 1000 - Number(ts));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected =
    "sha256=" + createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(sig ?? "");
  // Constant-time: a plain === leaks the answer through timing.
  return a.length === b.length && timingSafeEqual(a, b);
}

• Sign over the raw body, before any JSON parsing — re-serialising changes the bytes and the signature will not match.
• Respond 2xx quickly and do the work asynchronously; slow endpoints get retried.
• Make your handler idempotent — a retry may deliver the same result twice.

Outbound safety

Callback URLs are checked before delivery: private, loopback and link-local addresses — including cloud metadata endpoints — are refused. The same guard covers every outbound request the platform makes on your behalf, including web_browse, swarm HTTP nodes and MCP endpoints, so a URL chosen by a model cannot be used to reach inside your network.

Runs that hit an approval node

A swarm with an approval node will wait for a human. For an unattended integration that is a hang, so set reject_approvals on the key and such runs fail fast instead. Approvals fail closed either way — a run never proceeds past a gate on a timeout.

Seeing what happened

Every API-triggered run produces a full trace attributed to the key that started it, visible in Traces, with cost attributed in Analytics. When an integration misbehaves, start there rather than in your own logs — the trace shows the resolved prompt and every tool call.

Calling a notebook instead of a swarm

Notebooks in the Developer workspace can be published the same way: click Publish on a notebook to mint an nbk_… key, then POST /api/notebook/run with {"inputs": {…}}. The request body reaches the notebook's entrypoint function and its return value comes back as the response; long runs hand back a runId to poll at /api/notebook/run/status. Use it when the logic is Python that already works in a notebook and does not need to become a swarm first.