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

# Custom Domains

> Point your own subdomain at a Mixpeek App. TLS is provisioned automatically.

## Overview

Every App gets a default URL at `{slug}.mxp.co`. You can also serve it on your own subdomain — for example, `search.yourcompany.com` — by adding a custom domain and creating a DNS CNAME record.

***

## Add a custom domain

<Steps>
  <Step title="Open the Domains panel">
    In the App details page, click the **Domains** tab.
  </Step>

  <Step title="Enter your subdomain">
    Type the subdomain you want to use (e.g. `search.yourcompany.com`) and click **Add Domain**.
  </Step>

  <Step title="Add a DNS TXT record for verification">
    Add a TXT record to prove domain ownership. The record name and value are returned in the API response:

    | Type | Name                                     | Value                                            |
    | ---- | ---------------------------------------- | ------------------------------------------------ |
    | TXT  | `_mixpeek-verify.search.yourcompany.com` | `mixpeek-site-verification={verification_token}` |
  </Step>

  <Step title="Create a CNAME record">
    In your DNS provider, add a `CNAME` record pointing your subdomain to the `cname_target` returned by the API:

    | Type  | Name                   | Value           |
    | ----- | ---------------------- | --------------- |
    | CNAME | search.yourcompany.com | `{slug}.mxp.co` |
  </Step>

  <Step title="Trigger verification">
    Call `POST /v1/apps/{app_id}/domains/{domain}/verify` to start DNS polling. Mixpeek polls every 30 minutes for up to 72 hours, then provisions a TLS certificate automatically via Cloudflare.

    Domain status changes to `active` once the certificate is issued.
  </Step>
</Steps>

***

## Domain statuses

| Status             | Meaning                                                     |
| ------------------ | ----------------------------------------------------------- |
| `pending`          | Domain added, waiting for DNS verification                  |
| `verifying`        | TXT record found, polling for CNAME propagation             |
| `provisioning_tls` | CNAME verified, issuing TLS certificate                     |
| `active`           | Domain is live and serving HTTPS                            |
| `failed`           | Verification failed after 72 hours — check your DNS records |

***

## Via API

<CodeGroup>
  ```python Python theme={null}
  from mixpeek import Mixpeek

  client = Mixpeek(api_key="your-api-key", namespace_id="ns_...")

  domain = client.apps.domains.add(
      app_id="app_...",
      domain="search.yourcompany.com",
  )
  print(domain.status)  # "pending"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.mixpeek.com/v1/apps/$APP_ID/domains \
    -H "Authorization: Bearer $API_KEY" \
    -H "X-Namespace: $NAMESPACE_ID" \
    -H "Content-Type: application/json" \
    -d '{"domain": "search.yourcompany.com"}'
  ```
</CodeGroup>

***

## Notes

* Only subdomain CNAMEs are supported (not apex/root domains).
* Each domain can be attached to one App at a time.
* Removing a domain does not affect the App's default `{slug}.mxp.co` URL.

***

## Related

* [Apps overview](/canvas/apps)
* [Deployment guide](/canvas/apps/deploy)
* [Add Domain (API)](/api-reference/apps/add-domain)
* [List Domains (API)](/api-reference/apps/list-domains)