List connections
List connections: reference page for this CustomDomain™ API operation in the connections group. Covers parameters, request body, responses and error codes.
With an API key: every connection across the tenant's applications (optional ?app_id= and ?status= filters). With an app-scoped widget JWT or a delegated agent token: the calling application's connections (app_id is ignored; the scope is fixed to that application). A connect-scoped widget JWT (an end user's) is refused with 403.
The response is paginated and always bounded. limit defaults to 500 and is clamped to 1000; next_cursor is present only when more rows remain. To read every connection, follow next_cursor until it is absent. Counting rows client-side is not required; see GET /connections:count.
A status outside the enum is rejected with 400 (it used to reach the database and surface as a 500).
Every row carries dns_hosting: who runs the domain's DNS. To find the domains CustomDomain™ runs the DNS for, ask for ?dns_hosting=hosted; the filter is applied in the database, so a page is full and next_cursor keeps walking the matching rows. A dns_hosting outside the enum is rejected with 400. Test mode connections never match it.
A delegated agent token needs domains:read. It reads no end_user_ref, the platform's id for its end user, on any row (an API key reads it).
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.
In: header
Query Parameters
Value in
- "pending"
- "propagating"
- "live"
- "failed"
Keep only the connections by who runs their DNS. hosted: the nameservers point at a zone we run, so the domain's DNS is served from it. moving: the zone is being set up or the nameservers are being moved. any: every domain with DNS hosting in play (hosted, moving or failed). Omit for all connections.
Value in
- "hosted"
- "moving"
- "any"
Rows per page. Defaults to 500; values above 1000 are clamped to 1000.
1 <= value <= 1000500Opaque keyset cursor taken verbatim from a previous response's next_cursor. Omit for the first page.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/connections"{ "connections": [ { "id": "string", "application_id": "string", "domain": "string", "host": "string", "provider_id": "string", "setup_type": "automatic", "status": "pending", "managed": true, "created_at": "2019-08-24T14:15:22Z", "sandbox": true, "last_checked_at": "2019-08-24T14:15:22Z", "www_redirect": true, "override_spf": true, "validate_dmarc": true, "validate_caa": true, "monitor": true, "batch_id": "string", "end_user_ref": "string", "client_label": "string", "retried_at": "2019-08-24T14:15:22Z", "routing": { "mode": "edge", "cname_target": "string", "apex_ipv4": [ "string" ], "set_at": "2019-08-24T14:15:22Z" }, "records_source": "integrator", "created_via": "", "secure_root_domain": true, "redirect_to": "http://example.com", "power_root_path_access": [ "string" ], "error_code": "string", "error_message": "string", "write_rail": "api_key", "provider_account_id": "string", "removal_started_at": "2019-08-24T14:15:22Z", "dns_hosting": { "state": "none", "by": "customdomain", "provider": "string", "zone": "string", "since": "2019-08-24T14:15:22Z" } } ], "count": 0, "next_cursor": "string"}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}