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

# CXP API overview

> Authenticate to the CXP API and understand its tenant, security, execution, and response conventions.

# CXP API overview

Use the CXP API to connect trusted websites, portals, and backend automations to
your customer experience workflows. The first available endpoint creates or
continues a conversation from a structured form submission.

## Prerequisites

Before you send a request, obtain these values from your Crescendo contact:

* Your tenant ID
* A tenant API key with the `cxm:conversations.write` scope (or a broader CXP
  write scope)
* The production API base URL

Keep API keys in a server-side secret store. Never put an API key in browser,
mobile app, or public form code. Send requests over HTTPS.

## Authenticate

Send the API key as a bearer token:

```http theme={null}
Authorization: Bearer <tenant-api-key>
```

The tenant in the URL and every ID, email channel, agent, or team referenced by
the request must belong to the API key's authorized tenant. Write endpoints do
not accept a bearer token in the query string.

## Request conventions

* Use `Content-Type: application/json`.
* Keep the complete JSON body at or below 1 MiB.
* Unknown request properties are rejected.
* Optional blank strings are treated as absent where the endpoint permits
  them.
* Email addresses are trimmed and normalized to lowercase; phone numbers are
  normalized to E.164 format.

You may send `X-Request-Id` or `X-Correlation-Id` to help Crescendo support
trace a request. These headers are tracing identifiers only. They do not make a
request idempotent or suppress duplicate work.

<Warning>
  Every accepted POST executes. Repeating a request can create another
  conversation or append another customer message. If a timeout or transport
  error makes the outcome unclear, verify the result before retrying when
  possible.
</Warning>

## Responses and errors

Success responses contain the result of the requested operation. They can also
contain a `warnings` array when the primary operation succeeded but a
documented best-effort follow-up did not. Treat warnings according to the
endpoint guide; they are not error responses.

Errors use a stable JSON envelope:

```json theme={null}
{
  "code": "BadRequest",
  "message": "message.text is required"
}
```

For `429 RateLimitExceeded`, wait for the number of seconds in the
`Retry-After` response header. A `502` or `504` can have an ambiguous mutation
outcome; retrying can duplicate the effect.

## Next step

Follow [Create a conversation](./create-conversation) for request mappings,
routing behavior, and copyable examples. Open **API reference** in the
developer navigation for the generated operation and machine-readable
contract.