Build with UpHex API

Authentication

Protected `/v1` routes and `/mcp` accept exactly one authentication method per request.

• API key headers: `X-API-Key: uphex_key_...` plus `X-API-Secret: uphex_secret_...`, issued per developer app in the portal. The secret is shown once.
• API key over HTTP Basic: `Authorization: Basic base64(api_key:api_secret)`.
• Bearer: `Authorization: Bearer <token>` with an OAuth access token (`uphex_access_...`) or a one-hour token from `POST /v1/tokens`.
• Bearer tokens and legacy tokens carry the scopes of the OAuth grant or API key they came from.
• Mixing bearer auth with API key headers, or sending an auth header twice, returns `401`.
• `GET /v1/health` is the cheapest way to confirm credentials; it returns the app id, name, environment, and granted scopes.

OAuth flow

OAuth is authorization code + PKCE (S256) with confidential clients. It is meant for developer users in the developer account that owns the OAuth client.

• Register a client in the portal or with `POST /v1/oauth/clients` (`oauth:clients:write`). The `uphex_oauth_secret_...` secret is returned once.
• Redirect URIs must be `https`, or `http` only for localhost/loopback, with no userinfo or fragment, and they match exactly.
• Send the user to `/oauth/authorize`; they must be signed in to the Developer Portal in the owning account. Requested scopes must be a subset of the client's scopes (all client scopes when omitted).
• The authorization code is single-use and expires after 10 minutes. Tokens are bound to one agency resolved from the approving user's account and the app's allowed agencies.
• Exchange the code at `/oauth/token` with `redirect_uri` and `code_verifier`. Access tokens last 1 hour; refresh tokens last 30 days and rotate on every refresh.
• Only `authorization_code` and `refresh_token` grants exist; there is no `client_credentials` grant. Server-to-server integrations should use API keys.
• Token and revoke errors use OAuth-style bodies such as `{"error":"invalid_grant"}`; client authentication failures return `401` `invalid_client`.
• `Idempotency-Key` works with OAuth access tokens on every write that accepts it. On edge-stored routes keys are scoped to the OAuth client and the token's agency, so a refreshed token keeps seeing them; `POST /v1/leads/{id}/messages` and `POST /v1/appointments` require a key and crm-service holds it per developer app.

Publishing your app

Every app starts private: only your developer account's own agency and agencies UpHex granted can install it. To let any agency install it through OAuth consent, submit it for UpHex review.

• Register an OAuth client with every scope and redirect URI the app needs, including at least one `https` redirect URI.
• On the app page in the portal, fill in the public listing (description up to 1,000 characters, `https` homepage URL, `https` privacy policy URL, and a support email) and choose Submit for review. The app shows `in review`.
• UpHex approves or rejects the submission. Approval makes the app `public` and records the scopes and redirect URIs of its active OAuth clients as the approved snapshot. A rejection shows the reason; fix it and submit again.
• Agencies can only consent to scopes and redirect URIs in the approved snapshot. Adding a scope or redirect URI to a public app's OAuth clients marks it `changes pending review`: consent requesting the new scope returns `invalid_scope` (an unapproved `redirect_uri` is refused without a redirect) until UpHex re-approves, while already-approved scopes keep working.
• Removing a scope, revoking an OAuth client, and rotating a client secret never trigger re-review.
• UpHex may delist a public app. Delisting blocks new installs and re-consent by other agencies (your own and UpHex-granted agencies can still install it, as with a private app); existing installs and their tokens keep working until an agency revokes them.
• Once public, webhooks for an agency are delivered through that agency's installation and its granted scopes. To keep receiving events for your own agency after approval, connect it once through OAuth consent.

Rate limits

Authenticated `/v1` and `/mcp` traffic is counted per developer app in fixed one-minute windows; all of an app's API keys and OAuth tokens share one counter.

• The default limit is 120 requests per minute per app; the per-app maximum is 1,000.
• Every counted response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (Unix seconds).
• Over the limit, the edge returns `429` with `Retry-After` in seconds and `{"errors":{"base":["Rate limit exceeded"]}}`.
• `POST /v1/tokens` is limited to 120 attempts per minute per source IP and 30 per presented API key.
• `/oauth/token` and `/oauth/revoke` are limited to 120 attempts per minute per source IP and 60 per presented client id.

Pagination

List routes are page-numbered and report totals in `meta`.

