Skip to main content
POST
/
agents
/
{agent_id}
/
invoke
Invoke agent
curl --request POST \
  --url https://api.trymaitai.ai/api/v1/agents/{agent_id}/invoke \
  --header 'Content-Type: application/json' \
  --header 'X-Maitai-Api-Key: <api-key>' \
  --data '
{
  "message": "I need help setting up my account",
  "release": "production"
}
'
{
  "data": {
    "id": "chatcmpl-abc123",
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": "Sure — let's start with your business details."
        }
      }
    ]
  }
}

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