Agent Completions let your backend run the Sume Agent on an ad-hoc task. POST /v1/agent/completions runs the same runtime as the Agents chat: a full sandbox, tools, and media generation, with nobody watching. You send the task on every call; Sume saves nothing on your behalf.
Every detail below is from the Agent Completions docs.
Why is it asynchronous?
A real agent turn opens a sandbox, calls tools, and may generate media. That takes far longer than an HTTP request should stay open, so the create call returns 202 with an agent.run receipt, and you poll it or take a webhook. The request borrows OpenAI's messages[] shape so existing plumbing fits, but the response is a run receipt, not choices[].
What does a request look like?
Send exactly one of instruction (a plain string) or messages (system and user turns). generation_spend_cap_usd is required: an unattended agent with access to your wallet has no interactive spend-approval prompt, so the cap is the substitute. Set it to the most you will spend on one run, using the rates on API pricing.
curl -sS -X POST "https://api.sume.com/v1/agent/completions" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: promo-8823-v1" \
-d '{
"messages": [
{ "role": "user", "content": "Make a 9:16 product teaser for https://shop.example.com/p/8823" }
],
"generation_spend_cap_usd": 5,
"communication": { "webhook_url": "https://acme.example.com/hooks/sume" }
}'Which fields can I send?
| Field | Required | Notes |
|---|---|---|
instruction or messages | One of them | Never both. assistant turns are rejected; every completion runs in a fresh thread. |
generation_spend_cap_usd | Yes | No default. Omitting it is 400 invalid_request. |
input | No | Caller data written to a file in the sandbox. Treated as data, never as instructions. |
attachments | No | Up to 30 images the agent can see. |
output_schema | No | Bind the run's output to your own JSON Schema. |
communication.webhook_url | No | Public HTTPS URL notified once when the run completes or fails. |
How do I get the result?
Poll status_url from the receipt until next_action stops being poll_status, or pass communication.webhook_url and receive one signed POST carrying the same receipt (Run webhooks). Statuses are queued, processing, completed, failed, and canceled.
A completed run fills output with the agent's closing text and any generated media (output.images, output.videos, output.audio, output.files), plus artifacts and the spend recorded in usage. Media URLs are durable media.sume.com HTTPS URLs. POST /v1/agent-runs/{id}/cancel stops a run in flight.
Which API key do I need?
The key needs agent_completions:write to create and cancel, and agent_completions:read to read and list. Scopes are fixed when a key is minted, so keys created before Agent Completions shipped fail with 403 insufficient_scope; create a new key at API keys and rotate. Service-account keys cannot create Agent Completions.
When should I use a Format or a schedule instead?
All three surfaces run the same agent and return the same receipt shape. If the recipe is fixed and only the inputs change, save it as a Format and call POST /v1/formats/{handle}/{slug}/runs (see What is a Sume Format?). If the same saved task should run on a cadence, use Scheduled. Use Agent Completions when the task itself changes on every call.
What is not available yet?
The docs list these limits today:
- Streaming, and a synchronous OpenAI-compatible
choices[]response. - Continuing a prior thread, and
assistantturns inmessages[]. - Non-image attachments;
input_imageis the only attachment type. - Team-owned threads; completions are user-owned.