Public API

A small, read-only HTTP API for backends and warehouses. Authenticate with a workspace API key — not a browser session.

Get started

Create a key

Settings → Install → API keys. Copy the sk_live_… secret once — it is only shown at creation.

Send Bearer auth

Authorization: Bearer sk_live_…. The workspace is implied by the key.

Call an endpoint

Start with GET /conversations. Lists support limit and offset.

⚠

Never ship API keys in frontend code or commit them to a public repo. Revoke a key from Settings if it leaks.

Authentication

Every request needs a header. There is no workspaceId query param — the key is already bound to one workspace.

bash

curl https://sellio.chat/api/public/v1/conversations \
  -H "Authorization: Bearer sk_live_your_key_here"

Keys and scopes

Keys are created in Settings, then Install, under API keys, by a workspace owner or admin. Each key is bound to one workspace and carries the scopes you tick when you create it; a call to an endpoint outside the key’s scopes returns 403 with the scope it lacks. The secret is shown once, at creation; the page keeps the name, the scopes, the date it was last used and a Revoke button. Keys minted before scopes existed have full read access.

conversations:read

scope

List conversations and read their messages.

contacts:read

scope

List CRM contacts.

tickets:read

scope

List tickets.

analytics:read

scope

Read the performance summary.

Two endpoints need no scope: GET / describes the API and its version, and GET /status reports whether the service and its database are up, for monitors.

Base URL

bash

https://sellio.chat/api/public/v1

Paths below are relative to this base (for example /conversations).

Rate limits

120 requests per minute per API key (not per IP). Over limit returns 429 with Retry-After.

You do not have to hit the limit to find it. Every response carries your budget, in both the widely-deployed triplet and the current IETF structured fields:

http

RateLimit-Limit: 120
RateLimit-Remaining: 99
RateLimit-Reset: 42
RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=99;t=42

RateLimit-Reset (and t) is the number of seconds until your next request slot returns. Pace from it rather than retrying into a wall.

Errors

Every error is JSON with the same three fields. Branch on code, never on error: the message is free to improve, the code is the contract.

json

{
  "error": "This API key lacks the contacts:read scope",
  "code": "forbidden",
  "documentation": "https://sellio.chat/docs/api#authentication"
}

Codes: bad_request, unauthorized, forbidden, not_found, rate_limited, internal_error, service_unavailable, and plan_upgrade_required when the workspace's plan does not include the data (analytics start on Essentials).

OpenAPI and discovery

The Sellio public API is described by an OpenAPI 3.1 document. Every operation carries a unique operationId, typed parameters and a response schema, so it converts straight into tool definitions for an agent or a generated client.

/openapi.json the specification. Also served at /api/openapi.json.
GET https://sellio.chat/api/public/v1 an unauthenticated discovery document listing every endpoint and the scope it needs.
GET https://sellio.chat/api/public/v1/status an unauthenticated liveness check.
/llms.txt the whole site described for LLMs. Every page here also answers to Accept: text/markdown.

bash

curl https://sellio.chat/api/public/v1 | jq .endpoints
curl https://sellio.chat/openapi.json -o sellio-openapi.json

MCP server

The same reads are exposed as Model Context Protocol tools, so Claude, ChatGPT and other agents can call Sellio natively instead of you writing an integration. Transport is Streamable HTTP: POST JSON-RPC 2.0 messages to the endpoint. The server is stateless and issues no session id.

Endpoint: https://sellio.chat/mcp
Description: /mcp.json
Tools: list_conversations, get_conversation_messages, list_contacts, list_tickets, get_support_performance, get_api_status. All read-only.
Auth: the same Authorization: Bearer sk_live_… header. initialize, tools/list and get_api_status work without a key.

bash

curl https://sellio.chat/mcp   -H "Content-Type: application/json"   -H "Accept: application/json, text/event-stream"   -H "Authorization: Bearer sk_live_…"   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Versioning and deprecation

The version is in the path: /api/public/v1. Every response also carries an API-Version header.

Additive changes ship without a version bump. New endpoints, new optional parameters and new response fields can appear at any time. Ignore fields you do not recognise.
Breaking changes get a new version path. The old version keeps working for at least twelve months from the day the new one is announced.
Deprecation is announced in headers, not a blog post. A deprecated endpoint answers with Deprecation (RFC 9745) carrying the announcement date, Sunset (RFC 8594) carrying the date it stops working, and a Link header with rel="deprecation" pointing at the migration notes.
Nothing is deprecated today. No endpoint currently sends either header.

The machine-readable copy of this policy is the x-deprecation-policy object in /openapi.json.

GET/conversations

List conversations for the workspace, newest lastMessageAt first.

Parameters

statusoptional

Filter by conversation status.

"open" | "closed" | "resolved" | "pending"

limitoptional

Page size (1–100). Default 50.

number

offsetoptional

Rows to skip. Default 0.

number

JavaScript

index.ts

const res = await fetch("https://sellio.chat/api/public/v1/conversations?status=open&limit=20", {
  headers: { Authorization: "Bearer sk_live_…" },
});
const { conversations } = await res.json();

cURL

bash

curl "https://sellio.chat/api/public/v1/conversations?status=open&limit=20" \
  -H "Authorization: Bearer sk_live_…"

Response

json

