---
title: "Create connections for a set of domains in one call"
method: POST
path: "/connections:bulk"
tags: ["Connections"]
---

# Create connections for a set of domains in one call

`POST /connections:bulk`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/connections:bulk`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

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.

`end_user_ref` labels every connection the call creates, 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 the label. It is set once, when the connection is created. A domain that already exists keeps the label 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.

## Request body

- object: The body is decoded with unknown fields REJECTED, so the properties below are exactly the accepted set.
  - `domains` string[], required
  - `batch_id` string: correlates every domain connected in one session.
  - `end_user_ref` string: Your own label for these domains, such as a client's name or your id for the customer they belong to. Stored on each connection this call creates and echoed back by the connection reads.
  - `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 `200`

Per-domain results

- object
  - `results` BulkResult[]
    - `domain` string, required
    - `connection_id` string
    - `status` 'connected' | 'already' | 'failed', required
    - `message` string

## Other responses

- `400`: Error envelope: {code, title, details}.
- `401`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)