• Send `page` (1-based). Page size is fixed by the owning service, except `GET /v1/templates` and `GET /v1/leads`, which accept `per_page` from 1 to 100 (leads default to 25).
• Read `meta.page`, `meta.per_page`, `meta.total_entries`, and `meta.total_pages`, and stop when `page` reaches `total_pages`.
• Unsupported query parameters, including `per_page` on routes that do not accept it, return `400`.
• `GET /v1/leads` with `updated_since` or `cursor` is keyset-paginated instead: read `meta.next_cursor` and `meta.has_more`, and send `next_cursor` back as `cursor` until it is `null`. `page` cannot be combined with either.
• `GET /v1/conversations` and `GET /v1/leads/{id}/messages` use `limit` and an opaque `cursor`: send `meta.next_cursor` back as `cursor` until it is `null`.

Leads

`/v1/leads` is the single public lead resource, backed by UpHex's CRM (the same leads shown in the CRM inbox, pipelines, and workflows). Tags, notes, activities, pipeline stage, and channel opt-outs nest under `/v1/leads/{id}`.

• Every lead route requires `client_id` (query string on reads and deletes, JSON body on writes). A `client_id` outside the authorized agency returns `404` `client_not_found`.
• Lead ids are CRM lead ids. Ids returned by the pre-CRM `/v1/leads` (before October 2026) are not valid; look leads up again with `GET /v1/leads/lookup`.
• Lead fields: `id`, `client_id`, `full_name`, `email`, `phone`, `status`, `pipeline_id`, `pipeline_stage_id`, `campaign_id`, `campaign_name`, `created_time`, `source`, `updated_at` (ISO 8601 UTC), `tags`, and `metadata`. `ghl_tags` is a deprecated alias of `tags` and will be removed in a later release.
• List filters: `search` (partial name, email, or phone), `email` (exact), `status`, `tag`, `pipeline_id`, `pipeline_stage_id`, and `campaign_id`; page with `page` and `per_page` (1-100, default 25).
• Incremental sync (a backstop to webhooks): `updated_since` (ISO 8601; inclusive, second precision; no offset means UTC, a bare date means midnight UTC; percent-encode a `+` offset as `%2B`) returns leads changed at or after that time, ordered by `updated_at` then `id`, and pages with `meta.next_cursor` / `cursor` instead of `page`. A lead updated while you page is returned again on a later page, so upsert by `id`; poll from a few minutes before the largest `updated_at` you stored. Removed leads are not returned.
• `POST /v1/leads` creates one lead and returns `201`. Send `match: "email_then_phone"` to return the client's existing lead (`200`, `meta.matched: true`) when one has the same email, or else the same phone, instead of creating a duplicate.
• `PATCH /v1/leads/{id}` updates `full_name`, `email`, `phone`, `status`, and `metadata` (replaced as a whole). Sending `pipeline_stage_id` (and optionally `pipeline_id` to switch pipelines) also moves the stage; the stage move runs first.
• Tags are referenced by name. `POST /v1/leads/{id}/tags` with `{"tags": [...]}` creates any missing tags; `DELETE /v1/leads/{id}/tags/{tag}` removes one by name (`404` if the client has no such tag). Both return the updated lead.
• Notes are authored as your developer app. Activities accept `activity_type` `call` or `email`, a `description`, optional `metadata`, and optional `occurred_at`.
• `/v1/leads/{id}/contact_channels` reads and sets do-not-disturb per channel: `email`, `sms`, `marketing_sms`, or `transactional_sms`.
• Leads created through the API have `source` `public_api` in UpHex.

Calendars and appointments

`/v1/calendars` and `/v1/appointments` read and book crm-service calendars for one client of the credential's agency. Reads need `calendars:read`; booking, rescheduling, and canceling need `appointments:write`.

