---
topic: custom-domain
connector: "update_app · register_domain / verify_domain; app_danger_zone · delete_domain; read_app · domains"
api: "https://ship.embarko.ai/api/apps/{app-name}/domains"
needs_human: Adding one DNS record wherever their domain is managed.
requires: [claim]
---

[← Guide home](https://embarko.ai/docs)

# Own domain

**On this page:** With the connector, Over HTTP, In the dashboard, Limits, Errors, What to tell the person

> Plain words unless the person is a developer. Never invent a link, name or code. [Rules](https://embarko.ai/docs/prerequisites) Needs first: [claim](https://embarko.ai/docs/claim) (over HTTP only).

Point a domain or subdomain at the app. HTTPS is set up automatically once DNS is in place.

**Connector:** update_app · register_domain / verify_domain; app_danger_zone · delete_domain; read_app · domains

**Done when:** https://{their domain} opens the app.

**With the connector**

1. Call update_app { action: "register_domain", appName, domain }. The reply's instructions field is the DNS record.
2. Give the person that one record in plain words (type, name, value) and where it goes ("your domain provider's DNS settings").
3. When they say it is done, call update_app { action: "verify_domain", appName, domain }. A 422 means DNS has not reached Embarko yet: try again in a few minutes.

**Over HTTP**

1. POST https://ship.embarko.ai/api/apps/{app-name}/domains with the token and the body {domain}. The reply's instructions field is the one DNS record the person must add.
2. Once the record is added: POST https://ship.embarko.ai/api/apps/{app-name}/domains/{domain}/verify. Safe to repeat.

**In the dashboard**

1. For any app in the person's account, including one they uploaded in the dashboard, and when you cannot reach the API: they do it themselves in the dashboard.
2. Tell them: open https://embarko.ai/app, choose the app, open the Domain tab, and enter the domain.
3. The page shows the one DNS record to add at their domain provider. After adding it they press Verify; if DNS is not ready yet, they wait a few minutes and press it again. It works the same as the API route above.

**Limits**

- A root domain gets an A record, a subdomain a CNAME.
- One domain belongs to one app.

**Errors**

| Code | Status | Retry | What to do |
| --- | --- | --- | --- |
| `domain_taken` | 409 | No | Another app has it. |
| `domain_reserved` | 400 | No | An Embarko address (*.embarko.app) cannot be registered. |
| `invalid_domain` | 400 | No | Not a valid domain name. |
| `(DNS not ready)` | 422 | Later | On verify: wait a few minutes and verify again. |

**What to tell the person**

- ask_dns: "To use {domain}, add this one record in your domain provider's DNS settings: {type} {name} → {value}. Tell me when it's done."
- done: "{domain} now opens your app."

**Next:** Register the domain, give the person the DNS record, verify when they are done.

**Related:** [resume](https://embarko.ai/docs/resume) · [rename](https://embarko.ai/docs/rename)

---

[Guide home](https://embarko.ai/docs) · JSON: add .json