---
title: "Add a custom domain."
method: POST
path: "/v1/domains"
tags: ["Domains"]
---

# Add a custom domain.

`POST /v1/domains`

## Request

- Base URL: `https://api.scalix.world`
- URL: `https://api.scalix.world/v1/domains`
- Auth: HTTP bearer

Registers a custom domain for the caller's project and returns the created
record plus the DNS records (CNAME + TXT) needed to verify and serve it.

## Request body

- AddDomainBody: Request body for `POST /v1/domains` — the custom domain to register.
  - `domain` string, required: Fully-qualified domain to attach, e.g. `app.example.com`.
  - `run_service` string, nullable: Optional Scalix Run service (by name) this domain should serve. When set, requests to the domain are proxied to the service exactly like `{name}.run.scalix.world`; when omitted, the domain serves the project's API surface. The service must belong to the caller's project.
  - `storage_bucket` string, nullable
  - `function_name` string, nullable: Optional Function (by globally-unique name) this domain serves. Requests to the domain invoke the function's HTTP handler exactly like `{name}.fn.scalix.world`. Mutually exclusive with the other targets.

## Response `201`

Domain registered; returns DNS setup instructions

- AddDomainResponse: Response for `POST /v1/domains` — the created domain plus DNS setup steps.
  - `domain` DomainJson, required: A custom domain attached to a project, with verification + SSL state.
    - `id` string, required
    - `project_id` string, required
    - `domain` string, required
    - `domain_type` string, required
    - `status` string, required
    - `verification_token` string, required
    - `ssl_status` string, required
    - `ssl_expires_at` string, required
    - `ssl_issued_at` string, required
    - `ssl_error` string, nullable: Last cert-issuance failure reason (absent = none). Lets the console show "DNS doesn't point to our edge" instead of a silent stuck 'none'/'failed'.
    - `primary_domain` boolean, required
    - `created_at` string, required
    - `updated_at` string, required
    - `cname_target` string, nullable
    - `run_service` string, nullable: Run service this domain serves (absent = the project's API surface).
    - `storage_bucket` string, nullable
    - `function_name` string, nullable: Function this domain serves (absent = not a function target).
    - `edge_ip` string, nullable: Gateway IP for apex A-record setup (absent if not configured).
  - `instructions` DomainInstructions, required: DNS setup steps returned when a domain is added.
    - `step_1` string, required
    - `step_2` string, required
    - `step_3` string, required
    - `step_4` string, required

## Other responses

- `400`: Invalid or platform-reserved domain
- `401`: Missing or invalid credentials
- `409`: Domain already registered
- `500`: Internal error

---

[API](https://skmtc.dev/scalix/apis/scalix-cloud-api.md) · [All operations](https://skmtc.dev/scalix/apis/scalix-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalix/apis/scalix-cloud-api/revisions/2c04ca0a90bb?raw)