Augeo AI Docs
AI Server

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:

FieldTypeRequiredDescription
messagesarrayyesConversation messages. Each message has a role and a parts array; a user turn's part is { "type": "text", "text": "..." }.
threadIdstringnoAn 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.
modelobjectnoOptional model override; omit it to use the server default.
coldStartCompletedbooleannoWhen 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:

  1. POST /mcp — send a JSON-RPC message. The first request of a session must be an MCP initialize request (with no session header); the response carries an Mcp-Session-Id header 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 not initialize returns 400.

  2. GET /mcp — open the server-to-client SSE stream for an existing session. Requires the Mcp-Session-Id header.

  3. DELETE /mcp — terminate a session. Requires the Mcp-Session-Id header and returns 204.

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.