{
  "conversations": [
    {
      "id": "conv_…",
      "subject": "Billing question",
      "status": "open",
      "priority": "normal",
      "visitorName": "Ada Lovelace",
      "visitorNameUnverified": false,
      "visitorEmail": "ada@example.com",
      "messageCount": 4,
      "lastMessageAt": "2026-08-20T01:00:00.000Z",
      "createdAt": "2026-08-19T22:00:00.000Z"
    }
  ]
}

Response fields

conversations[].id

string

Conversation id.

conversations[].status

string

open | closed | resolved | pending.

conversations[].visitorName

string | null

Visitor display name when known.

conversations[].visitorNameUnverified

boolean

True when identity verification is on and the visitor typed the name or sent it without a valid signature. Always false with verification off.

conversations[].lastMessageAt

string | null

ISO timestamp of the latest message.

Errors

401

Missing or invalid Authorization Bearer API key.

429

Rate limited (120 requests per minute per key).

GET/conversations/:id/messages

Return up to 200 non-deleted messages for a conversation, oldest first. IDs from other workspaces 404.

Parameters

idrequired

Conversation id (path).

string

JavaScript

index.ts

const res = await fetch("https://sellio.chat/api/public/v1/conversations/conv_…/messages", {
  headers: { Authorization: "Bearer sk_live_…" },
});
const { messages } = await res.json();

cURL

bash

curl "https://sellio.chat/api/public/v1/conversations/conv_…/messages" \
  -H "Authorization: Bearer sk_live_…"

Response

json

{
  "messages": [
    {
      "id": "msg_…",
      "senderType": "visitor",
      "content": "Hi — I need help with billing.",
      "createdAt": "2026-08-19T22:01:00.000Z"
    }
  ]
}

Response fields

messages[].senderType

string

Who sent the message (visitor, agent, system, …).

messages[].content

string

Message body text.

Errors

401

Missing or invalid Authorization Bearer API key.

429

Rate limited (120 requests per minute per key).

404

Conversation not found in this workspace.

GET/contacts

List contacts, newest createdAt first.

Parameters

limitoptional

Page size (1–100). Default 50.

number

offsetoptional

Rows to skip. Default 0.

number

JavaScript

index.ts

const res = await fetch("https://sellio.chat/api/public/v1/contacts?limit=50", {
  headers: { Authorization: "Bearer sk_live_…" },
});
const { contacts } = await res.json();

cURL

bash

curl "https://sellio.chat/api/public/v1/contacts?limit=50" \
  -H "Authorization: Bearer sk_live_…"

Response

json

{
  "contacts": [
    {
      "id": "ct_…",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "phone": null,
      "tags": ["vip"],
      "createdAt": "2026-08-10T12:00:00.000Z"
    }
  ]
}

Errors

401

Missing or invalid Authorization Bearer API key.

429

Rate limited (120 requests per minute per key).

GET/tickets

List tickets, newest createdAt first.

Parameters

limitoptional

Page size (1–100). Default 50.

number

offsetoptional

Rows to skip. Default 0.

number

JavaScript

index.ts

const res = await fetch("https://sellio.chat/api/public/v1/tickets?limit=50", {
  headers: { Authorization: "Bearer sk_live_…" },
});
const { tickets } = await res.json();

cURL

bash

curl "https://sellio.chat/api/public/v1/tickets?limit=50" \
  -H "Authorization: Bearer sk_live_…"

Response

json

{
  "tickets": [
    {
      "id": "tkt_…",
      "number": 42,
      "subject": "Refund request",
      "status": "open",
      "priority": "high",
      "conversationId": "conv_…",
      "createdAt": "2026-08-18T09:00:00.000Z"
    }
  ]
}

Errors

401

Missing or invalid Authorization Bearer API key.

429

Rate limited (120 requests per minute per key).

GET/analytics/performance

Headline performance totals for a date range, plus the previous period of equal length. Same summary the dashboard and emailed reports use.

Parameters

fromoptional

Range start. Default: 7 days before to.

string (ISO date)

tooptional

Range end. Default: now. Max span 366 days.

string (ISO date)

JavaScript

index.ts

const res = await fetch("https://sellio.chat/api/public/v1/analytics/performance?from=2026-08-01&to=2026-08-20", {
  headers: { Authorization: "Bearer sk_live_…" },
});
const data = await res.json();

cURL

bash

curl "https://sellio.chat/api/public/v1/analytics/performance?from=2026-08-01&to=2026-08-20" \
  -H "Authorization: Bearer sk_live_…"

Response

json

{
  "period": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-08-20T00:00:00.000Z"
  },
  "totals": {
    "volume": 120,
    "involved": 80,
    "aiResolved": 40,
    "automationRate": 0.33,
    "involvementRate": 0.67,
    "resolutionRate": 0.5,
    "cxScore": 0.9,
    "rated": 20,
    "positive": 18
  },
  "previous": { "…": "same shape" }
}

Response fields

totals.volume

number

Conversations in the period.

totals.automationRate

number | null

AI-resolved / volume (null if denominator is 0).

totals.cxScore

number | null

Positive ratings / rated.

previous

object

Same metrics for the prior window of equal length.

Errors

401

Missing or invalid Authorization Bearer API key.

429

Rate limited (120 requests per minute per key).

400

Invalid from/to, or range longer than 366 days.

Create keys in the product: Settings → Install → API
Widget for the browser: Widget JavaScript API

Updated 14 September 2026. Something wrong or missing? Tell us.

PreviousMicrosoft Teams

Public API

Get started

Authentication

Keys and scopes

Base URL

Rate limits

Errors

OpenAPI and discovery

MCP server

Versioning and deprecation

Related