• Every `client_id` must belong to the credential's agency; other ids return `404` `client_not_found`.
• Appointment ids are strings: `bk_<id>` is a native UpHex booking and `la_<id>` is an appointment synced from GHL, Calendly, or Google.
• Appointments carry `provider` (`native`, `ghl`, `calendly`, `google`) and `status` (`scheduled`, `pending`, `rescheduled`, `cancelled`, `no_show`, `showed`). Times are UTC.
• v1 limit: only active, free event types on native UpHex calendars can be booked. Anything else, including GHL or Calendly calendar ids, returns `422` `calendar_not_bookable`; synced appointments are read-only (`422` `appointment_read_only`).
• `POST /v1/appointments` requires `Idempotency-Key` (up to 200 characters) with API keys and OAuth tokens. A replay returns `200` with `X-Idempotent-Replay: true`; reusing a key for a different booking returns `409` `idempotency_key_conflict`.
• Rescheduling creates a new appointment whose `previous_appointment_id` is the moved one.
• Booking-domain errors use the normalized error list `{"errors":[{"code","title","detail","source"}],"request_id"}` with a stable `code`: `409` `slot_unavailable` or `idempotency_key_conflict`; `422` `calendar_not_bookable`, `outside_availability`, `lead_missing_contact`, `range_too_large`, `appointment_read_only`, `appointment_not_reschedulable`, or `appointment_not_cancelable`; `404` `event_type_not_found`, `lead_not_found`, or `appointment_not_found`. Edge validation, scope, and `Idempotency-Key` failures use `errors.base`.

Conversations & messages

Conversations, lead message history, sends, and messaging readiness are proxied to crm-service and messaging-service. `client_id` is required (query string on reads, JSON body on `POST`) and must belong to the authorized agency for every credential type; otherwise `404` `Client not found`.

• `GET /v1/conversations` lists the client's actionable conversations: the latest message is inbound, or outbound within the last 72 hours, or the lead is new within 72 hours. `limit` 1-100 (default 25); follow `meta.next_cursor` until it is `null`.
• `updated_since` (ISO 8601 with offset) keeps conversations whose `updated_at` is at or after it. It filters each page, so a page can hold fewer than `limit` items; keep following `next_cursor`.
• `GET /v1/leads/{id}/messages` returns newest first: `channel` (`sms`, `email`, `voice`, `custom`), `limit` 1-100 (default 50), `cursor`. History reaches the 500 most recent messages.
• `POST /v1/leads/{id}/messages` with `type: sms` (`body`) or `type: email` (`body`, `subject`, optional `html`, `from_email`) sends through UpHex messaging and records the message: `201` when new.
• `type: custom` (`direction`, `body`, `channel_label` up to 40 characters, optional `external_id` up to 200, `occurred_at`) only logs the message; nothing is delivered. Inbound custom messages fire `contact_replied` workflows. `occurred_at` is returned in UTC; history is ordered by when UpHex recorded the message.
• `Idempotency-Key` (1-200 letters, numbers, `.`, `_`, `:`, `-`) is required on this `POST` for API keys and OAuth tokens alike; crm-service, not the edge key store, holds it. A repeat returns `200` with `meta.idempotent_replay: true` and `X-Idempotent-Replay: true`, a failed send replays the same error, and a key reused for a different send returns `409` `idempotency_key_conflict`.
• Custom messages dedupe on `external_id` when you send one, otherwise on the key. A repeat whose stored message differs (direction, body, or channel label) returns `409` `idempotency_key_conflict` (key) or `external_id_conflict` (your `external_id`, also returned when it is already used on another lead).
• Keys and external ids are scoped to your app, so two apps on one agency never collide. `external_id` is shown only for messages your app logged with one.
• A refused send keeps crm-service's code and status in the normalized error list (`code`, `title`, `detail`, `source: crm`, plus `reason`, `retryable`, `lead_message_id` when known): `invalid_params` 422, `client_not_found` / `lead_not_found` 404, `lead_missing_phone` / `lead_missing_email` / `invalid_from_email` 422, `ghl_routed_contact` 409, `no_from_number_provisioned` / `a2p_campaign_not_ready` / `sms_suppressed` / `email_suppressed` / `sending_domain_unavailable` 422, `sms_not_enabled` 403, `insufficient_credits` 402, `send_failed` 502 (check `retryable`), `idempotency_key_in_progress` 409, `idempotency_key_conflict` 409.
• `GET /v1/clients/{client_id}/messaging_readiness` (`messages:send` or `conversations:read`) reports `sms.ready` / `sms.reason` (`no_from_number_provisioned` or `a2p_campaign_not_ready`, raw reason in `detail`) and the email sending domain with its status. Lead opt-outs, GoHighLevel routing, plan entitlement, and wallet balance are checked only at send time. A failed read returns `502` `messaging_readiness_unavailable`.
• Sends count against the app's normal per-minute rate limit (default 120, see Rate limits).

