Skip to main content

​
CXP API overview

Use the CXP API to connect trusted websites, portals, and backend automations to your customer experience workflows. Create or continue conversations, update operational fields, assign work, add internal notes, and read details/history. ChatGPT and Codex use a separate OAuth connection and MCP endpoint; they do not use tenant API keys. See Connect CXP to ChatGPT and Codex for that user-consent flow.

​
Prerequisites

Before you send a request, obtain these values from your Crescendo contact:
  • Your tenant ID
  • A tenant API key with cxm:conversations.read for reads and cxm:conversations.write for writes (or a broader scope for the action)
  • 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:
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. A write-only key does not grant read access; choose read/write or wildcard scopes for an integration needing both.

​
Request conventions

  • GET Conversation detail/history requests have no body. History accepts optional limit (1–200, default 100) and opaque cursor query parameters.
  • For writes, use Content-Type: application/json.
  • Create Conversation accepts at most 1 MiB; update, assignment, and internal-note operations accept at most 32 KiB.
  • 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.
Each accepted write executes independently. Repeating a request can create another conversation, message, or internal note, or repeat a field change. If a timeout or transport error makes the outcome unclear, verify the result before retrying when possible.

​
Responses and errors

Conversation detail reads return the latest projection without root messages; history reads return one oldest-first stored page, including internal notes. Missing projections/history return null/empty successful results. Both reads are marked Cache-Control: no-store. See Manage conversations. 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:
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 or Manage conversations for request mappings, routing behavior, and copyable examples. Open API reference in the developer navigation for the generated operation and machine-readable contract.