# DNS

Records of a domain on Orbits DNS, zone file imports, and email records.

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

These routes manage the records of a domain whose nameservers are Orbits' (`ns1.theorbits.app` and `ns2.theorbits.app`). See [Orbits DNS](https://docs.orbits.africa/domains/orbits-dns) and [Email records](https://docs.orbits.africa/domains/email-records).

Endpoints:

- `GET /v1/teams/{team}/domains/{domain}/records`: A zone's records
- `POST /v1/teams/{team}/domains/{domain}/records`: Add a record
- `PUT /v1/teams/{team}/domains/{domain}/records/{record}`: Edit a record
- `DELETE /v1/teams/{team}/domains/{domain}/records/{record}`: Delete a record
- `POST /v1/teams/{team}/domains/{domain}/zone-imports`: Import a BIND zone file
- `GET /v1/teams/{team}/domains/{domain}/email`: The Email setup dialog
- `PUT /v1/teams/{team}/domains/{domain}/email`: Set up email for a zone

## The DNS record object



- `type` (string, required): One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA`.
- `name` (string, required): Relative to the zone; `@` for the apex. At most 253 characters.
- `value` (string, required): An MX record's is its priority and server; a TXT record's is its text without quotes. At most 2048 characters.
- `ttl` (integer, required): Seconds; `0` is Auto (5 minutes). One of `0`, `60`, `300`, `3600`, `86400`.
- `id` (string, required)
- `managed` (boolean, required): Orbits keeps it for a project; it can't be changed here.
- `used_by` (null or object, required)
  - `kind` (string, required): One of `project`, `email`.
  - `project` (object)
    - `id` (string, required)
    - `slug` (string, required)
    - `name` (string, required)
- `updated_at` (string, required)
## A zone's records

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

The DNS records table on an Orbits DNS domain's page: every record the zone serves, the team's own and the ones Orbits manages for its projects (`used_by.kind: project`, `managed: true`, locked: they change from that project's Domains page). Email records (`used_by.kind: email`) came with Email setup and stay editable. The zone also has its SOA and NS records, which aren't listed.

**Permissions:** Any team member. A non-member 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/records" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "type": "A",
      "name": "@",
      "value": "10 mx.zoho.com",
      "ttl": 0,
      "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "managed": false,
      "used_by": {
        "kind": "project",
        "project": {
          "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w",
          "slug": "my-app",
          "name": "my-app"
        }
      },
      "updated_at": "2026-11-10T09:30:00Z"
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Add a record

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

Add a DNS record. It's served within about a minute. A name Orbits manages for a project (the apex and `www` of a zone in use, a subdomain added as a domain) can't take another record there: add the domain from the project's Domains page instead. A CNAME can't share its name with any other record, and can't sit at `@`.

**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.
- `domain`: The domain's name, or its `dom_` id.

Body:

- `type` (string, required): One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA`.
- `name` (string, required): Relative to the zone; `@` for the apex. At most 253 characters.
- `value` (string, required): An MX record's is its priority and server; a TXT record's is its text without quotes. At most 2048 characters.
- `ttl` (integer, required): Seconds; `0` is Auto (5 minutes). One of `0`, `60`, `300`, `3600`, `86400`.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/domains/example.com/records" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "@",
    "value": "10 mx.zoho.com",
    "ttl": 0
  }'
```

Response `201`:

```json
{
  "type": "A",
  "name": "@",
  "value": "10 mx.zoho.com",
  "ttl": 0,
  "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "managed": false,
  "used_by": {
    "kind": "project",
    "project": {
      "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "slug": "my-app",
      "name": "my-app"
    }
  },
  "updated_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.
## Edit a record

```http
PUT /v1/teams/{team}/domains/{domain}/records/{record}
```

The record menu's Edit: the record is replaced by what's sent, under the same rules as adding one. Records Orbits manages for a project can't be edited (409).

**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.
- `record`

Body:

- `type` (string, required): One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA`.
- `name` (string, required): Relative to the zone; `@` for the apex. At most 253 characters.
- `value` (string, required): An MX record's is its priority and server; a TXT record's is its text without quotes. At most 2048 characters.
- `ttl` (integer, required): Seconds; `0` is Auto (5 minutes). One of `0`, `60`, `300`, `3600`, `86400`.

Example:

```sh
curl -X PUT "https://api.theorbits.app/v1/teams/my-team/domains/example.com/records/rec_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "@",
    "value": "10 mx.zoho.com",
    "ttl": 0
  }'
```

Response `200`:

```json
{
  "type": "A",
  "name": "@",
  "value": "10 mx.zoho.com",
  "ttl": 0,
  "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "managed": false,
  "used_by": {
    "kind": "project",
    "project": {
      "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "slug": "my-app",
      "name": "my-app"
    }
  },
  "updated_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.
## Delete a record

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

The record menu's Delete, after its confirmation. Records Orbits manages for a project can't be deleted (409): remove the domain from the project instead.

**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.
- `record`

Example:

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

Response `204`: Deleted.

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.
## Import a BIND zone file

```http
POST /v1/teams/{team}/domains/{domain}/zone-imports
```

Import zone file. Send the pasted or dropped file with `dry_run: true` to show "4 records found: 1 new, 3 already here", then again without it to add the new ones. Records already in the zone (same type, name and value) are left as they are. Lines Orbits can't use (SOA, NS, records for another domain, types it doesn't host, names Orbits manages for a project) are counted in `skipped`, not guessed at.

**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.
- `domain`: The domain's name, or its `dom_` id.

Body:

- `zone` (string, required): The zone file as text. At most 200000 characters.
- `dry_run` (boolean): Defaults to `false`.

Example:

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

Response `200`:

```json
{
  "found": 1,
  "added": 1,
  "existing": 1,
  "skipped": 1,
  "records": [
    {
      "type": "A",
      "name": "@",
      "value": "10 mx.zoho.com",
      "ttl": 0
    }
  ]
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `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.
## The Email setup dialog

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

Set up email for a zone: the provider set up now (the Active badge), how many of the zone's records came with it or are mail records ("Already set up · 5 records"), and for each provider the records Setup would add, less any that would clash with the team's own or Orbits' (for "Adds 5 MX records and SPF"). `other` is "Something else" and adds nothing. A name inside a zone answers with its zone's.

**Permissions:** Any team member. A non-member 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/email" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "zone": "shadyventures.com",
  "provider": "zoho",
  "email_records": 1,
  "providers": [
    {
      "id": "zoho",
      "records": [
        {
          "type": "A",
          "name": "@",
          "value": "10 mx.zoho.com",
          "ttl": 0
        }
      ]
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Set up email for a zone

```http
PUT /v1/teams/{team}/domains/{domain}/email
```

Email setup: the zone's MX and SPF records for one provider, in place of the last provider's (records added by Email setup, `used_by.kind: email`). DMARC and the team's other TXT records stay. DKIM keys belong to the team's mail account, so they're added as records afterwards. `other` ("Something else") clears the provider and keeps every record, for the team to manage.

**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:

- `provider` (string, required): One of `zoho`, `google`, `microsoft`, `other`.

Example:

```sh
curl -X PUT "https://api.theorbits.app/v1/teams/my-team/domains/example.com/email" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "zoho"
  }'
```

Response `200`:

```json
{
  "items": [
    {
      "type": "A",
      "name": "@",
      "value": "10 mx.zoho.com",
      "ttl": 0,
      "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "managed": false,
      "used_by": {
        "kind": "project",
        "project": {
          "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w",
          "slug": "my-app",
          "name": "my-app"
        }
      },
      "updated_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).
