#Partner Integrations

Identity, API-key lifecycle, webhook registration, model/voice catalogs, and capacity monitoring for approved partner integrations.

• Production API: https://api.aidial.ai
• Version prefix: /v1

Use X-API-Key for server-to-server requests unless AiDial has explicitly provisioned a portal bearer flow for your integration. Send only one credential per request: if both X-API-Key and Authorization: Bearer are present, the API key is used and the bearer token is ignored.

#Partner Identity

#GET /v1/partner/me

Returns the authenticated partner context: client_id, scope, data_env, and auth_type. When authenticated with X-API-Key, the response also includes the key's api_key_id, api_key_description, and expires_at.

Requires a partner_admin or partner_user scope; other scopes receive a non-enumerating 404.

#API Keys

API-key responses return safe metadata only, except create and rotate responses which reveal the generated secret once. Store that secret immediately; it cannot be retrieved later.

Create, rotate, and revoke are mutations and require an Idempotency-Key header. A new API key's scope must be partner_admin or partner_user. API-key lifecycle mutations require a portal bearer session with a partner_admin scope; X-API-Key callers can list keys but cannot create, rotate, or revoke them.

Bearer callers must name the target tenant with a client_id query parameter on every API-key route; an omitted client_id, or one the caller is not assigned to, returns a non-enumerating 404. X-API-Key callers may omit client_id, and when they supply it, it must match the key's own client. Keys are additionally scoped to the caller's data_env, so a key is only listed, rotated, or revoked in the environment it was issued for.

Create and rotate are rate limited to 5 requests per minute, counted separately per operation, caller identity, tenant, and environment.

#Webhooks

Webhook configuration routes are project scoped and require a project_id (supplied as a query parameter, or in the body on create); on GET /v1/partner/webhooks/deliveries, project_id is an optional filter. Mutating requests require the current revision guard: create and update accept it in the revision_hash body field or the If-Match header, while delete, rotate-secret, and test read it from If-Match only. A mismatch returns 409, and a missing guard returns 428. Creating a webhook also requires an Idempotency-Key header. Generated signing secrets are returned only when created or rotated. Webhook mutations require a partner_admin scope; partner_user may list webhooks and delivery history but not mutate.

Endpoint configuration is validated on create and update:

• endpoint_url must be an https URL with no embedded credentials that resolves to a public address; loopback, link-local, and private ranges are rejected.
• event_types accepts call_started, call_ended, call_analyzed, and transfer_initiated, and must contain at least one value.
• transcript_to_send accepts none, redacted, or original. original is accepted only when the tenant has approved transcript access; otherwise the request fails validation.
• timeout_seconds is 1–30, retry_attempts is 0–5, and retry_backoff_seconds is 5–300.

Create, rotate-secret, and test are each rate limited to 5 requests per minute, counted separately per operation, caller identity, and tenant.

Runtime and test deliveries include canonical signing headers such as X-AiDial-Delivery-Id, X-AiDial-Event, X-AiDial-Timestamp, X-AiDial-Endpoint-Id, and X-AiDial-Signature. The signature header carries t=<timestamp>,d=<delivery_id>,e=<event>,v1=<hmac_sha256_hex>, and a legacy body-only X-Webhook-Signature-256 header is sent alongside it. Test deliveries are sent with redirects disabled, so a 3xx response is recorded as a blocked redirect instead of being followed.

Delivery history never returns raw payloads, transcripts, response bodies, signing secrets, bearer tokens, API keys, or ciphertext. It covers the most recent 30 days, and each response reports that window alongside the delivery records.

#Catalogs

Catalog routes are read-only and return the current platform catalog. The response is the same for every authorised caller; it is not filtered per partner or per tenant.

#Capacity

Capacity routes return safe availability and history summaries for authorised partner and operator callers. Partners see only their assigned clients (no platform summary).

GET /v1/capacity/history requires a range query parameter of 24h, 7d, or 30d. On GET /v1/capacity/overview, page_size must be 10, 25, or 50, and partners cannot request the platform view (scope=platform returns a non-enumerating 404).

#Errors