Skip to main content
POST
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.
Trigger an agent run via the external API.

​
Headers

​
string,null

​
Request body

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), resolved_return (2), wismo_resolution (1.50),abandonedcartrecovery(1.50), abandoned_cart_recovery (3), qualified_lead (5),b2breorder(5), b2b_reorder (5), billing_dispute (5),upsell(5), upsell (20), pre_purchase_consultation (10),triage(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

TriggerResponse
​
string
required
UUID of the queued job. Use it for subsequent /jobs/:id calls.
​
string
required
Initial job status — usually ‘queued’. Replays of an idempotent request return the existing job’s current status.

​
Status codes

​
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.
Last modified on September 21, 2026