Sign in

v1

latestOpenAPI 3.0.0Proprietary2026-08-062711471.0 MB
Agents

Run an agent (send a message)

Sends a message to an agent and returns its reply — the same way the in-app Overview/Playground tests an agent and its flow (runs over the OVERVIEW channel, against the active OR draft flow). Omit message on a new conversation to just open it and run the Start flow; pass conversation_id + message to continue. Requires a USER API key.

post/public/v1/agents/{agentId}/messages

Path parameters

agentIdstring required
Example:uuid-xxxx-xxxx

Request body

messagestring

The message to send. Omit on a NEW conversation to just open it and run the agent's Start flow (like the Overview/Playground). Required when continuing an existing conversation (conversation_id present).

conversation_idinteger

Continue an existing conversation. Omit to start a new one.

contact_idstring

Link the conversation to a People (contact) record.

initial_variablesobject

Variables to seed the conversation with when starting a new one (HMAC is computed server-side).

Example request

{
  "message": "Hi, I need help with my order",
  "conversation_id": 42,
  "contact_id": "example"
}

Response

The agent's reply messages and the conversation id

conversation_idnumber nullable

Example response

{
  "conversation_id": 42,
  "messages": [
    {
      "id": 1,
      "role": "ASSISTANT",
      "type": "MESSAGE",
      "text": "Hi! How can I help?",
      "created_at": "example"
    }
  ]
}