API and webhooks
How programmatic access to CoPhrase works — a versioned public API authenticated with organization-owned keys, plus signed outgoing webhooks.
The reference is not published yet
CoPhrase is pre-launch. This page describes the shape of the API — how it is versioned, how you authenticate, how webhooks behave — so you can plan an integration. The endpoint reference, request and response schemas, and SDKs are coming, and no endpoint paths are listed here until they are real.
Two lanes, one of which is yours
CoPhrase's backend serves two different API surfaces on purpose:
| Lane | Who it's for | Stability |
|---|---|---|
Public API — versioned under /v1 | You. Integrations, scripts, automation, our own MCP server. | A frozen contract. Breaking changes mean a new version. |
| App API | The CoPhrase dashboard, authenticated with your browser session. | Not a public contract. It changes whenever the frontend does. |
If you are integrating with CoPhrase, you build against /v1. Do not reverse-engineer whatever the dashboard is calling — that surface is deliberately unstable and unsupported, and it can change without notice.
Authentication
Programmatic access uses API keys owned by an organization, not by a person.
- Issued per organization, from Settings → Integrations in the dashboard. The key is scoped to that one organization, and every request made with it is scoped there too. There is no cross-organization key.
- Scoped and rate-limited per key. You can give a key a narrow permission set and its own rate limit, so an integration that only needs to read conversations cannot write contacts.
- Expiring keys are supported — set an expiry when you create one.
- Hashed at rest. We store a hash, not the key. You see the key once, at creation. If you lose it, you rotate it; we cannot recover it.
- Because the key belongs to the org and not to a user, an employee leaving does not silently break your integration.
For agencies: a client workspace is its own organization, so it has its own keys. There is no single agency-wide key that reaches into every client's data — that is the same explicit-access rule the agency access model follows everywhere.
Sessions are for humans, keys are for machines
The dashboard authenticates with a session cookie. The public API authenticates with an API key. They are not interchangeable, and there is no way to drive /v1 with a browser session or a dashboard with a key.
Webhooks
Webhooks are the outbound half: CoPhrase pushes events to a URL you control, so you can drive Zapier, Make, n8n, or your own service off things that happen in your agent.
What you should design for:
- You subscribe per event type. A webhook registers a URL plus a filter over the event catalog — you receive what you asked for, not everything.
- Payloads are HMAC-signed. Every delivery carries a signature computed with a secret only you and CoPhrase know. Verify it before you act on a payload; an unsigned or badly-signed request is not from us.
- Deliveries are retried, and logged. A failed delivery is retried with backoff, and you can see the delivery log — status, attempt count, response code — in the dashboard.
- A dead endpoint gets auto-disabled. After enough consecutive failures we stop delivering and mark the webhook disabled with a reason. Re-enabling is a deliberate manual action — re-saving the endpoint will not silently re-arm it.
- Endpoints must be public HTTPS.
localhost, private IP ranges, and internal hostnames are rejected when you save the webhook, not when it first fires.
Related surfaces
- Custom channel — an inbound POST plus an outbound webhook, for driving a channel CoPhrase doesn't support natively. See channels.
- Custom functions / tools — your own HTTPS endpoints, called by the agent mid-conversation as tools. That is a different thing from webhooks: the agent calls you and waits for an answer. See actions.
- MCP server — a planned CoPhrase MCP server, so an AI client can drive the platform. It is a thin shim over the same public
/v1, using the same keys — which is exactly why/v1is a frozen contract from day one.