Create connections for a set of domains in one call

Create connections for a set of domains in one call: CustomDomain™ API reference in the connections group. Covers parameters, request body and responses.

Fans out the same idempotent upsert as single-domain create. Each domain is independent: a bad domain is reported failed and the batch continues; a domain already connected under this app returns already. Max 200 domains per call.

Callable with an app scoped widget token or straight from your server with an API key, in which case the connections are created on the key's application, or on application_id when that names another application of the same tenant. A viewer's key is refused.

client_label names the client every connection the call creates is for, the way it does on a single create: an agency adds a client's domains together under the client's name, and the Domains page shows, filters and exports it. PATCH /connections/{id} changes it later. end_user_ref is your own id for the end user, set once and never changed. A domain that already exists keeps what it has and is reported already.

A workspace with no subscription yet connects its first ten domains, or the number an operator set, without one; the rest of a list are reported failed with the reason, one by one, until it starts its trial.

Authorization

AuthorizationBearer <token>

Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The body is decoded with unknown fields REJECTED, so the properties below are exactly the accepted set.

domains*array<string>

Itemsitems <= 200

batch_id?string

correlates every domain connected in one session.

end_user_ref?string

Your own id for the customer these domains belong to. Stored on each connection this call creates and echoed back by the connection reads. Set once; it binds widget tokens to the connection, so it is not a name (send client_label).

Lengthlength <= 256

client_label?string

The name of the client these domains are for, such as an agency's client. Trimmed to one line, at most 200 characters, with characters that draw nothing dropped; a name with nothing left stores no name. Stored on each connection this call creates; PATCH /connections/{id} changes it later.

Lengthlength <= 200

application_id?string

API key callers only: create the connections on this application of the key's tenant instead of the key's own. A widget token may only name its own application.

Response Body

`application/json`

curl -X POST "https://example.com/connections:bulk" \  -H "Content-Type: application/json" \  -d '{    "domains": [      "string"    ]  }'

{  "results": [    {      "domain": "string",      "connection_id": "string",      "status": "connected",      "message": "string"    }  ]}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

Create connections for a set of domains in one call

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`