Invoke agent
Agents
Invoke agent
Run an agent and wait for its final response. Targets the draft by default; pass `version` (e.g. "1.2.0") or `release` (e.g. "production") to pin. Body: `{message}` or `{messages: [...]}`, plus optional `session_id`, `max_iterations`, and `secrets` ({NAME: value} for actions that declare `{{secrets.NAME}}` placeholders). Set `wait=false` to enqueue asynchronously and poll with the task endpoint instead.
POST
Invoke agent
Authorizations
Your Maitai API key from the Portal.
Path Parameters
Body
application/json
Shorthand for a single user message.
OpenAI-style message list (overrides message).
Pin a published version, e.g. '1.2.0'.
Pin a named release, e.g. 'production'.
Continue an existing agent session.
Structured output for the agent's final response. OpenAI-style: {"type": "json_object"} or {"type": "json_schema", "json_schema": {"name": ..., "schema": {...}}}. Omit for freeform text (default).
false = enqueue and return task ids immediately.
{NAME: value} map for actions that declare {{secrets.NAME}} placeholders in auth/headers. Ephemeral — never persisted.
Response
200 - application/json
Invoke agent.