Preview Job V1
Dry-run a trigger payload without queueing. Resolves template defaults + per-job overrides into the final params dict, surfaces what model + agent_mode would…
POST
Dry-run a trigger payload without queueing.
Resolves template defaults + per-job overrides into the final
params dict, surfaces what model + agent_mode would actually be
used, and reports whether the request would currently pass quota.
Does NOT create a Job row, consume an idempotency key, or count
against quota — purely diagnostic.
Useful before sending a large batch: catch the misconfigured
agent_type, the wrong model alias, the missing template default,
without burning the budget.
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.
string
required
Natural-language task description shown to the agent. Whitespace-only is rejected with 422.
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.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.
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].
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.
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.string,null
Strategy §4 SKU. Setting this turns the Job into a billable Outcome on success. Choices: resolved_contact (2), wismo_resolution (3), qualified_lead (5), billing_dispute (20), pre_purchase_consultation (0.50). Order Form may override per-SKU pricing.
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.
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.
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
JobPreviewResponse
string
required
string
required
How the agent_type resolves:
builtin ships with the platform; tenant is owned by your org; unknown would be rejected by /trigger but is shown here so callers can confirm typos.string
required
The trimmed instruction that would land on the worker.
object
required
The full
params dict the worker would see, with template defaults merged underneath your per-job overrides.string,null
required
Canonical model id after alias resolution. None = deployment default.
string
required
claude (default), openai (GPT-5.6 Sol), or nsr (local engine).boolean
required
True iff sending this job right now would clear the tenant’s quota check.
integer
required
integer
required