Create a connection

curl -X POST http://localhost:8080/v1/connections \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Idempotency-Key: <UUID>" \
  -H "Content-Type: application/json" \
  -d '{"application_id":"<APP_ID>","hostname":"app.customer.com"}'

Request fields (see the API reference for the full schema):

• application_id, hostname — required.
• setup_type — override the detected setup type (automatic, manual, …).
• dns_records — override the application's record_template for this connection only.
• batch_id — group connections created together (e.g. a bulk import).

Send an Idempotency-Key header on creates to make retries safe.

Response

The response includes the connection id (also the jobId used by widget events and webhooks), its state, and — unless a delegated DNS credential auto-writes the records — an ownership_challenge:

{
  "id": "…",
  "state": "pending_ownership",
  "ownership_challenge": {
    "name": "_customdomain-challenge.app.customer.com",
    "type": "TXT",
    "value": "cd-verify-…"
  }
}

Errors

Next: verify ownership and go live.