CustomDomain Connect API
The Connect API from CustomDomain — 1 operation(s) for connect.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/customdomain-ai:customdomain-ai-connect-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Customdomain Ai Connect API
version: '1.0'
license:
name: Apache-2.0
identifier: Apache-2.0
description: 'Operations tagged Connect across 2 of this provider''s published API definitions: customdomain-ai-openapi-original.json, customdomain-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.customdomain.ai/v1
description: Hosted control-plane
- url: http://localhost:8080/v1
description: Local control-plane
security:
- apiKey: []
tags:
- name: Connect
paths:
/telemetry:connect:
post:
operationId: recordConnectTelemetry
summary: Widget funnel beacon (fire-and-forget)
tags:
- Connect
description: 'A PII-free beacon recording which step of the in-modal connect flow a user reached. It exists because server-side counters only observe connections that actually get created, and so are blind to pre-connection drop-off.
`step` and `outcome` are allow-listed server-side and anything unrecognised is folded into a fixed label. A beacon that carries a `session_id` is also stored against the calling application, which is what `GET /analytics/connect` reads; one without it is only counted. No domain is stored, and nothing the end user typed. With each stored beacon the control plane keeps the end user''s IP address and country (from the request, believed only through Cloudflare), and the session it belongs to: at its first beacon the address, the region and city Cloudflare derived, and the device type, operating system and browser parsed from the User-Agent (the string itself is not stored); at every beacon the step, rail, provider and outcome. Addresses are kept for as long as the account exists, unless the deployment''s `IP_RETENTION_DAYS` sets a window. It **always** answers `204`, including for an invalid token or a malformed body, so telemetry can never block or error the widget; do not branch on its response.'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
step:
type: string
description: Funnel step label (server-side allow-list).
outcome:
type: string
description: Outcome label (server-side allow-list).
session_id:
type: string
description: Random id per widget open, 8 to 64 of [A-Za-z0-9_-].
provider:
type: string
description: Detected DNS provider id.
rail:
type: string
enum:
- oauth
- domain_connect
- manual
- api_key
- managed_dns
- cloud_browser
domain_kind:
type: string
enum:
- apex
- subdomain
error_code:
type: string
description: Widget error code, [A-Za-z0-9_] up to 48.
connection_id:
type: string
elapsed_ms:
type: integer
description: Milliseconds since the widget opened (capped at a day).
client:
type: object
description: Optional. What the widget reports about its surroundings, recorded on the session while the session has no value for it yet. Every field is optional, and a value outside its range or alphabet is dropped; unlike the beacon's own fields an unknown field here is ignored, and an object larger than 2 KiB is ignored whole.
additionalProperties: true
properties:
screen_width:
type: integer
minimum: 1
maximum: 20000
screen_height:
type: integer
minimum: 1
maximum: 20000
viewport_width:
type: integer
minimum: 1
maximum: 20000
viewport_height:
type: integer
minimum: 1
maximum: 20000
pixel_ratio:
type: number
minimum: 0.25
maximum: 10
touch:
type: boolean
description: The device has a touch screen.
language:
type: string
description: The browser's language (navigator.language), a BCP 47 tag.
locale:
type: string
description: The language the widget shows, a BCP 47 tag.
time_zone:
type: string
description: An IANA time zone, such as Europe/Berlin.
color_scheme:
type: string
enum:
- light
- dark
reduced_motion:
type: boolean
connection:
type: string
enum:
- slow-2g
- 2g
- 3g
- 4g
description: The Network Information API's effective type, where the browser has it.
widget_version:
type: string
sdk:
type: string
enum:
- script
- npm
- react
sdk_version:
type: string
embed:
type: string
enum:
- embedded
- modal
host_origin:
type: string
description: The page the widget is on. Only the scheme, host and port are kept.
referrer_origin:
type: string
description: The referrer of the widget's frame. Only the scheme, host and port are kept.
responses:
'204':
description: Always. Carries no body and reports no error by design.
servers:
- url: https://api.customdomain.ai/v1
description: Hosted control-plane
- url: http://localhost:8080/v1
description: Local control-plane
components:
securitySchemes:
managementKey:
type: http
scheme: bearer
description: Operator management key. Gates provisioning + reads across tenants.
provisionSecret:
type: apiKey
in: header
name: X-Provision-Secret
description: Narrow secret held by the customer console's server, for signup provisioning and its other server to server calls (also accepted as a Bearer token, except on POST /audit, where a Bearer is always a tenant credential).
apiKey:
type: http
scheme: bearer
description: Long-lived tenant API key, cd_live_… (production) or cd_test_… (staging, development), stored hashed. Keys created before the switch to cd_ start with sk_live_… / sk_test_… and are still accepted. Scoped to the owning application's tenant.
widgetJWT:
type: http
scheme: bearer
bearerFormat: JWT
description: Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain).
browserSession:
type: http
scheme: bearer
description: The session token of one cloud browser sign in, returned by `POST /browser-sessions:redeem`. It binds one session, one connection and one workspace, lives at most as long as the session, and stops working the moment the session ends. It lives in the popup's memory only.
agentToken:
type: oauth2
description: 'A delegated agent access token: an ES256 JWT that lives 15 minutes, sent as a bearer token. A person approves an agent in the console and the agent exchanges its authorization code (with PKCE) at the token endpoint. The token carries the workspace, the one application the grant is bound to, the grant, the approved scopes and its audience, and is verified against `/.well-known/jwks.json`. A route that accepts it lists the scope it needs; a token without the scope is refused with `403`, and a connection or order of another application answers `404`.'
flows:
authorizationCode:
authorizationUrl: https://api.customdomain.ai/oauth/agent/authorize
tokenUrl: https://api.customdomain.ai/oauth/agent/token
refreshUrl: https://api.customdomain.ai/oauth/agent/token
scopes:
domains:read: Look at availability, connections, records, certificates, diagnoses, orders and the billing standing.
domains:connect: Connect a domain, recheck it, reapply its records and start a one click setup.
domains:disconnect: Remove a connected domain. The call must name the domain.
domains:purchase: Buy a domain, up to the grant's monthly spend cap.
x-refined-from:
- customdomain-ai-openapi-original.json
- customdomain-ai-openapi.yml