API reference (Swagger / OpenAPI)

Open in

View as Markdown

Open in ChatGPT Open in Claude

Conversa Labs

Last updated on Oct 21, 2026

Overview

ConversaLabs publishes an OpenAPI 3.1 public-surface reference for discovering and integrating the endpoints that belong to that contract. It is produced from routes and curated sources; it does not promise that every internal route, enabled module, or installation form is automatically published.

There are three ways to view the same reference:

ReDoc (reading) — a navigable documentation, organized by groups and tags, ideal to understand each endpoint's contract: https://app.conversalabs.com.br/swagger
Swagger-UI (interactive) — the same reference with a "Try it out" button to make real API calls right from the browser: https://app.conversalabs.com.br/swagger/ui.html
OpenAPI definition (JSON) — the raw file to import into Postman, Insomnia or to generate SDKs: https://app.conversalabs.com.br/swagger/swagger.json

The reference groups Account/AgentBot under /api/v1, Platform under /platform, Widget under /api/v1/widget, public routes under /public/api, public discovery/challenge metadata, and webhook paths that belong to the contract. Read each operation's declared security: no universal token exists.

Prerequisites

The credential required by that operation: an account/AgentBot token, Platform App key, resource-specific public token, or no credential, according to its contract.
A modern browser. To test calls, prefer a token from a test environment.

Step by step

Open the reference at https://app.conversalabs.com.br/swagger (ReDoc) and browse the module groups in the sidebar.
Find the endpoint you need (by method and path) and read its parameters, body and responses.
To test, open the interactive reference at https://app.conversalabs.com.br/swagger/ui.html.
Read the operation's security requirement before Authorize, then enter only a credential compatible with that path.
Pick an endpoint, click Try it out, fill in the parameters and click Execute only when the test environment and operation permit it.
Review the response (status, body) and reuse the generated request example (cURL) in your integration.

Settings & options

Coverage and authentication: new routes must be included and reviewed in the contract. Operations may use api_access_token, a Platform App key, a resource token, or explicit empty security; never copy a credential across surfaces by assumption.
Inbound webhooks: a path accepts calls only when its configuring feature is enabled and validated. Authentication differs by provider/resource (signature, secret, verification token, or challenge), so it is not a generic REST API to try with an account token.
Metrics: /monitoring/metrics is not a customer operation. It is inert until the operator sets OPERATIONS_METRICS_TOKEN, then requires Authorization: Bearer <token> for an authorized scrape.
MCP and operator: MCP uses its own profiles, URLs, and Bearer/OAuth credentials. Operator REST has a separate reference and is not served from /swagger.
Availability: on self-hosted installs, the docs are enabled by the operator via an environment variable (ENABLE_API_DOCS). On hosted ConversaLabs they're already available at the URLs above.

Use cases

Determine whether an integration belongs to Account/AgentBot, Platform, Widget, or a public surface.
Check an operation's requirements before testing a call in a controlled environment.
Import the OpenAPI definition into Postman/Insomnia or generate a client SDK.

Tips, limits & best practices

Treat every token or secret as confidential; never expose it in a front end or reuse it between Account/AgentBot, Platform, Widget, MCP, and Metrics.
For tests, use a least-privilege credential and confirm whether the operation is authenticated, public, or a conditional inbound webhook.
Respect rate limits and handle 429/5xx errors with backoff.

Types and responses in integrations

Use each response schema, as well as its example, when generating or validating your client:

For calendar events, all_day is a boolean and reminders values are integers in minutes.
In the profile, accounts[] includes onboarding progress, the access-role identifier and api_and_webhooks. The access_role object appears only when an effective role exists; permission-dependent fields remain subject to server authorization.
In the Brain, signals and suggested_action can preserve JSON arrays. Do not force them into maps; reading and redaction still follow the caller's permissions.
A Follow-up enrollment can respond with 422 and either error (a rejection reason) or message and attributes (a validation failure). Read the received variant before choosing the next action.

Troubleshooting

The page doesn't open (404): the docs may be disabled in that environment — the operator enables them with ENABLE_API_DOCS.
401/403 when testing: confirm the surface and security scheme; an api_access_token does not automatically authorize Platform, MCP, Metrics, or public routes.
An endpoint is missing: it may be outside the public reference, need a curated source, or belong to the operator's separate REST reference.