Run an API
Start an agent job. Returns job_id for polling.
By default returns {job_id, status:"queued"} immediately and the caller
polls GET /jobs/{id} then GET /jobs/{id}/results.
Synchronous mode (?wait=true), opt-in: the request is held open while
the job is polled server-side (backoff), then:
• completed → {job_id, agent, status:"completed", row_count, returned, truncated, data} with up to API_WAIT_INLINE_ROW_CAP (100) rows inline.
If truncated, fetch the rest via GET /jobs/{id}/results (streamed) or
/jobs/{id}/download.
• failed / cancelled → {job_id, agent, status, error} inline.
• timeout (default 60s, hard-capped; override lower with wait_timeout) →
falls back to {job_id, status:"running", created_at}; poll as above.
MCP-sourced runs ignore wait (the MCP server self-polls).
A withdrawn id that still has live callers is rewritten to its replacement
BEFORE anything else, so validation, the wallet hold, the run row and the
invoice all name the surviving API (see agent_registry.DEPRECATED_ALIASES).
Bad params 422 before anything is booked. Which rule set decides is
PARAM_VALIDATION_MODE (api/core/config.py): legacy is the hand-rolled
gates alone, shadow (the default) runs them and logs what the shared
validator WOULD have done, enforce hands the decision to the shared
validator, the same mindcase_core.param_validation the MCP server and the
playground run, so a request this door accepts is one the data plane
accepts. A rejection carries per-field errors[] (api/core/errors.py), so
a UI can bind each one to the input that caused it. Every mode rejects
before create_job, before the wallet hold and before dispatch.
Authorizations
Headers
Optional, recommended. A unique string per run (e.g. a UUID). Retrying with the same key within 24h returns the original job instead of starting and charging a second one; the response carries X-Idempotent-Replay: true. The same key with a different agent or params returns 422 idempotency_key_reused.
8 - 255Query Parameters
Response
Successful Response