---
title: "Add a custom domain"
method: POST
path: "/v1/apps/{app_id}/domains"
tags: ["Apps"]
---

# Add a custom domain

`POST /v1/apps/{app_id}/domains`

Attach a custom domain to an App.

Returns a `verification_token` and `cname_target`. To prove ownership,
add a DNS TXT record:

    _mixpeek-verify.{domain}  TXT  "mixpeek-site-verification={verification_token}"

Then call `POST /{app_id}/domains/{domain}/verify` to start polling.

## Path parameters

- `app_id` string, required — App ID (e.g. app_abc123def456)

## Request body

- AddDomainRequest
  - `domain` string, required — Customer domain (e.g. 'search.acme.com')
  - `is_primary` boolean — Set as primary domain

## Response `200`

The newly added domain configuration

- DomainResponse
  - `domain` string, required
  - `status` string, required
  - `verification_token` string, nullable
  - `cname_target` string, nullable
  - `is_primary` boolean, required
  - `verified_at` string, nullable

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

## Changes

- **2026-08-09** `5d4c905106b4` — 1 info
  - the endpoint scheme security `BearerAuth` was added to the API

[Change history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/apps/:app_id/domains/post.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/5cb0d3a12d0a?raw)