# Domains

Add custom domains to a team, attach them to projects, check their DNS, and list a project's branch addresses.

Source: https://docs.orbits.africa/api/domains

A domain belongs to the team and points at one project (and optionally one branch, or a redirect). Add it, then point it at Orbits the way its `dns_mode` says: one record at your DNS provider, or Orbits DNS by changing the domain's nameservers. Orbits checks the records and issues the certificate itself. See [Custom domains](https://docs.orbits.africa/domains/custom-domains).

Endpoints:

- `GET /v1/teams/{team}/projects/{project}/branch-addresses`: A project's branch addresses
- `GET /v1/teams/{team}/domains`: The team's domains
- `POST /v1/teams/{team}/domains`: Add a domain
- `GET /v1/teams/{team}/domains/preview`: What adding a domain would do
- `GET /v1/teams/{team}/domains/{domain}`: A domain
- `PATCH /v1/teams/{team}/domains/{domain}`: Change what a domain serves
- `DELETE /v1/teams/{team}/domains/{domain}`: Remove a domain
- `POST /v1/teams/{team}/domains/{domain}/checks`: Look for the domain's DNS now

## The domain object



- `id` (string, required)
- `name` (string, required)
- `apex` (string, required): The registrable part.
- `host` (string, required): What precedes the apex; `@` for the apex itself.
- `dns` (string, required): `external`: the team keeps its DNS provider and adds one record. `orbits`: the team hands the domain's DNS to Orbits (an apex's nameservers at its registrar, or NS records for a subdomain at its parent's DNS). One of `external`, `orbits`.
- `state` (string, required): `pending`: its record isn't there yet. `valid`: DNS points at Orbits. `misconfigured`: a record is there but points elsewhere (`seen` says where). One of `pending`, `valid`, `misconfigured`.
- `project` (null or object, required): What it serves or redirects for; null is "Not in use".
  - `id` (string, required)
  - `slug` (string, required)
  - `name` (string, required)
- `branch` (string or null, required): The branch whose newest ready preview it serves; null for production.
- `redirect` (null or Redirect, required)
  - `to` (string, required): The hostname it sends visitors to, keeping the path.
  - `status` (integer, required): One of `301`, `308`.
