API Integration Guide

Integrate SimpliServe's AI agents directly into your own application, mobile app, or custom chat widget. The API is stateless on your end. We handle conversation memory and contextual routing automatically.

Base URL

All integration requests go to the SimpliServe Integrations API, under the /v1 prefix. This is a different host from the dashboard API.

Base URL

https://simpliserve-integration-production.up.railway.app/v1

Authentication

Every endpoint requires an API key, which you generate in the SimpliServe dashboard under your agent's Channels settings. Send it on every request:

Header

X-API-Key: your_generated_api_key_here

Keep your API keys secure.A key grants full access to your agent's chat API and consumes your credits, so treat it like a password. For server-side integrations, call SimpliServe from your backend and never ship the key to your frontend. The website widget is the exception, because it necessarily carries the key in the browser. Give it a key of its own, and rotate that key if you suspect it has been copied.

1. Retrieve agent information

GET /agent/name

Typically used to fetch the agent's name when initialising your chat UI.

Request

curl https://simpliserve-integration-production.up.railway.app/v1/agent/name \
  -H "X-API-Key: your_generated_api_key_here"

200 OK

{
  "name": "Customer Support Bot"
}

2. Standard chat (synchronous)

POST /chat

Send a message and wait for the complete response. Omit thread_id to start a new conversation. The response returns one, which you pass on subsequent requests to keep the conversation in context.

POST /v1/chat

curl -X POST https://simpliserve-integration-production.up.railway.app/v1/chat \
  -H "X-API-Key: your_generated_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, I need help with my account.",
    "thread_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

200 OK

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Account Assistance",
  "response": "Hello! I'd be happy to help you with your account. What specifically do you need assistance with?"
}

3. Streaming chat (Server-Sent Events)

POST /chat/stream

Stream the response token by token for a typing effect. Same request body as /chat. The stream terminates with a [DONE] signal.

On streaming requests the thread_id and title come back as response headers, not in the body: X-Thread-ID and X-Thread-Title.

text/event-stream

data: {"content": "You "}
data: {"content": "can "}
data: {"content": "reset "}
data: {"content": "your "}
data: {"content": "password..."}
data: [DONE]

4. Retrieve chat history

GET /chat/thread/{thread_id}

Fetch the full message history for a conversation thread.

200 OK

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "987fcdeb-51a2-43d7-9012-345678901234",
  "source": "api_key",
  "title": "Account Assistance",
  "created_at": "2026-10-27T10:00:00Z",
  "updated_at": "2026-10-27T10:05:00Z",
  "messages": [
    {
      "id": "msg-001",
      "role": "user",
      "content": "Hello, I need help with my account.",
      "created_at": "2026-10-27T10:00:00Z"
    },
    {
      "id": "msg-002",
      "role": "assistant",
      "content": "Hello! I'd be happy to help you with your account.",
      "created_at": "2026-10-27T10:00:05Z"
    }
  ]
}

Error handling

Status	Meaning
200 OK	The request was successful.
401 Unauthorized	The X-API-Key header is missing or incorrect.
404 Not Found	The provided thread_id or agent does not exist.
500 Internal Server Error	Something went wrong on SimpliServe's end.

Billing and exhaustion.If an agent runs out of allocated credits or is unpublished, the chat endpoints return a graceful “I am offline currently” string, either as a normal response or streamed, rather than a hard HTTP error. Your frontend keeps working.