{ "openapi": "3.0.0", "info": { "title": "Supovia API", "version": "1.0.0", "description": "Public REST API for Supovia. Authenticate with an API key created in the Supovia dashboard: send the base64-encoded key secret with HTTP Basic auth. Each key carries per-resource scopes like `conversations:read` or `messages:write`.", "x-api-versioning": { "currentVersion": "1", "requestHeader": "API-Version", "responseHeader": "API-Version", "compatibilityPolicy": "Omitting API-Version selects version 1. Unsupported versions return HTTP 400.", "deprecationPolicy": "Supovia announces incompatible versions at least 180 days before removal.", "deprecationHeaders": [ "Deprecation", "Sunset", "Link" ], "policyUrl": "https://www.supovia.com/api.md#compatibility-version" } }, "servers": [ { "url": "https://api.supovia.com" } ], "components": { "headers": { "Deprecation": { "description": "RFC 9745 deprecation date when an operation is deprecated.", "schema": { "type": "string", "example": "@1893456000" } }, "Sunset": { "description": "HTTP-date when a deprecated operation will be retired.", "schema": { "type": "string", "example": "Tue, 01 Jan 2030 00:00:00 GMT" } }, "DeprecationLink": { "description": "Migration policy link with rel=\"deprecation\".", "schema": { "type": "string" } } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "basic", "description": "HTTP Basic auth carrying only the API key secret: Authorization: Basic base64()." }, "accessToken": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Operator session token issued by the Supovia dashboard: Authorization: Token ." } }, "schemas": { "Entity": { "type": "object", "description": "A Supovia resource. Fields vary by endpoint and requested projection.", "properties": { "_id": { "type": "string", "description": "Stable resource identifier." }, "organizationId": { "type": "string", "description": "Owning organization identifier when applicable." }, "websiteId": { "type": "string", "description": "Owning website identifier when applicable." } }, "additionalProperties": true }, "Error": { "type": "object", "required": [ "name", "message", "status" ], "properties": { "name": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } }, "DocumentPage": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "description": "One page of documents in ascending `_id` order", "items": { "type": "object", "additionalProperties": true } }, "nextCursor": { "nullable": true, "type": "string", "description": "Opaque cursor for the next page, or null after the final page" } } } } }, "paths": { "/api/batch": { "post": { "tags": [ "Batch" ], "summary": "Read several organization resources in one request", "description": "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.\n", "security": [ { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "alias", "url" ], "properties": { "alias": { "type": "string" }, "url": { "type": "string", "example": "websites?limit=10" } } } } } } }, "responses": { "200": { "description": "Results keyed by operation alias", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "postBatch", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ] } }, "/api/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations", "description": "Lists the conversations of your organization, newest first when sorted by `lastEditTime`. Requires the `conversations:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "websiteId", "schema": { "type": "string" } }, { "in": "query", "name": "customerId", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "sortField", "schema": { "type": "string", "example": "lastEditTime" } }, { "in": "query", "name": "sortDirection", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "resolved", "schema": { "type": "boolean" } }, { "in": "query", "name": "fields", "description": "Comma-separated projection of fields to return", "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "Array of conversations", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `conversations:read` scope", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getConversations" } }, "/api/conversations/{conversationId}": { "get": { "tags": [ "Conversations" ], "summary": "Get a conversation", "description": "Returns a single conversation by id. Conversations belonging to another organization respond 404. Requires the `conversations:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "The conversation", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "404": { "description": "Not found (or owned by another organization)", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getConversationsByConversationId" } }, "/api/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Requires the `customers:read` scope.", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "websiteId", "schema": { "type": "string" } }, { "in": "query", "name": "email", "schema": { "type": "string" } }, { "in": "query", "name": "userId", "description": "Your own user id set via the widget `setUserId`", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated projection of fields to return", "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "Array of customers", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } } }, "operationId": "getCustomers" }, "post": { "tags": [ "Customers" ], "summary": "Create a customer", "description": "Creates a customer on a website. Emits the `customer.created` webhook event. Requires the `customers:write` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "nickname": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } } } } } }, "responses": { "200": { "description": "The created customer", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "403": { "description": "API key is missing the `customers:write` scope", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postCustomers", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ] } }, "/api/customers/{customerId}": { "get": { "tags": [ "Customers" ], "summary": "Get a customer", "description": "Returns a single customer by id. Customers belonging to another organization respond 404. Requires the `customers:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "customerId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "The customer", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "404": { "description": "Not found (or owned by another organization)", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getCustomersByCustomerId" }, "put": { "tags": [ "Customers" ], "summary": "Update a customer", "description": "Requires the `customers:write` scope.", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "customerId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The updated customer", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "putCustomersByCustomerId" } }, "/api/documents/search": { "get": { "tags": [ "Documents" ], "summary": "Search documents", "description": "Semantic (vector) search over your published help documents. Requires the `documents:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "query", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "websiteId", "schema": { "type": "string" } }, { "in": "query", "name": "locale", "schema": { "type": "string", "default": "en" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "Array of matching documents, best match first", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } } }, "operationId": "getDocumentsSearch" } }, "/api/documents": { "get": { "tags": [ "Documents" ], "summary": "List documents", "description": "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.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "websiteId", "schema": { "type": "string" } }, { "in": "query", "name": "locale", "schema": { "type": "string" } }, { "in": "query", "name": "documentId", "description": "Exact document id", "schema": { "type": "string" } }, { "in": "query", "name": "category", "schema": { "type": "string" } }, { "in": "query", "name": "published", "schema": { "type": "boolean" } }, { "in": "query", "name": "search", "description": "Plain-text title search", "schema": { "type": "string" } }, { "in": "query", "name": "pagination", "description": "Set to `cursor` for a stable page envelope", "schema": { "type": "string", "enum": [ "cursor" ] } }, { "in": "query", "name": "cursor", "description": "Opaque `nextCursor` from the preceding cursor page", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "description": "Optional bounded page size (maximum 500 and default 100 in cursor mode; 0 returns everything otherwise)", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "fields", "description": "Comma-separated projection of fields to return", "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "Array of documents, or `{items, nextCursor}` in cursor mode", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } }, { "$ref": "#/components/schemas/DocumentPage" } ] } } } } }, "operationId": "getDocuments" } }, "/api/messages": { "get": { "tags": [ "Messages" ], "summary": "List messages", "description": "Lists messages, usually filtered by `conversationId`. Requires the `messages:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "conversationId", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "sortField", "schema": { "type": "string", "example": "creationTime" } }, { "in": "query", "name": "sortDirection", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "fields", "description": "Comma-separated projection of fields to return", "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "Array of messages", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } } }, "operationId": "getMessages" }, "post": { "tags": [ "Messages" ], "summary": "Create a message", "description": "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.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "conversationId", "content", "from" ], "properties": { "conversationId": { "type": "string" }, "content": { "type": "string" }, "from": { "type": "string", "enum": [ "operator", "customer" ] } } } } } }, "responses": { "200": { "description": "The created message", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Idempotency-Replayed": { "description": "True when a completed response was replayed for the supplied idempotency key.", "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "403": { "description": "API key is missing the `messages:write` scope", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Idempotency-Replayed": { "description": "True when a completed response was replayed for the supplied idempotency key.", "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postMessages", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "description": "Unique retry key retained for 24 hours (maximum 255 characters). Authenticated callers only.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ] } }, "/api/messages/{messageId}": { "get": { "tags": [ "Messages" ], "summary": "Get a message by id", "description": "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.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "The message", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "404": { "description": "Not found (or outside the authenticated tenant)", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getMessagesByMessageId" } }, "/api/messages/{messageId}/read": { "post": { "tags": [ "Messages" ], "summary": "Mark a protected customer reply as read", "responses": { "200": { "description": "The receipt is read (including an idempotent retry)", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "postMessagesByMessageIdRead", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ] } }, "/api/messages/{messageId}/rating": { "post": { "tags": [ "Messages" ], "summary": "Rate an agent or operator reply", "description": "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.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "websiteId", "rating" ], "properties": { "websiteId": { "type": "string" }, "rating": { "type": "string", "enum": [ "unhappy", "neutral", "happy" ] } } } } } }, "responses": { "200": { "description": "The rated message", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "400": { "description": "Unrecognised rating value", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such rateable message for this chat session", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postMessagesByMessageIdRating", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ] } }, "/api/sandbox/documents": { "get": { "tags": [ "Sandbox" ], "summary": "Read sandbox help-center documents without authentication", "description": "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.\n", "security": [], "responses": { "200": { "description": "Demonstration help-center documents.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "locale": { "type": "string" } } } } } }, "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } } }, "429": { "description": "Anonymous rate limit exceeded; retry after `Retry-After` seconds.", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getSandboxDocuments", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ] } }, "/api/sandbox/documentsummaryjobs": { "post": { "tags": [ "Sandbox" ], "summary": "Start a demonstration asynchronous document-summary job", "description": "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.\n", "security": [], "responses": { "202": { "description": "Job accepted; poll the `Location` URL for the result.", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Location": { "description": "URL of the created job resource.", "schema": { "type": "string", "example": "/api/sandbox/documentsummaryjobs/c2FuZGJveGpvYnwxNzU2NTAwMDAwMDAw" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded" ] }, "creationTime": { "type": "string", "format": "date-time" } } } } } }, "429": { "description": "Anonymous rate limit exceeded; retry after `Retry-After` seconds.", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" }, "Retry-After": { "description": "Seconds until this request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postSandboxDocumentsummaryjobs", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ] } }, "/api/sandbox/documentsummaryjobs/{jobId}": { "get": { "tags": [ "Sandbox" ], "summary": "Poll a demonstration document-summary job", "description": "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.\n", "security": [], "parameters": [ { "in": "path", "name": "jobId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "Current job state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded" ] }, "creationTime": { "type": "string", "format": "date-time" }, "completionTime": { "type": "string", "format": "date-time" }, "document": { "type": "object", "properties": { "_id": { "type": "string" }, "title": { "type": "string" }, "locale": { "type": "string" } } }, "summary": { "type": "string" } } } } }, "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } } }, "404": { "description": "Unknown job id.", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getSandboxDocumentsummaryjobsByJobId" } }, "/api/webhooksubscriptions": { "get": { "tags": [ "Webhook subscriptions" ], "summary": "List webhook subscriptions", "description": "Webhook subscriptions deliver `message.created`, `conversation.created` and `customer.created` events to your server as signed POST requests (`X-Supovia-Signature: t=,v1=`). 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.\n", "security": [ { "accessToken": [] } ], "responses": { "200": { "description": "Array of webhook subscriptions (without secrets)", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } } }, "operationId": "getWebhooksubscriptions", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ] }, "post": { "tags": [ "Webhook subscriptions" ], "summary": "Create a webhook subscription", "description": "The response includes the signing `secret` exactly once — store it; it cannot be retrieved again.\n", "security": [ { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "websiteId", "url" ], "properties": { "websiteId": { "type": "string" }, "url": { "type": "string", "example": "https://example.com/supovia-webhook" }, "events": { "type": "array", "description": "Empty array subscribes to all events", "items": { "type": "string", "enum": [ "message.created", "conversation.created", "customer.created" ] } } } } } } }, "responses": { "200": { "description": "The created subscription, including its secret", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "postWebhooksubscriptions", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ] } }, "/api/webhooksubscriptions/{webhookSubscriptionId}": { "put": { "tags": [ "Webhook subscriptions" ], "summary": "Update a webhook subscription", "description": "`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.\n", "security": [ { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "webhookSubscriptionId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The updated subscription (without secret)", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "putWebhooksubscriptionsByWebhookSubscriptionId" }, "delete": { "tags": [ "Webhook subscriptions" ], "summary": "Delete a webhook subscription", "security": [ { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "webhookSubscriptionId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "Deleted", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "deleteWebhooksubscriptionsByWebhookSubscriptionId" } }, "/api/websites": { "get": { "tags": [ "Websites" ], "summary": "List websites", "description": "Lists the websites (projects) of your organization. Requires the `websites:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "responses": { "200": { "description": "Array of websites", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } } }, "operationId": "getWebsites", "parameters": [ { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ] } }, "/api/websites/{websiteName}": { "get": { "tags": [ "Websites" ], "summary": "Get a website by name", "description": "Requires the `websites:read` scope.", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "websiteName", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "API-Version", "required": false, "description": "Compatibility version. Omit to select version 1.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } ], "responses": { "200": { "description": "The website", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "404": { "description": "Not found", "headers": { "RateLimit": { "description": "Quota, remaining requests, and reset time.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Quota policy applied to the credential.", "schema": { "type": "string" } }, "API-Version": { "description": "Compatibility version used for this response.", "schema": { "type": "string", "enum": [ "1" ] } }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/DeprecationLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getWebsitesByWebsiteName" } } }, "tags": [] }