Validation

The API edge validates public query params, scopes, lead write payloads, and draft template write payloads before proxying downstream.

• `agency_id` is not accepted as a query param; single-agency apps use the developer account agency by default.
• Multi-agency apps can send `X-Agency-Id`, which must be a bounded positive integer allowed by the app policy.
• Policy headers such as `X-Agency-Id` and `Idempotency-Key` must be sent at most once.
• API key ids, API secrets, API Basic authentication, and bearer tokens are shape-bounded before authentication lookup or token verification.
• `group_by` is required for `GET /v1/metrics` and must be `client_id` or `campaign_id`.
• Campaign creative preview ids must be bounded positive integers; the optional `client_id` filter must match the campaign's owning client or backend returns not found.
• Template preview filters are limited to `platform`, `category_id`, `enabled`, `page`, `per_page`, `q`, and `query`; template ids must be bounded positive integers.
• Template draft create requires `name` and `platform`; update requires a non-empty object. Unknown template body fields, including unsupported nested `ads` and `adsets`, are rejected at the edge.
• Template draft image upload accepts exactly one of `image_url` or `image_base64`; URLs must be HTTPS, base64 data URLs may declare only image/jpeg, image/png, image/gif, or image/svg+xml, decoded images are limited to 10 MB, and the upload route has a 15 MB route-specific request body allowance.
• Date filters must use ISO 8601 format such as `2026-05-29`.
• When both `start_date` and `end_date` are sent on metrics routes, `start_date` must be on or before `end_date`.
• String filters and lead fields are capped at 255 characters; lead ids must be bounded positive integers.
• Comma-separated id filters can contain up to 100 bounded positive integer values.
• Date, integer, and comma-separated id filters must be scalar values; structured objects and arrays are rejected at the edge.
• Public query and lead-write integer fields are bounded before validation parses them or forwards requests downstream.
• Lead creation requires `client_id` and an `email` or `phone`; `email` must be a valid address. Bulk lead creation is not supported.
• External API, OAuth, and MCP request bodies are limited to 1 MB before parsing and during parser reads, including clients that omit `Content-Length`, except `POST /v1/templates/{id}/images`, which uses the same 15 MB route-specific cap in both places.
• MCP requests must be a single JSON-RPC object with `jsonrpc: "2.0"`; ids may be strings (up to 128 bytes) or JSON-safe integers, and null ids, fractional ids, array `params`, and batches are rejected before proxying.
• Parser-level malformed request and unsupported media-type failures use the same public `errors.base` envelope as controller-level validation failures.
• Malformed or duplicated `Content-Length` headers are rejected before request parsing.
• OAuth token and revocation requests reject malformed or oversized authorization codes, refresh tokens, revocation tokens, PKCE verifiers, and redirect URIs before credential material reaches grant lookup paths.
• Protected public API routes reject mixed authentication methods, such as bearer auth plus `X-API-Key` headers.
• Portal-created control-plane display fields are bounded before storage: apps, API keys, OAuth/MCP clients, webhook endpoints, developer users, and accounts fail validation when names, URLs, or descriptions are too large.
• Registered OAuth/MCP redirect URI lists are trimmed, deduplicated, and bounded before invalid URI errors are returned.

Responses

Successful responses always use the same envelope while domain data remains backend-owned.

• `data` contains the resource payload returned by the owning service.
• `meta.resource` identifies the public resource.
• Safe pagination and date range metadata are preserved with redacted and bounded values.
• Internal downstream fields such as agency ids, SQL, or debug keys are filtered.
• Template preview and write echo data is limited to public-safe copy, category, availability, ad/adset preview rows, media URLs or public references, deleted status, and timestamps.
• Campaign creative preview data is read-only and cache-only: backend returns public-safe campaign, adset, ad, creative, media, copy, CTA, status, and cache metadata without provider tokens, targeting, review feedback, object story specs, or asset feed specs.

Creative Writes (beta)

Creative write beta access is conservative: it creates and changes only CMS-owned API drafts for the resolved agency, with explicit scopes, request logs, and reversible stop controls.

