POST /v1/chat

• X-Api-KeyYour platform key. See Authentication.
• X-Agent-IdUUID of the agent to invoke.
• Content-TypeAlways application/json.

• message (required)The user's message. Appended to the conversation history and sent to the LLM along with the agent's system prompt.
• conversation_id (optional)Pass an existing id to continue a thread. Omit it and a new conversation is created automatically.

{
  "conversation_id": "conv-uuid-...",
  "message": {
    "id": "msg-uuid-...",
    "conversation_id": "conv-uuid-...",
    "role": "assistant",
    "content": "Order ORD-1234 is shipped via FedEx (FX-998877)...",
    "token_count": 156,
    "created_at": "2026-03-28T14:30:00Z"
  },
  "tool_calls": [
    {
      "name": "get_order",
      "input": { "order_id": "ORD-1234" },
      "output": "{\"status\":\"shipped\",\"carrier\":\"FedEx\"}"
    }
  ]
}

• conversation_idPersistent thread id. Store and pass back to keep history.
• message.idUnique id of the saved assistant message.
• message.roleAlways "assistant" for replies.
• message.contentThe reply text. Format depends on the agent's configured output type.
• message.token_countTotal tokens across every LLM call in the request (incl. tool rounds).
• tool_callsPresent only when MCP tools ran. Each entry has name, input, output.

1. 1

   Authenticate

   X-Api-Key resolves to your account; rate limits and plan checks fire.
2. 2

   Load the agent

   X-Agent-Id selects the agent config — system prompt, model, provider key, parameters.
3. 3

   Resolve conversation

   If you passed conversation_id, history is loaded. Otherwise a new conversation is created.
4. 4

   Persist your message

   The new user message is saved to the conversation history before any LLM work starts.
5. 5

   Call the LLM

   System prompt + all prior messages + new message are sent to the provider.
6. 6

   Run MCP tools if requested

   If the model asks for a tool, the platform runs it and feeds the result back (up to 8 rounds by default — configurable per agent).
7. 7

   Save and return

   Final reply is saved and returned with the optional tool_calls array.

The first request returns a conversation_id. Pass it back on every subsequent request and the agent sees the full prior thread — same model context window as a single long conversation.

# 1) Start a thread
curl -X POST https://api.sentientone.ai/v1/chat \
  -H "X-Api-Key: sk-so-..." -H "X-Agent-Id: ..." \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hi, my order ORD-1234 hasn't arrived." }'
# → { "conversation_id": "conv-abc123", ... }

# 2) Continue it
curl -X POST https://api.sentientone.ai/v1/chat \
  -H "X-Api-Key: sk-so-..." -H "X-Agent-Id: ..." \
  -H "Content-Type: application/json" \
  -d '{ "conversation_id": "conv-abc123", "message": "What carrier is it on?" }'