## 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://chatwoot.losangosolucoes.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://chatwoot.losangosolucoes.com.br/swagger/ui.html>
- **OpenAPI definition (JSON)** — the raw file to import into Postman, Insomnia or to generate SDKs:
  <https://chatwoot.losangosolucoes.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

1. Open the reference at <https://chatwoot.losangosolucoes.com.br/swagger> (ReDoc) and browse the module
   groups in the sidebar.
2. Find the endpoint you need (by method and path) and read its parameters, body and responses.
3. To **test**, open the interactive reference at
   <https://chatwoot.losangosolucoes.com.br/swagger/ui.html>.
4. Read the operation's security requirement before **Authorize**, then enter only a credential compatible
   with that path.
5. Pick an endpoint, click **Try it out**, fill in the parameters and click **Execute** only when the test
   environment and operation permit it.
6. 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.

## See also

- [Dashboard Apps SDK, REST API and MCP](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-en)
- [REST API, tokens and webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-en)
- [API & Developers overview](/hc/ajuda/articles/api-developers-overview-en)
- [Per-module events](/hc/ajuda/articles/api-developers-eventos-por-modulo-en)