• `templates:write` is required for REST create, update, image upload, and delete endpoints; `templates:read` remains enough only for preview reads.
• `mcp:write` exposes the external draft-template write tools (`template_create`, `template_create_direct`, `template_update` by `section`, `template_add_image`, and `template_delete`) while `mcp:read` stays read-only.
• REST and MCP creative writes are draft-only: launched templates, non-drafts, and UI-authored drafts cannot be changed through the public API and return normalized errors instead.
• No public creative write route launches, publishes, activates, or reaches CampaignBuilders/backend campaign launch endpoints.
• `POST /v1/templates` and `POST /v1/templates/{id}/images` support `Idempotency-Key` for API key, legacy bearer-token, and OAuth access token requests. `PATCH /v1/templates/{id}` and `DELETE /v1/templates/{id}` should be retried only after checking the latest template state or request log.
• Image uploads accept one HTTPS URL or one base64 payload. JPG, PNG, GIF, and SVG are supported, decoded images are limited to 10 MB, and the image route uses a 15 MB encoded-body allowance.
• Delete means soft-delete of an API-created draft. It is the documented rollback path for removing beta-created draft assets without affecting launched campaigns.
• Every write is request-logged with `X-Request-ID`, resolved agency, auth mode, downstream CMS status, idempotency state when present, and public caller attribution forwarded to CMS audit paths.
• Rate limits apply at the developer app/API key or OAuth credential boundary and return `429` with `Retry-After` plus rate-limit headers.
• Rollback controls stay at the edge: revoke the API key/OAuth client or pause/suspend/archive the app to stop future REST and MCP writes without deleting downstream audit history.

Errors

Public errors are normalized so integrations get stable status codes and readable details.

• `400` means the API edge rejected an invalid public request, agency header, or idempotency key.
• `401` means authentication failed: missing, malformed, mixed, revoked, or expired credentials, or an inactive app or account. On protected `/v1` routes and `/mcp` the body is always `{"errors":{"base":["Unauthorized"]}}` with a `WWW-Authenticate` challenge; `POST /v1/tokens` returns `Invalid API credentials`, and `/oauth/token` and `/oauth/revoke` return `{"error":"invalid_client"}`.
• `403` means the credential is missing the required scope (`missing_scope`), the app may not access the resolved agency (`agency_not_allowed`), or the owning service refused the request.
• `404` means the owning service did not find the record for the resolved agency, or `GET /v1/{resource}` named an unknown resource (`unknown_resource`).
• `405` is returned for `GET /mcp` and `DELETE /mcp`.
• `413` means the request body exceeded 1 MB (15 MB for template image uploads).
• `429` means the developer app rate limit was exceeded for API key or OAuth traffic.
• API-edge validation, authentication, scope, idempotency, and rate-limit failures use `errors.base` or field-keyed error arrays.
• Downstream rejections use a normalized error list with `code`, `title`, `detail`, and `source`; downstream 4xx statuses are preserved and downstream 5xx statuses become `502` with code `downstream_unavailable`. `/mcp` passes CMS 4xx JSON-RPC bodies through (redacted) and normalizes only 5xx.
• `409` on template writes means CMS found the template for the resolved agency but it is not an API-created draft that can be modified through the public API.
• Stable request-log error codes include `unauthorized`, `invalid_request`, `missing_scope`, `missing_agency_id`, `invalid_agency_id`, `ambiguous_agency_id`, `agency_not_allowed`, `rate_limited`, `invalid_idempotency_key`, `idempotency_key_processing`, `idempotency_key_conflict`, `downstream_rejected`, `backend_unavailable`, `cms_unavailable`, `downstream_timeout`, and `unknown_resource`.
• `POST /v1/tokens` also returns `429` with `Retry-After` when legacy credential exchange attempts exceed IP or presented-key limits.
• `/oauth/token` and `/oauth/revoke` also return `429` with `Retry-After` when client-auth attempts exceed OAuth endpoint limits.
• `502` means an owning downstream service is unavailable.
• `504` means an owning downstream service timed out.
• Proxy/downstream error bodies include `request_id`, matching the `X-Request-ID` header.

Request IDs

Every public API response includes `X-Request-ID`, and the same value is forwarded to downstream UpHex services.

