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

# Messaging API

> Base URLs, authentication, versioning, and response envelopes for the Messaging API.

Polymorfa has three public API families. The Messaging API uses separate native
and Meta-compatible OpenAPI documents so clients do not mix request shapes.

| Contract       | Base paths                               | Use it for                                                                                                 |
| -------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Messaging API  | `/api/*`, `/vNN.0/*`, `/health`, `/ping` | Sessions, messages, contacts, groups, webhooks, media, pairing, and Meta Cloud API-compatible integrations |
| Platform API   | `/v1/*`                                  | Organization, project, billing, campaign, and session automation                                           |
| Enterprise API | `/api/*`, `/admin/*`                     | Messaging plus instance administration                                                                     |

The production base URL is:

```text theme={null}
https://api.polymorfa.com
```

## Authentication

Service calls send a credential in the bearer header:

```http theme={null}
Authorization: Bearer titan_…
```

The three service credential kinds retain their compatibility prefixes:

* `titan_…` — organization/server key.
* `titan_pt_…` — project credential, restricted to its owning project.
* `titan_ct_…` — short-lived client token, restricted by session and client rules.

Dashboard routes use a short-lived bearer and recheck live session,
organization, membership, ban, and role state. See
[Authentication](/api/authentication).

## Messaging API versioning

```http theme={null}
Titan-Version: 2026-03-20
```

The Messaging API defaults to `2026-03-20` and echoes the resolved version.
Older versions follow the `Deprecation`, `Sunset`, and `Link` behavior described
in [Versioning](/api/versioning). Meta-compatible paths use their own `vNN.0`
version.

## Success and error shapes

Most typed Messaging API responses use one of these envelopes:

```json theme={null}
{ "success": true, "data": { "id": "…" } }
```

```json theme={null}
{ "success": true, "message": "completed" }
```

Messaging API errors contain a safe human-readable `error` string and may
include a `docs` URL:

```json theme={null}
{
  "error": "session not found",
  "docs": "https://docs.polymorfa.com/api/sessions"
}
```

Meta-compatible errors use Meta's `error` envelope and `fbtrace_id`.
See [Errors](/api/errors).

Every response carries `X-Request-Id`. Send your own value to correlate a call,
or log the generated one when contacting support.

## API references

Use the generated endpoint page for the exact parameters, request bodies,
responses, security requirements, and component types. The live OpenAPI
document for the Messaging API is also available at
`https://api.polymorfa.com/docs/openapi.json`.

<Columns cols={2}>
  <Card title="Authentication" icon="lock" href="/api/authentication">Credential kinds, scopes, and audiences.</Card>
  <Card title="Meta-compatible requests" icon="share-nodes" href="/api/messaging-api-compatibility">Use Messaging API paths and shapes compatible with Meta Cloud API.</Card>
  <Card title="Platform API" icon="sliders" href="/api/platform-api">Public `/v1` paths, credentials, and schemas.</Card>
  <Card title="Enterprise API" icon="server" href="/api/enterprise-api">Instance administration and messaging operations.</Card>
</Columns>