curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.computer.stateset.app/api/v1/trigger/batch' \
--header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY" \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"agent_type": "general",
"effort": "low",
"instruction": "Open https://example.com and report the page title.",
"max_cost_usd": 0.1,
"model": "haiku",
"webhook_url": "https://hooks.example.com/cua"
}
]
}'
{
"accepted": 1,
"rejected": 1,
"results": [
{
"index": 1,
"job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "pending",
"error": "string"
}
]
}
Trigger Agent Batch
Submit up to 50 jobs in a single API call. Per-item validation: bad rows surface as individual errors in the response without blocking the rest…
POST
/
api
/
v1
/
trigger
/
batch
curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.computer.stateset.app/api/v1/trigger/batch' \
--header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY" \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"agent_type": "general",
"effort": "low",
"instruction": "Open https://example.com and report the page title.",
"max_cost_usd": 0.1,
"model": "haiku",
"webhook_url": "https://hooks.example.com/cua"
}
]
}'
{
"accepted": 1,
"rejected": 1,
"results": [
{
"index": 1,
"job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "pending",
"error": "string"
}
]
}
Confirm your deployment before running this request. This page describes an API contract;
a published reference does not establish hosted availability. Check the dated
host report and obtain your deployment URL and credentials.
Replace the example host if your provisioned service uses a different URL.
Idempotency-Key header to make a batch
replay-safe: a retried call returns the original batch’s job ids and
sets the Idempotency-Replayed: true header. Each item gets a
derived idempotency key of the form
v1.trigger.batch:<your-key>:<index>, so partial replays are
well-defined too.
Headers
string,null
Request body
BatchTriggerRequest
TriggerRequest[]
required
List of jobs to enqueue (1..50). Each item is validated independently — bad items are rejected per-row, valid items are still accepted and queued. Minimum items:
1. Maximum items: 50.Show TriggerRequest
Show TriggerRequest
string
Built-in template name (general, analytics_notebook, code_interpreter, jupyter_notebook, outbound_sequence, case_study, slide_deck) or the name of a tenant-owned Template row. Alphanumeric + dash/underscore, ≤128 chars. Default:
'general'.string
required
Natural-language task description shown to the agent. Whitespace-only is rejected with 422. Minimum length:
1. Maximum length: 50000.object
Free-form template parameters merged into the worker’s context. Reserved keys (model, effort_level, max_cost_usd, webhook_url) are populated from the typed fields below.
string,null
Optional one-shot webhook called when the job reaches a terminal state (succeeded / failed). Single best-effort POST, no retries. Provide
webhook_secret alongside to receive an HMAC-SHA256 signature. Tenants needing reliable delivery should register a tenant webhook via the dashboard instead.string,null
Optional shared secret for signing the ad-hoc webhook body. Adds
X-Webhook-Signature: t=<unix>,v1=<hex> to the delivery where v1 = HMAC-SHA256(secret, f’{t}.{body}’). Receivers verify by recomputing the HMAC with the same secret and rejecting deliveries with stale or mismatched signatures. Length 16..256. Minimum length: 16. Maximum length: 256.string,null
Pin a provider-compatible model. Claude aliases include haiku / sonnet / opus; agent_mode=‘openai’ accepts gpt-5.6-sol. Canonical IDs are accepted directly. Omit to use the selected provider’s default.
string,null
Provider reasoning-effort knob. Accepted values: low, medium, high, xhigh, max. Support depends on the selected model. Allowed values:
'low', 'medium', 'high', 'xhigh', 'max'.number,null
Hard per-job cost ceiling in USD. The worker monitors running cost each iteration; when the cap is crossed the job is cancelled with status=‘cancelled’ before the next API call. Range: (0, 1000]. Maximum:
1000.string,null
Execution backend. ‘agent’ (default; alias for ‘claude’) runs the Anthropic LLM sampling loop. ‘openai’ runs GPT-5.6 Sol with the Responses API GA computer tool. ‘nsr’ routes to the local neuro-symbolic engine — zero API tokens and deterministic. Allowed values:
'agent', 'claude', 'openai', 'nsr'.string[],null
Free-form labels stored alongside the job. Up to 20 entries, each ≤64 chars, alphanumeric + underscore + dash + colon. Filter on
GET /jobs?tag=<value> to retrieve a slice. Maximum items: 20.string,null
Strategy §4 SKU. Setting this turns the Job into a billable Outcome on success. Choices: resolved_contact (2),resolvedreturn(2), wismo_resolution (1.50),abandonedcartrecovery(3), qualified_lead (5),b2breorder(5), billing_dispute (5),upsell(20), pre_purchase_consultation (10),triage(0.50). Order Form may override per-SKU pricing. Allowed values:
'resolved_contact', 'resolved_return', 'wismo_resolution', 'abandoned_cart_recovery', 'qualified_lead', 'b2b_reorder', 'billing_dispute', 'upsell', 'pre_purchase_consultation', 'triage'.string,null
Stable Customer-side identifier for the conversation this Job is working — typically the upstream system’s id (Zendesk ticket, Gorgias conversation, Shopify order). Drives Multi-Touch Consolidation: follow-up Jobs with the same inquiry within the 72h Resolution Window roll up under one billable Outcome (Appendix A.1). Falls back to the Job’s UUID if omitted. Maximum length:
160.string,null
Upstream system-of-record event id proving the Outcome happened (Zendesk ticket id closed, NetSuite RMA id, etc). Required for SoR-bound SKUs (resolved_contact, resolved_return, b2b_reorder, billing_dispute) — Outcome is not minted without it. Maximum length:
256.boolean,null
Set true when the agent escalated to a human. The worker routes such Jobs to a TRIAGE Outcome at $0.50 regardless of the requested SKU (Strategy §4 margin protection).
boolean,null
Set true when the resolution involved an Appendix B.3 High-Value Action (refund > threshold, PII modification, subscription/payment-instrument change). Recorded on the Outcome row for audit; a future safety classifier will gate on this flag.
object,null
Per-SKU proof structure (Appendix A.2). Keys vary by SKU — resolved_contact accepts ticket_id, reopen_check; wismo_resolution accepts tracking_delivered, session_id, read_receipt; abandoned_cart_recovery accepts order_id, tracked_link, conversion_at; etc. Unrecognized keys are kept under
_unrecognized_keys rather than rejected.object,null
Free-form metadata attached to the Outcome row (extra_metadata column). Use for per-customer integration fields you want to surface in the Outcome Accounting Dashboard without polluting completion_criterion.
object,null
Optional JSON Schema constraining the agent’s final output. When set, the worker injects a system-prompt directive instructing the agent to emit a single JSON object matching this schema. Validation is currently caller-side — pull
summary and jsonschema.validate() against it; full agent-side enforcement is a roadmap item. Schemas larger than 8 KB serialised are rejected.Response
BatchTriggerResponse
integer
required
Count of successfully queued jobs.
integer
required
Count of rejected items.
BatchTriggerItemResult[]
required
Status codes
| Code | Meaning |
|---|---|
200 | Successful Response |
422 | Validation Error |
Using this contract
Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.computer.stateset.app/api/v1/trigger/batch' \
--header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY" \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"agent_type": "general",
"effort": "low",
"instruction": "Open https://example.com and report the page title.",
"max_cost_usd": 0.1,
"model": "haiku",
"webhook_url": "https://hooks.example.com/cua"
}
]
}'
{
"accepted": 1,
"rejected": 1,
"results": [
{
"index": 1,
"job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "pending",
"error": "string"
}
]
}
Last modified on September 21, 2026