• Keep this id in your logs for support and debugging.
• The developer portal request log is searchable by request id, accepts pasted smoke request-id lists, and is filterable by agency id and status family.
• Portal request-log filters are bounded, and wildcard characters are treated literally.
• Request detail pages show resolved agency, auth mode, downstream status, rate-limit state, and webhook enqueue state.
• `POST /v1/tokens` exchange attempts are logged without storing API secrets.
• OAuth token exchange and revocation attempts are logged without storing client secrets, authorization codes, access tokens, or refresh tokens.
• Known API key ids on failed `/v1/tokens` exchanges are scoped to their owning app for portal debugging.
• Sensitive query-string and metadata values are bounded and redacted before request logs are stored, including malformed query strings that cannot be decoded safely.
• Portal audit metadata is also redacted and bounded before storage so secret, token, password, and digest values are not displayed in control-plane history.
• UpHex also forwards `X-UpHex-Edge-Request-ID` to owning services for internal tracing and a bounded public caller id to CMS for draft-template audit attribution.
• Custom downstream headers are limited to valid HTTP token names and bounded values without CR/LF or NUL bytes.

Support handoff

External developer support starts from the API edge request log, not raw backend or CMS internals.

• Send UpHex the `X-Request-ID`, HTTP method, path, timestamp, app name, agency id, and the public error body.
• Use `/portal/requests` to find matching requests, including pasted smoke request-id lists, and confirm auth mode, resolved agency, downstream service, rate-limit state, idempotency state, and webhook enqueue state.
• Do not send API secrets, OAuth client secrets, access tokens, refresh tokens, webhook signing secrets, or provider tokens in support messages.
• UpHex can trace the edge request and downstream delegation from request ids while backend, CMS, and connector keep ownership of their domain data.

Credential lifecycle

The developer portal owns credential operations so external developers do not need direct access to backend services.

• API key secrets, OAuth client secrets, and webhook signing secrets are shown once and stored only as digests.
• API keys can have expiration dates and can be rotated while keeping the same public key id.
• OAuth/MCP client secrets can be rotated while keeping the same public client id.
• Webhook signing secrets can be rotated while keeping endpoint history and delivery records.
• Revoking an API key, OAuth/MCP client, or OAuth token session stops future edge authentication without deleting audit history.
• Credential create, rotate, revoke, token-session revoke, and successful portal sign-in actions are recorded in portal audit logs.

Preview handoff

Preview bundles are generated by the API edge so external developers receive only edge-owned access.

• `mix uphex_api.preview_sandbox` creates or reuses a developer account, owner user, and sandbox app for a known agency.
• `UPHEX_API_PREVIEW_PASSWORD` must be explicitly set, must be 12-128 bytes, and cannot use the placeholder from `.env.example`.
• `UPHEX_API_PREVIEW_BASE_URL` must be an absolute `http` or `https` origin; userinfo, paths, query strings, and fragments are rejected.
• Existing preview users are reactivated as owners and updated to the configured preview password so the printed portal sign-in details work.
• `UPHEX_API_PREVIEW_SCOPES` can narrow the generated API key and OAuth/MCP client to the least-privilege scopes needed by the preview.
• Generated API secrets and OAuth client secrets are printed once, stored only as digests, and should be shared through a secure channel.
• The handoff output includes portal sign-in details, docs, OpenAPI, request-log URLs, support contact, agency id, and granted scopes.
• A ready-to-run `scripts/smoke-preview.sh` command is printed only when the generated credentials include the scopes exercised by the smoke script.

Edge stop controls

UpHex can stop developer traffic at the API edge without deleting downstream-owned campaign, lead, metric, or provider-token data.

• Public sign-up can store a bounded requested agency id for review without granting access.
• Portal app allow-list agency ids are bounded before parsing and must already be granted to the developer account.
• Suspending a developer account stops portal sessions, API keys, OAuth clients, issued OAuth access tokens, and pending webhook deliveries from authenticating or sending.
• Paused, suspended, and archived apps are shown as traffic-blocked in the portal.
• Blocked apps keep credentials, OAuth clients, webhooks, request logs, and audit history visible for review.
• When an app is blocked, public API and MCP requests are rejected at the edge and are not forwarded to backend or CMS.

MCP gateway

`POST /mcp` accepts Streamable HTTP JSON-RPC requests and proxies them to CMS-owned MCP tool execution.

