Getting started
Authenticate with a bearer token and call the Augeo AI Server public surface - agent chat, thread management, suggested prompts, and the MCP endpoint.
Getting started with the Augeo AI Server API
Augeo AI Server exposes an AI assistant over a small HTTP surface: a streaming chat endpoint, CRUD for conversation threads, a suggested-prompts endpoint, and a Model Context Protocol (MCP) endpoint for tool-calling clients. This guide walks through authentication and each endpoint. The machine-readable contract for everything described here is the OpenAPI reference.
Partners send flat engagement events through the Events API.
Authentication
Every endpoint requires a bearer token:
Authorization: Bearer <your-token>Tokens are issued as part of your Augeo integration onboarding (API keys or
OAuth 2.0 access tokens are both accepted on the same header). Requests without
a valid token receive 401 Unauthorized:
{
"error": "Unauthorized",
"message": "Authorization header with Bearer token is required"
}Rate limiting
Chat requests are rate limited per caller. Successful chat responses include
X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
When you exceed the chat limit you receive 429 Too Many Requests with a
Retry-After header (in seconds); back off and retry after that interval.
Chat with the agent
POST /api/agent/chat sends a conversation turn to the assistant and streams
the reply back as Server-Sent Events (SSE).
curl -N https://<api-host>/api/agent/chat \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"parts": [{ "type": "text", "text": "What can you help me with?" }]
}
],
"threadId": "<optional-thread-id>"
}'Request body:
| Field | Type | Required | Description |
|---|---|---|---|
messages | array | yes | Conversation messages. Each message has a role and a parts array; a user turn's part is { "type": "text", "text": "..." }. |
threadId | string | no | An existing thread id (see below). When provided, the server persists the turn to the thread and replays the thread's history to the model, so you only need to send the latest user message. |
model | object | no | Optional model override; omit it to use the server default. |
coldStartCompleted | boolean | no | When true, marks the post-personalization-quiz kickoff turn. The server injects a turn-scoped instruction not to congratulate quiz completion and enables framing enforcement so card turns keep a single framing beat in the render tool's intro. Omit or set false for ordinary turns (default). Not persisted with the thread or message. |
The response is an SSE stream of UI message chunks compatible with the
Vercel AI SDK UI message stream protocol (useChat /
readUIMessageStream consume it directly). Missing or non-array messages
returns 400; posting to a thread owned by another caller returns 403.
Manage conversation threads
Threads persist conversations server-side so a chat can resume across
sessions. All routes live under /api/threads.
List threads
curl "https://<api-host>/api/threads?page=1&pageSize=50" \
-H "Authorization: Bearer $TOKEN"Supports page (default 1), pageSize (default 50), and q (title search)
query parameters. Returns:
{
"chats": [
{ "id": "…", "title": "My thread", "timestamp": "2026-07-02T00:00:00.000Z" }
],
"total": 1,
"page": 1,
"totalPages": 1
}Create a thread
curl -X POST https://<api-host>/api/threads \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "My thread" }'Returns 201 with the created thread, including its id. Pass that id as
threadId on subsequent POST /api/agent/chat calls.
Fetch a thread
curl https://<api-host>/api/threads/<threadId> \
-H "Authorization: Bearer $TOKEN"Returns the thread with its full message history (each message carries id,
role, parts, and createdAt). Threads you do not own return 404.
Rename a thread
curl -X PUT https://<api-host>/api/threads/<threadId> \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "New name" }'Returns 204 on success, 404 when the thread is not yours.
Delete a thread
curl -X DELETE https://<api-host>/api/threads/<threadId> \
-H "Authorization: Bearer $TOKEN"Returns 204 on success, 404 when the thread is not yours.
Suggested prompts
GET /api/prompts/suggested returns starter prompts you can offer users
before their first message:
curl https://<api-host>/api/prompts/suggested \
-H "Authorization: Bearer $TOKEN"{ "prompts": ["…", "…"] }MCP endpoint
The server is also an MCP server over the
Streamable HTTP transport.
Claude Desktop, ChatGPT, and Grok connect by OAuth. Follow
Remote MCP connectors. Check the environment first
with MCP Connect. A caller that already holds a
bearer for this server can also call /mcp directly. That call supports three
operations:
-
POST /mcp— send a JSON-RPC message. The first request of a session must be an MCPinitializerequest (with no session header); the response carries anMcp-Session-Idheader identifying the new session. Every later request must include that header:Mcp-Session-Id: <session-id>Requests with an unknown session id return
404; a first request that is notinitializereturns400. -
GET /mcp— open the server-to-client SSE stream for an existing session. Requires theMcp-Session-Idheader. -
DELETE /mcp— terminate a session. Requires theMcp-Session-Idheader and returns204.
Sessions are scoped to the caller that created them (another caller's session
id returns 403) and expire after 30 minutes of inactivity — reinitialize if
you receive 404 for a previously valid session.
A caller that already holds a bearer points it at https://<api-host>/mcp.
Claude Desktop, ChatGPT, and Grok obtain their own bearer through the steps in
Remote MCP connectors.
OpenAPI reference
The generated specification of every path and method on this public surface is
published alongside this guide as
reference/openapi.json. It is produced directly
from the server's route definitions, so it always reflects the deployed
contract. Request and response schemas are not included yet; the examples in
this guide cover the payload shapes.