> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactbutton.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API and MCP surfaces

> Choose the current REST, MCP, public Chat, and discovery interfaces, including their authorization and rollout boundaries.

This reference describes the implementation on `main` as reviewed on November 16, 2026. Availability depends on the deployed release, environment flags, workspace permissions, and provider readiness. A documented endpoint is not a claim that its feature is enabled in Production.

## Choose an interface

| Interface | Address | Authorization and purpose |
| - | - | - |
| Workspace REST | `https://api.contactbutton.com/v1` | Scoped API key; workspace and resource UUIDs. Content, onboarding, Inbox, bookings, reviews, telephony, and commerce management. |
| Workspace MCP | `https://api.contactbutton.com/mcp` | Scoped API key or registered MCP OAuth client. Content setup, authenticated Inbox, and creator commerce tools. |
| Documentation MCP | `https://docs.contactbutton.com/mcp` | Public documentation search. |
| Public Page MCP | `https://api.contactbutton.com/mcp/pages/{page_id}` | One published, non-password-protected Page. Public reads and visitor-reviewed action proposals. |
| Direct Agent MCP | `https://api.contactbutton.com/mcp/agents/{agent_id}` | Owner-enabled public questions to one published Agent. One question per call, with question and answer saved in Agent history. |
| Public Agent REST | `/v1/public/agents/{agent_id}` | Published Agent metadata and conversations. Subsequent conversation operations require `X-Conversation-Token`. |
| Native Chat REST | `/v1/public/apps/{app_id}/chat` | An active Chat Widget routed to Inbox. Uses the same participant-token pattern without calling an AI model. |
| Public Page actions | `/v1/public/pages/{page_id}` | Discover current capabilities and request visitor-reviewed, verified actions. |
| A2A | Advertised by the Page's Agent Card | Page-scoped tasks and action review. See [A2A](https://docs.contactbutton.com/agents/a2a.md). |

Paths beginning with `/v1` use the API host. The application-domain `/v1` and `/mcp` aliases remain supported. There is no `/api` prefix on the public contract. Use an environment's own service document and OpenAPI server URLs when testing outside Production.

The public OpenAPI document covers public `/v1` product routes. Mobile `/mobile/v1`, legacy `/v1/auth` and `/v1/projects`, browser privacy-consent routes, provider webhooks, and the private dashboard Assistant delegation endpoint `/mcp/assistant` have separate application-specific contracts. They are not general-purpose integration entry points.

## Find the current contract

| Document | Purpose |
| - | - |
| `GET https://api.contactbutton.com/v1` | Entry point, authentication, API contract, documentation, and Workspace MCP availability. |
| `GET https://api.contactbutton.com/openapi.yaml` | REST request and response schemas. The documentation site's API Reference uses the same checked-in source. |
| `GET https://api.contactbutton.com/.well-known/api-catalog` | API and protocol discovery links and token abilities. |
| `GET https://api.contactbutton.com/mcp.json` | Documentation and Workspace MCP server discovery. Page and Agent endpoints are selected using their public IDs. |
| MCP `initialize`, then `tools/list` | The connected server's negotiated capabilities, exact tool names, and input schemas. |

Use `contactbutton_get_page_manifest` for a workspace Page manifest and `contactbutton_get_profile` for a public Page profile. The current MCP servers expose these through tools; do not depend on the older `contactbutton://pages/{page_id}/manifest` resource URI.

## What REST covers

* **Setup and content:** workspaces, teams, settings, revisioned onboarding, Pages and domains, Buttons and templates, Apps, Forms, Lists, Surveys, and Knowledge.
* **Agents:** effective controls, profiles, ordered rules, knowledge assignments and gaps, handoff policies, and deterministic automations. Use the dedicated routes and their feature gates.
* **Inbox:** Contact-centric threads, messages, attachment upload/download/deletion, channel connections, templates, follow-ups, and confirmed workspace bookings. Read [Conversations API](https://docs.contactbutton.com/guides/conversations-api.md).
* **Calling:** telephony readiness, call flows, numbers, voice interactions, and browser dialer sessions. Session creation returns temporary credentials and intentionally bypasses REST idempotency replay. Read [Telnyx](https://docs.contactbutton.com/guides/telnyx.md).
* **Reviews:** destinations, connected locations, cursor-paginated reviews, provider reply updates/deletion, and consented review requests. Read [Reviews](https://docs.contactbutton.com/guides/reviews.md).
* **Commerce:** offers, support Apps, Stripe Connect onboarding, payments, creator reports, membership subscriptions, and supporter replies. Read [Creator commerce](https://docs.contactbutton.com/guides/creator-commerce.md). Both commerce and public-checkout gates must be enabled for visitor payment creation.
* **Public surfaces:** Agent and native Chat conversations, attachments and callback capture, Page action proposals, Surveys, Knowledge, Questions, Answer Widgets, and Review Widgets. Public visibility is checked independently of knowing a UUID.

## Permissions, retries, and confirmation

Use the [scope table](https://docs.contactbutton.com/authentication.md) to select a key. A scope grants an operation only inside workspaces the caller may access. MCP OAuth also requires an active grant for the selected workspace and the canonical MCP audience; these tokens are not REST API keys.

Send a unique `Idempotency-Key` for supported REST mutations and preserve the exact request for retries. Some endpoints require it; others accept it. File uploads and browser call sessions need their own retry handling. MCP setup and Inbox writes use a UUID `request_id`; public proposal tools use `idempotency_key`. Older MCP creation tools retain their original schemas and do not provide the new receipt contract.

Public MCP and A2A material actions return a Contact Button `review_url`. The visitor reviews and verifies on Contact Button; external clients cannot approve themselves or obtain the OTP. Authenticated Inbox booking tools instead act with the workspace operator's authority, reserve a slot immediately, and queue connected-calendar synchronization. Show the operator the requested action before calling a write tool.

See [MCP servers](https://docs.contactbutton.com/agents/mcp.md), [Agent protocol parity](https://docs.contactbutton.com/agents/protocol-parity.md), [Human confirmation](https://docs.contactbutton.com/agents/confirmation.md), and [Rollout](https://docs.contactbutton.com/guides/rollout.md) for the detailed boundaries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.