• Requests require `mcp:read`, `mcp:write`, or legacy `mcp:tools`. The agency comes from `X-Agency-Id`, an OAuth token's bound agency, or the app's single default agency, using the same rules as the REST routes.
• `mcp:read` exposes read tools such as `template_search`, `template_details`, and `campaign_details` with `view=funnel`.
• `mcp:write` is explicit write MCP access and is forwarded to CMS as read plus write tool intent so write-capable integrations can still discover and call read helpers.
• With `mcp:write`, external callers can use only draft-template write tools such as `template_create`, `template_create_direct`, `template_update` by `section`, `template_add_image`, and `template_delete`.
• External MCP write tools are draft-only: they can create, update, upload images to, and soft-delete API-created drafts, but they cannot mutate launched/non-draft templates.
• Launch/provider mutation tools such as `campaign_launch` and `launch_template_as_adset` are not exposed on the external public API MCP write surface.
• Legacy `mcp:tools` is preserved as deliberate full MCP tool access (`mcp:read` plus `mcp:write`) for backwards compatibility.
• The API edge derives CMS MCP scope intent only from the authenticated API credential or OAuth access token; client-supplied internal scope headers are ignored.
• `Mcp-Protocol-Version`, when provided, must be one of `2024-11-05`, `2025-03-26`, or `2025-06-18`.
• `X-Agency-Id` and `Mcp-Protocol-Version` must each be sent at most once.
• Each request is one JSON-RPC object (batches are rejected). Ids are limited to strings up to 128 bytes or JSON-safe integers; null ids are rejected. Method names are bounded to 128 bytes and cannot contain control characters. `params` must be an object when present.
• The developer app must be allowed to access the requested agency.
• Clients can discover OAuth and MCP metadata from `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`.
• Authorization-server discovery includes the developer documentation URL plus supported token and revocation client authentication methods.
• Gateway errors include `request_id`, and portal request logs show the resolved agency.
• CMS 5xx responses are normalized into stable `502` gateway errors instead of exposing raw CMS bodies.
• The gateway is stateless: `Mcp-Session-Id` is neither issued nor forwarded from CMS.
• `GET /mcp` and `DELETE /mcp` return `405` because the edge is stateless.

Idempotency

`POST /v1/leads`, `POST /v1/leads/{id}/notes`, `POST /v1/leads/{id}/activities`, `POST /v1/templates`, and `POST /v1/templates/{id}/images` support `Idempotency-Key` for API key, legacy bearer-token, and OAuth access token requests so integrations can retry safely after network failures.

• Use a unique key per logical write and reuse it only when retrying that same write.
• Keys are kept for 24 hours; after that the same key starts a fresh request. API-key requests scope keys to the API key that sent them; OAuth access token requests scope them to the OAuth client and the token's agency, so refreshed or rotated tokens of the same client share keys while other apps, clients, and agencies never see them.
• Responses with status 200-499 are stored and replayed with `X-Idempotent-Replay: true`; 5xx responses release the key so a retry runs again.
• Requests that fail body or scope validation are rejected before a key is claimed.
• Agency errors (`X-Agency-Id` `400` or `403`) are returned before a key is claimed, and the resolved agency is part of the request fingerprint.
• A repeated key while the first request is still running returns `409` (`idempotency_key_processing`).
• Keys are capped at 255 characters and may contain letters, numbers, dots, underscores, colons, or hyphens.
• A repeated key with the same payload replays the original public response.
• A repeated key with a different payload returns `409`.
• Template update and delete requests do not replay from idempotency storage; read the template or request log before retrying those operations.
• Expired idempotency records are released before a fresh matching request is claimed.
• Oversized public responses are not stored for replay; the key is released so a retry can re-run instead of staying stuck as processing.
• `POST /v1/leads/{id}/messages` is different: `Idempotency-Key` is required for API keys and OAuth tokens, is held by crm-service rather than the edge key store, and replays the first send's outcome (see Conversations & messages).

Webhooks

Active matching webhook endpoints receive developer-facing events that this API edge can safely derive from accepted public writes.

