---
title: "Attach custom domain"
method: POST
path: "/hosting/custom-domains"
tags: ["Hosting - Custom Domains"]
---

# Attach custom domain

`POST /hosting/custom-domains`

Attach a custom domain to an app or worker

## Request body

- union — Request body schema.
  - object
    - `kind` 'app', required
    - `appUuid` string, uuid, required — Identifier of the app this custom domain attaches to.
    - `hostname` string, required — Customer-controlled subdomain to attach (e.g. app.example.com). Must be a valid FQDN with at least three DNS labels, must not include a protocol or path, and must not be under a Cargo-owned domain. Normalised to lowercase.
  - object
    - `kind` 'worker', required
    - `workerUuid` string, uuid, required — Identifier of the worker this custom domain attaches to.
    - `hostname` string, required — Customer-controlled subdomain to attach (e.g. app.example.com). Must be a valid FQDN with at least three DNS labels, must not include a protocol or path, and must not be under a Cargo-owned domain. Normalised to lowercase.

## Response `200`

Successful response

- object
  - `customDomain` union, required — Newly attached custom domain.
    - object
      - `uuid` string, uuid, required
      - `workspaceUuid` string, uuid, required
      - `hostname` string, required
      - `status` 'pending_verification' | 'verifying' | 'active' | 'failed' | 'deactivated', required
      - `verifiedAt` string, nullable, required
      - `verification` object[], required
        - `recordType` 'CNAME' | 'TXT', required
        - `name` string, required
        - `value` string, required
      - `cnameTarget` string, nullable, required
      - `chargedUntil` string, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `kind` 'app', required
      - `appUuid` string, uuid, required
    - object
      - `uuid` string, uuid, required
      - `workspaceUuid` string, uuid, required
      - `hostname` string, required
      - `status` 'pending_verification' | 'verifying' | 'active' | 'failed' | 'deactivated', required
      - `verifiedAt` string, nullable, required
      - `verification` object[], required
        - `recordType` 'CNAME' | 'TXT', required
        - `name` string, required
        - `value` string, required
      - `cnameTarget` string, nullable, required
      - `chargedUntil` string, required
      - `createdAt` string, required
      - `updatedAt` string, required
      - `kind` 'worker', required
      - `workerUuid` string, uuid, required

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found
- `500` — Internal server error

---

[API](https://skmtc.net/getcargo/apis/cargo-api.md) · [All operations](https://skmtc.net/getcargo/apis/cargo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getcargo/cargo-api/revisions/1d5a19e01d83/schema)