- `required_record` (object or null, required): The one record an external domain needs at its DNS provider: an A record at an apex (a CNAME can't sit there), a CNAME below it. Null on Orbits DNS, which keeps the record itself.
  - `type` (string, required): One of `A`, `CNAME`.
  - `name` (string, required)
  - `value` (string, required)
- `seen` (string or null, required): What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.
- `nameservers` (object or null, required): An Orbits DNS zone's nameservers: for an apex, to set at its registrar; for a subdomain zone, to add as NS records for it at its parent's DNS. `pointing` once the zone is handed to them. Null for any other domain, including names inside a zone.
  - `names` (array of string, required)
  - `pointing` (boolean, required)
- `email` (string or null, required): The provider Email setup added records for, on an Orbits DNS zone. One of `zoho`, `google`, `microsoft`.
- `certificate` (object, required)
  - `state` (string, required): `none`: not needed yet (DNS not found, or the domain isn't in use). `pending`: DNS points here and the certificate is being issued; Orbits waits until public DNS answers for the name before asking Let's Encrypt. `failed`: the last try failed; it is tried again 5, 15, 30, then 60 minutes after each failure. One of `none`, `pending`, `active`, `failed`.
  - `issued_at` (string or null, required)
  - `expires_at` (string or null, required): It renews on its own about 30 days before.
- `checked_at` (string or null, required)
- `created_at` (string, required)
## A project's branch addresses

```http
GET /v1/teams/{team}/projects/{project}/branch-addresses
```

The branch rows on a project's Domains page ("Follows the branch"): one address per branch with a ready preview, serving that branch's newest ready preview. The address is `<project>-git-<branch>.theorbits.app` (`orders-git-feat-apple-pay.theorbits.app`), one label under the free addresses' domain so their certificate covers it; a long branch is shortened and given a short hash. Show `host` as it is rather than building it.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/branch-addresses" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "branch": "feat/apple-pay",
      "host": "orders-git-feat-apple-pay.theorbits.app",
      "url": "https://my-app.theorbits.app",
      "deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "deployed_at": "2026-11-10T09:30:00Z"
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## The team's domains

```http
GET /v1/teams/{team}/domains
```

The team's Domains and DNS page: every domain the team added, newest first, with the page's counts and the projects for its filter. A project's Domains page is this list with `project` set. Teams have a handful of domains, so the list isn't paged.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Query parameters:

- `q` (string): Part of a domain's name or its project's name. At most 253 characters.
- `state` (string): One of `pending`, `valid`, `misconfigured`.
- `dns` (string): One of `external`, `orbits`.
- `project` (string): A project's `id` or `slug`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/domains" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "as_of": "2026-11-10T09:30:00Z",
  "items": [
    {
      "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "name": "shop.shadyventures.ng",
      "apex": "shadyventures.ng",
      "host": "shop",
      "dns": "external",
      "state": "pending",
      "project": {
        "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "slug": "my-app",
        "name": "my-app"
      },
      "branch": null,
      "redirect": {
        "to": "to",
        "status": 301
      },
      "required_record": {
        "type": "A",
        "name": "shop",
        "value": "cname.theorbits.app"
      },
      "seen": "CNAME old-host.example.net",
      "nameservers": {
        "names": [
          "ns1.theorbits.app",
          "ns2.theorbits.app"
        ],
        "pointing": false
      },
      "email": "zoho",
      "certificate": {
        "state": "none",
        "issued_at": "2026-11-10T09:30:00Z",
        "expires_at": "2026-11-10T09:30:00Z"
      },
      "checked_at": "2026-11-10T09:30:00Z",
      "created_at": "2026-11-10T09:30:00Z"
    }
  ],
  "summary": {
    "total": 1,
    "apex": 1,
    "orbits": [
      "orbits"
    ],
    "pending": 1,
    "misconfigured": 1
  },
  "projects": [
    {
      "id": "id",
      "slug": "my-app",
      "name": "my-app"
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Add a domain

```http
POST /v1/teams/{team}/domains
```

The Add domain dialog, on the team's Domains and DNS page or a project's Domains page. The domain starts `pending`. With `dns: external`, show `required_record` for the team to add at its DNS provider. With `dns: orbits`, the domain becomes a zone of its own: show `nameservers.names` for the team to set at its registrar (an apex, `host: "@"`) or to add as NS records for that name at its parent's DNS (a subdomain such as `dns-test.example.com`); Orbits then serves the whole zone, keeps the records its projects need, and the team manages the rest (`.../records`). A name inside a zone the team already has on Orbits DNS is on Orbits DNS too, whatever `dns` says: its record is created for it. Zones never nest: a zone around one already on Orbits DNS is refused (422 `dns`), and so is one inside or around another team's (409 `domain`). Orbits looks for it every minute (and at once with `POST .../checks`), issues the certificate once it's found, then serves the project on it. The person who added it gets an email when it's live, and another if DNS still isn't there an hour later.

A domain the team already has that serves nothing (a zone moved to Orbits DNS before any project was picked) can be typed into a project's Add domain dialog like a new one: this call links it (200) instead of refusing it. `GET .../domains/preview` says beforehand what adding a name would do, for the dialog's note.

**Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.

Body:

- `domain` (string, required): As typed: a scheme, path or trailing dot comes off, and it is lowercased. At most 253 characters.
- `dns` (string): `external`: the team keeps its DNS provider and adds one record. `orbits`: the team hands the domain's DNS to Orbits (an apex's nameservers at its registrar, or NS records for a subdomain at its parent's DNS). One of `external`, `orbits`.
- `project` (string or null): A project's `id` or `slug`.
- `branch` (string or null): Serve this branch's newest ready preview instead of production. Needs `project`. At most 128 characters.
- `to` (string or null): Redirect every request (308, same path) to this hostname instead of serving. At most 253 characters.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/domains" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "shop.shadyventures.ng"
  }'
```

Response `200`:

```json
{
  "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "name": "shop.shadyventures.ng",
  "apex": "shadyventures.ng",
  "host": "shop",
  "dns": "external",
  "state": "pending",
  "project": {
    "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "branch": null,
  "redirect": {
    "to": "to",
    "status": 301
  },
  "required_record": {
    "type": "A",
    "name": "shop",
    "value": "cname.theorbits.app"
  },
  "seen": "CNAME old-host.example.net",
  "nameservers": {
    "names": [
      "ns1.theorbits.app",
      "ns2.theorbits.app"
    ],
    "pointing": false
  },
  "email": "zoho",
  "certificate": {
    "state": "none",
    "issued_at": "2026-11-10T09:30:00Z",
    "expires_at": "2026-11-10T09:30:00Z"
  },
  "checked_at": "2026-11-10T09:30:00Z",
  "created_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: This team already has the domain and it serves something already, or the request names nothing for it to serve; or another team has it (`errors[0].field` is `domain`).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## What adding a domain would do

```http
GET /v1/teams/{team}/domains/preview
```

The Add domain dialogs' note, as the person types: whether the name would use outside DNS (one record to add, `required_record`), sit inside one of the team's Orbits DNS zones (`zone`, Orbits adds the record), or become a zone of its own (`nameservers`); and whether the team has it already (`existing`, which Add links to the project when it serves nothing). Nothing is saved. Checks the same rules as Add, with the same errors.

**Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Query parameters:

- `domain` (string, required): At most 253 characters.
- `dns` (string): One of `external`, `orbits`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/domains/preview?domain=domain" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "domain": "pay.shadyventures.ng",
  "apex": "apex",
  "host": "pay",
  "dns": "external",
  "zone": "shadyventures.com",
  "required_record": {
    "type": "A",
    "name": "my-app",
    "value": "value"
  },
  "nameservers": [
    "nameservers"
  ],
  "existing": {
    "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "name": "shop.shadyventures.ng",
    "apex": "shadyventures.ng",
    "host": "shop",
    "dns": "external",
    "state": "pending",
    "project": {
      "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "slug": "my-app",
      "name": "my-app"
    },
    "branch": null,
    "redirect": {
      "to": "to",
      "status": 301
    },
    "required_record": {
      "type": "A",
      "name": "shop",
      "value": "cname.theorbits.app"
    },
    "seen": "CNAME old-host.example.net",
    "nameservers": {
      "names": [
        "ns1.theorbits.app",
        "ns2.theorbits.app"
      ],
      "pointing": false
    },
    "email": "zoho",
    "certificate": {
      "state": "none",
      "issued_at": "2026-11-10T09:30:00Z",
      "expires_at": "2026-11-10T09:30:00Z"
    },
    "checked_at": "2026-11-10T09:30:00Z",
    "created_at": "2026-11-10T09:30:00Z"
  }
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: Another team has the domain, or a zone of another team's holds or sits inside it (`errors[0].field` is `domain`).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## A domain

```http
GET /v1/teams/{team}/domains/{domain}
```

A domain's page: its state, the record it needs and what the last check found, the hostname card (which project and branch it serves, or where it redirects) and its certificate. While it's `pending`, refresh the page every few seconds or call `POST .../checks`.

**Permissions:** Any team member. A non-member, or a domain of another team, gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `domain`: The domain's name, or its `dom_` id.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/domains/example.com" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "name": "shop.shadyventures.ng",
  "apex": "shadyventures.ng",
  "host": "shop",
  "dns": "external",
  "state": "pending",
  "project": {
    "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "branch": null,
  "redirect": {
    "to": "to",
    "status": 301
  },
  "required_record": {
    "type": "A",
    "name": "shop",
    "value": "cname.theorbits.app"
  },
  "seen": "CNAME old-host.example.net",
  "nameservers": {
    "names": [
      "ns1.theorbits.app",
      "ns2.theorbits.app"
    ],
    "pointing": false
  },
  "email": "zoho",
  "certificate": {
    "state": "none",
    "issued_at": "2026-11-10T09:30:00Z",
    "expires_at": "2026-11-10T09:30:00Z"
  },
  "checked_at": "2026-11-10T09:30:00Z",
  "created_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Change what a domain serves

```http
PATCH /v1/teams/{team}/domains/{domain}
```

The hostname card's Change: point the domain at another project, a branch, production again, a redirect, or nothing (`project: null` leaves it "Not in use"). Send only what changes; `null` clears a field. The name and DNS mode don't change: remove the domain and add it again.

**Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `domain`: The domain's name, or its `dom_` id.

Body:

- `project` (string or null)
- `branch` (string or null): At most 128 characters.
- `to` (string or null): At most 253 characters.

Example:

```sh
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/domains/example.com" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": null,
    "branch": null,
    "to": null
  }'
```

Response `200`:

```json
{
  "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "name": "shop.shadyventures.ng",
  "apex": "shadyventures.ng",
  "host": "shop",
  "dns": "external",
  "state": "pending",
  "project": {
    "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "branch": null,
  "redirect": {
    "to": "to",
    "status": 301
  },
  "required_record": {
    "type": "A",
    "name": "shop",
    "value": "cname.theorbits.app"
  },
  "seen": "CNAME old-host.example.net",
  "nameservers": {
    "names": [
      "ns1.theorbits.app",
      "ns2.theorbits.app"
    ],
    "pointing": false
  },
  "email": "zoho",
  "certificate": {
    "state": "none",
    "issued_at": "2026-11-10T09:30:00Z",
    "expires_at": "2026-11-10T09:30:00Z"
  },
  "checked_at": "2026-11-10T09:30:00Z",
  "created_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Remove a domain

```http
DELETE /v1/teams/{team}/domains/{domain}
```

Remove domain, after the dialog's confirmation. The project stops answering on it within a minute and its certificate is deleted. The record at the team's DNS provider stays until they delete it there.

**Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `domain`: The domain's name, or its `dom_` id.

Example:

```sh
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/domains/example.com" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `204`: Removed.

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Look for the domain's DNS now

```http
POST /v1/teams/{team}/domains/{domain}/checks
```

Check now. Orbits looks up the domain's DNS at once and answers with the domain as it stands, `checked_at` included. A domain checked in the last 10 seconds isn't looked up again; the answer is the same. Orbits also checks by itself every minute while a domain waits, and every 10 minutes once it's valid. A certificate follows within about a minute of DNS being found.

**Permissions:** Any team member: checking changes nothing the team chose. A non-member gets 404.

This call ignores `Idempotency-Key`.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `domain`: The domain's name, or its `dom_` id.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/domains/example.com/checks" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "name": "shop.shadyventures.ng",
  "apex": "shadyventures.ng",
  "host": "shop",
  "dns": "external",
  "state": "pending",
  "project": {
    "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "branch": null,
  "redirect": {
    "to": "to",
    "status": 301
  },
  "required_record": {
    "type": "A",
    "name": "shop",
    "value": "cname.theorbits.app"
  },
  "seen": "CNAME old-host.example.net",
  "nameservers": {
    "names": [
      "ns1.theorbits.app",
      "ns2.theorbits.app"
    ],
    "pointing": false
  },
  "email": "zoho",
  "certificate": {
    "state": "none",
    "issued_at": "2026-11-10T09:30:00Z",
    "expires_at": "2026-11-10T09:30:00Z"
  },
  "checked_at": "2026-11-10T09:30:00Z",
  "created_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `503`: A store this endpoint reads is unreachable. Try again shortly.
