> ## 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

**1. Open the Domains panel**

In the App details page, click the **Domains** tab.

**2. Enter your subdomain**

Type the subdomain you want to use (e.g. `search.yourcompany.com`) and click **Add Domain**.

**3. 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}` |

**4. 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` |

**5. 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.

***

## 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

```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"}'
```

***

## 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](https://docs.mixpeek.com/docs/canvas/apps.md)
* [Deployment guide](https://docs.mixpeek.com/docs/canvas/apps/deploy.md)
* [Add Domain (API)](https://docs.mixpeek.com/docs/api-reference/apps/add-domain.md)
* [List Domains (API)](https://docs.mixpeek.com/docs/api-reference/apps/list-domains.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.