• `lead.created` is sent by UpHex's CRM once per created lead, whatever created it (`POST /v1/leads`, forms, ads, or the UpHex app). A `POST /v1/leads` that matches an existing lead sends nothing.
• Endpoints are managed per developer app in the portal and subscribe to one or more supported events. The signing secret (`whsec_...`) is shown once and can be rotated.
• Each delivery is a JSON `POST` of `{"event", "data"}` with `UpHex-Event`, `UpHex-Delivery-Id`, `UpHex-Signature-Timestamp`, and `UpHex-Signature: v1=<hex>` headers.
• Signature: HMAC-SHA256 over `<timestamp>.<raw body>`, keyed with the lowercase hex SHA-256 digest of the signing secret, hex-encoded lowercase.
• Any `2xx` response within 10 seconds marks the delivery delivered. Other statuses, connection errors, and timeouts are retried automatically, for at most 5 attempts, with backoff of 17s, 19s, 23s, and 31s after successive failures; the portal shows the same next-retry time.
• Each attempt is re-signed with a fresh timestamp but keeps the same `UpHex-Delivery-Id`. Delivery is at-least-once and unordered, so de-duplicate on that id.
• Deliveries are cancelled without retry when the endpoint is disabled, the app or developer account is inactive, or the URL fails the safety check. Failed deliveries can be retried from the portal; each manual retry starts a new run of up to 5 attempts.
• Webhook endpoints may subscribe only to supported public events: `lead.created`, `lead.updated`, `lead.tag_added`, `lead.tag_removed`, `message.inbound`, `message.outbound.status`, `appointment.created`, `appointment.rescheduled`, `appointment.canceled`, and `app.uninstalled`.
• CRM events (`lead.*` from the CRM, `message.*`, `appointment.*`) are delivered for an agency only to endpoints that list the event explicitly, owned by apps authorized for that agency whose scopes cover the event: `leads:read` for `lead.*`, `conversations:read` for `message.*`, and `calendars:read` for `appointment.*`. Partner apps need an active installation for the agency whose granted scopes cover the event; other apps need the agency on the developer account or an operator agency installation plus an active API key or OAuth client holding the scope. An endpoint with no events selected keeps receiving only app-targeted events.
• CRM event `data` is `{event_id, type, agency_id, client_id, occurred_at, data}`. `event_id` is a UUID that is stable for the source change even across separate deliveries; de-duplicate business effects on it.
• `message.inbound` carries `data.channel` (`sms`, `email`, or `custom`); `message.outbound.status` carries `data.status` (`delivered` or `failed`). Lead events carry `data.lead_id` and the lead under `data.lead`.
• `app.uninstalled` is delivered only to the app an agency removed (when the agency revokes the installation), with `data.app_id` and `data.installation_id`.
• Webhook event subscriptions are bounded before storage and unsupported event errors are truncated for portal display.
• Webhook delivery records reject unsupported event names and bound stored receiver response status/body data for portal review.
• Webhook endpoint URLs must use public HTTPS hosts without userinfo or fragments; localhost, private network targets, unresolved hosts, and private DNS answers are rejected.
• Webhook delivery timeouts are bounded and fall back to the safe default when misconfigured.
• Webhook payloads use the normalized public response data plus request id and agency metadata.
• Lead storage and all lead domain behavior are owned by UpHex's CRM; the API edge does not emit lead events itself.

Browser origins

Browser-based integrations can call `/v1`, `/oauth`, and `/mcp` endpoints only from configured CORS origins.

• Set `CORS_ALLOWED_ORIGINS` to a comma-separated origin list.
• App connection details repeat this requirement so browser integration failures start from the API edge configuration.
• CORS preflights are accepted only for documented public methods and headers.
• CORS origins and requested preflight headers must be single-valued and bounded.
• Allowed browser responses expose request id, rate limit, MCP session id, and idempotency replay headers.
• Portal session pages are not opened for arbitrary cross-origin browser calls.

Response envelope

Successful downstream responses are normalized before developers see them. Safe pagination and date metadata are preserved.

{
  "data": [],
  "meta": {
    "resource": "leads",
    "page": 1,
    "per_page": 25,
    "total_entries": 80,
    "total_pages": 2
  }
}

Error envelope

API-edge validation and policy failures use field-keyed arrays. Downstream errors are converted into a stable list with code, title, detail, and source.

{
  "errors": {
    "base": ["X-Agency-Id must be a positive integer"]
  }
}

{
  "errors": [
    {
      "code": "downstream_rejected",
      "title": "Downstream request rejected",
      "detail": "client_id is required",
      "source": "backend"
    }
  ]
}

Webhook signatures

Webhook deliveries are signed with HMAC-SHA256 over the timestamp and raw JSON body, keyed with the hex SHA-256 digest of your signing secret.

UpHex-Event: lead.created
UpHex-Delivery-Id: <stable id across retries>
UpHex-Signature-Timestamp: <unix seconds>
UpHex-Signature: v1=<hex(hmac_sha256(hex(sha256(secret)), timestamp + "." + body))>