Skip to main content
POST
Invoke agent

Authorizations

X-Maitai-Api-Key
string
header
required

Your Maitai API key from the Portal.

Path Parameters

agent_id
integer
required

Body

application/json
message
string

Shorthand for a single user message.

messages
object[]

OpenAI-style message list (overrides message).

version
string

Pin a published version, e.g. '1.2.0'.

release
string

Pin a named release, e.g. 'production'.

session_id
string

Continue an existing agent session.

max_iterations
integer
response_format
object

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

wait
boolean

false = enqueue and return task ids immediately.

secrets
object

{NAME: value} map for actions that declare {{secrets.NAME}} placeholders in auth/headers. Ephemeral — never persisted.

Response

200 - application/json

Invoke agent.

data
any