> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouncy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Domain

> Connect a custom domain to your Bouncy.ai account

## Request

### Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body

<ParamField body="domain" type="string" required>
  The custom domain to connect (without protocol)

  **Example:** `go.example.com`
</ParamField>

<ParamField body="isDefault" type="boolean">
  Whether to make this your default domain for new links

  **Default:** `false`
</ParamField>

<Note>
  After connecting a domain, you must verify DNS records before it can be used. See the [Verify Domain](#) endpoint.
</Note>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the domain
</ResponseField>

<ResponseField name="domain" type="string">
  The connected domain name
</ResponseField>

<ResponseField name="verified" type="boolean">
  Whether the domain is verified (will be `false` initially)
</ResponseField>

<ResponseField name="isDefault" type="boolean">
  Whether this is your default domain
</ResponseField>

<ResponseField name="dnsRecords" type="object">
  DNS records that need to be configured

  <Expandable title="properties">
    <ResponseField name="type" type="string">
      Record type (e.g., "CNAME")
    </ResponseField>

    <ResponseField name="host" type="string">
      Host/Name for the DNS record
    </ResponseField>

    <ResponseField name="value" type="string">
      Value/Target for the DNS record
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of creation
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.bouncy.ai/v1/domains \
    -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "domain": "go.example.com",
      "isDefault": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.bouncy.ai/v1/domains', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      domain: 'go.example.com',
      isDefault: true
    })
  });

  const result = await response.json();
  console.log('Connected domain:', result.domain);
  console.log('DNS records to configure:', result.dnsRecords);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.bouncy.ai/v1/domains',
      headers={
          'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'domain': 'go.example.com',
          'isDefault': True
      }
  )

  result = response.json()
  print(f"Connected domain: {result['domain']}")
  print(f"DNS records: {result['dnsRecords']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "dom_abc123xyz",
    "domain": "go.example.com",
    "verified": false,
    "isDefault": true,
    "dnsRecords": {
      "type": "CNAME",
      "host": "go",
      "value": "cname.bouncy.ai"
    },
    "createdAt": "2026-02-06T12:00:00Z"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": {
      "code": "invalid_domain",
      "message": "Invalid domain format. Domain should not include protocol (http/https)",
      "field": "domain"
    }
  }
  ```

  ```json 409 Conflict theme={null}
  {
    "error": {
      "code": "domain_already_connected",
      "message": "This domain is already connected to your account or another account"
    }
  }
  ```
</ResponseExample>