Trigger Agent

Trigger an agent run via the external API.

POST /api/v1/trigger

cURL

curl --request POST \
  --url 'https://api.computer.stateset.app/api/v1/trigger' \
  --header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
}'

200

{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending"
}

Trigger an agent run via the external API.

Request body

TriggerRequest

agent_type · 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.

instruction · string · required

Natural-language task description shown to the agent. Whitespace-only is rejected with 422.

params · 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.

webhook_url · 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.

webhook_secret · 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.

model · 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.

effort · string,null

Provider reasoning-effort knob. Accepted values: low, medium, high, xhigh, max. Support depends on the selected model.

max_cost_usd · 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].

agent_mode · 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.

tags · 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.

outcome_type · string,null

Strategy §4 SKU. Setting this turns the Job into a billable Outcome on success. Choices: resolved_contact ($2), resolved_return ($2), wismo_resolution ($1.50), abandoned_cart_recovery ($3), qualified_lead ($5), b2b_reorder ($5), billing_dispute ($5), upsell ($20), pre_purchase_consultation ($10), triage ($0.50). Order Form may override per-SKU pricing.

inquiry_id · 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.

system_of_record_event_id · 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.

triggered_human_handoff · 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).

high_value_action · 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.

completion_criterion · 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.

outcome_metadata · 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.

output_schema · 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

TriggerResponse

job_id · string · required

UUID of the queued job. Use it for subsequent /jobs/:id calls.

status · string · required

Initial job status — usually ‘queued’. Replays of an idempotent request return the existing job’s current status.

Status codes

Code	Meaning
200	Successful Response
422	Validation Error

cURL

curl --request POST \
  --url 'https://api.computer.stateset.app/api/v1/trigger' \
  --header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
}'

200

{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending"
}