Supovia API reference

Read several organization resources in one request

Executes a bounded batch of collection reads and returns an object keyed by each operation's alias. Only explicitly allow-listed, organization-scoped collections can be queried.

List conversations

Lists the conversations of your organization, newest first when sorted by lastEditTime. Requires the conversations:read scope.

Get a conversation

Returns a single conversation by id. Conversations belonging to another organization respond 404. Requires the conversations:read scope.

List customers

Requires the customers:read scope.

Create a customer

Creates a customer on a website. Emits the customer.created webhook event. Requires the customers:write scope.

Get a customer

Returns a single customer by id. Customers belonging to another organization respond 404. Requires the customers:read scope.

Update a customer

Requires the customers:write scope.

Search documents

Semantic (vector) search over your published help documents. Requires the documents:read scope.

List documents

Requires the documents:read scope. For stable traversal, set pagination=cursor; the response becomes {items, nextCursor} and is ordered by ascending _id. Pass nextCursor back as cursor until it is null. Existing array responses and offset pagination remain available when cursor pagination is not requested.

List messages

Lists messages, usually filtered by conversationId. Requires the messages:read scope.

Create a message

Appends a message to a conversation. from is operator for replies sent on behalf of your team and customer for messages on behalf of the visitor. Emits the message.created webhook event. Requires the messages:write scope.

Get a message by id

Returns one message to an authenticated operator or API key. A key requires the messages:read scope. Anonymous chat sessions cannot use this route. Messages belonging to another organization, or to a different Website than a Website-pinned key, respond 404.

Mark a protected customer reply as read

Rate an agent or operator reply

Records how the visitor rated one reply, as rating and ratingTime on that message. Called by the embedded chat surfaces with the visitor's chat-session credentials; there is no API-key or operator-token path, because the rating is the customer's own answer and nobody else may author it. Re-rating the same message overwrites the previous value. Emits MESSAGE_UPDATED_EVENT to the dashboard.

Read sandbox help-center documents without authentication

Returns a fixed set of demonstration help-center documents in the same {title, locale} shape as authenticated document reads. No account, credential, or key is required, so agents can evaluate the API before onboarding. Responses carry the standard RateLimit response headers and the anonymous pacing limit applies.

Start a demonstration asynchronous document-summary job

Demonstrates the API's asynchronous-job pattern without authentication. The response is 202 Accepted with a Location header pointing at the job resource and a body carrying the job _id and status. Poll the Location URL until the status is succeeded, then read the summary from the job body. The job is deterministic fixture work that completes about two seconds after creation.

Poll a demonstration document-summary job

Reads the status of a demonstration job started at POST /api/sandbox/documentsummaryjobs. While the job runs the status is running; afterwards it is succeeded and the body carries the document summary. No authentication is required.

List webhook subscriptions

Webhook subscriptions deliver message.created, conversation.created and customer.created events to your server as signed POST requests (X-Supovia-Signature: t=<timestamp>,v1=<hex HMAC-SHA256 of "timestamp.body">). An endpoint failing 20 times in a row is disabled automatically. Subscriptions are managed with an operator access token; the secret is only returned once, on create.

Create a webhook subscription

The response includes the signing secret exactly once — store it; it cannot be retrieved again.

Update a webhook subscription

url, events and active are editable; the secret and website are immutable. Re-enabling an auto-disabled endpoint is done by setting active back to true.

Delete a webhook subscription

List websites

Lists the websites (projects) of your organization. Requires the websites:read scope.

Get a website by name

Requires the websites:read scope.