OrbitsDocs
esc
    Open Orbits
    API reference · DomainsDNS

    DNS

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

    These routes manage the records of a domain whose nameservers are Orbits' (ns1.theorbits.app and ns2.theorbits.app). See Orbits DNS and Email records.

    The DNS record object

    Fields

    • typestringrequired

      One of A, AAAA, CNAME, MX, TXT, CAA.

    • namestringrequired

      Relative to the zone; @ for the apex.

      At most 253 characters.

    • valuestringrequired

      An MX record's is its priority and server; a TXT record's is its text without quotes.

      At most 2048 characters.

    • ttlintegerrequired

      Seconds; 0 is Auto (5 minutes).

      One of 0, 60, 300, 3600, 86400.

    • idstringrequired
    • managedbooleanrequired

      Orbits keeps it for a project; it can't be changed here.

    • used_bynull or objectrequired
      Show 2 child fields
      • kindstringrequired

        One of project, email.

      • projectobject
        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
    • updated_atstringrequired

    A zone's 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.

    GET/v1/teams/{team}/domains/{domain}/records
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • domainstringrequired

      The domain's name, or its dom_ id.

    Response 200

    The zone's records, by name then type.
    • itemsarray of DnsRecordrequired
      Show 8 child fields
      • typestringrequired

        One of A, AAAA, CNAME, MX, TXT, CAA.

      • namestringrequired

        Relative to the zone; @ for the apex.

        At most 253 characters.

      • valuestringrequired

        An MX record's is its priority and server; a TXT record's is its text without quotes.

        At most 2048 characters.

      • ttlintegerrequired

        Seconds; 0 is Auto (5 minutes).

        One of 0, 60, 300, 3600, 86400.

      • idstringrequired
      • managedbooleanrequired

        Orbits keeps it for a project; it can't be changed here.

      • used_bynull or objectrequired
        Show 2 child fields
        • kindstringrequired

          One of project, email.

        • projectobject
          Show 3 child fields
          • idstringrequired
          • slugstringrequired
          • namestringrequired
      • updated_atstringrequired

    Errors

    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/domains/example.com/records" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "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"
        }
      ]
    }

    Add a record

    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.

    POST/v1/teams/{team}/domains/{domain}/records
    Full tokenNeeds Idempotency-KeyReturns201Created

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • domainstringrequired

      The domain's name, or its dom_ id.

    Body

    application/json
    • typestringrequired

      One of A, AAAA, CNAME, MX, TXT, CAA.

    • namestringrequired

      Relative to the zone; @ for the apex.

      At most 253 characters.

    • valuestringrequired

      An MX record's is its priority and server; a TXT record's is its text without quotes.

      At most 2048 characters.

    • ttlintegerrequired

      Seconds; 0 is Auto (5 minutes).

      One of 0, 60, 300, 3600, 86400.

    Response 201

    Added.
    • typestringrequired

      One of A, AAAA, CNAME, MX, TXT, CAA.

    • namestringrequired

      Relative to the zone; @ for the apex.

      At most 253 characters.

    • valuestringrequired

      An MX record's is its priority and server; a TXT record's is its text without quotes.

      At most 2048 characters.

    • ttlintegerrequired

      Seconds; 0 is Auto (5 minutes).

      One of 0, 60, 300, 3600, 86400.

    • idstringrequired
    • managedbooleanrequired

      Orbits keeps it for a project; it can't be changed here.

    • used_bynull or objectrequired
      Show 2 child fields
      • kindstringrequired

        One of project, email.

      • projectobject
        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
    • updated_atstringrequired

    Errors

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

    Every code is explained in Errors.

    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
    {
      "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"
    }

    Edit a 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.

    PUT/v1/teams/{team}/domains/{domain}/records/{record}
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • domainstringrequired

      The domain's name, or its dom_ id.

    • recordstringrequired

    Body

    application/json
    • typestringrequired

      One of A, AAAA, CNAME, MX, TXT, CAA.

    • namestringrequired

      Relative to the zone; @ for the apex.

      At most 253 characters.

    • valuestringrequired

      An MX record's is its priority and server; a TXT record's is its text without quotes.

      At most 2048 characters.

    • ttlintegerrequired

      Seconds; 0 is Auto (5 minutes).

      One of 0, 60, 300, 3600, 86400.

    Response 200

    Updated.
    • typestringrequired

      One of A, AAAA, CNAME, MX, TXT, CAA.

    • namestringrequired

      Relative to the zone; @ for the apex.

      At most 253 characters.

    • valuestringrequired

      An MX record's is its priority and server; a TXT record's is its text without quotes.

      At most 2048 characters.

    • ttlintegerrequired

      Seconds; 0 is Auto (5 minutes).

      One of 0, 60, 300, 3600, 86400.

    • idstringrequired
    • managedbooleanrequired

      Orbits keeps it for a project; it can't be changed here.

    • used_bynull or objectrequired
      Show 2 child fields
      • kindstringrequired

        One of project, email.

      • projectobject
        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
    • updated_atstringrequired

    Errors

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

    Every code is explained in Errors.

    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
    {
      "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"
    }

    Delete a 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.

    DELETE/v1/teams/{team}/domains/{domain}/records/{record}
    Full tokenReturns204No Content

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • domainstringrequired

      The domain's name, or its dom_ id.

    • recordstringrequired

    Response 204

    Deleted. No body.

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 409The request conflicts with current state.

    Every code is explained in Errors.

    curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/domains/example.com/records/rec_01jc8x6e4mq2v7r9y3t5b0zp8w" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    HTTP/1.1 204 No Content

    Import a BIND zone file

    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.

    POST/v1/teams/{team}/domains/{domain}/zone-imports
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • domainstringrequired

      The domain's name, or its dom_ id.

    Body

    application/json
    • zonestringrequired

      The zone file as text.

      At most 200000 characters.

    • dry_runboolean

      Defaults to false.

    Response 200

    What the file holds, and what was (or would be) added.
    • foundintegerrequired

      Records in the file Orbits can use.

    • addedintegerrequired
    • existingintegerrequired

      Already in the zone.

    • skippedintegerrequired

      Lines Orbits can't use.

    • recordsarray of objectrequired

      The ones added (or to be added).

      Show 4 child fields
      • typestringrequired

        One of A, AAAA, CNAME, MX, TXT, CAA.

      • namestringrequired

        Relative to the zone; @ for the apex.

        At most 253 characters.

      • valuestringrequired

        An MX record's is its priority and server; a TXT record's is its text without quotes.

        At most 2048 characters.

      • ttlintegerrequired

        Seconds; 0 is Auto (5 minutes).

        One of 0, 60, 300, 3600, 86400.

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 422Validation failed, or the Idempotency-Key was reused with a different body.

    Every code is explained in Errors.

    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
    {
      "found": 1,
      "added": 1,
      "existing": 1,
      "skipped": 1,
      "records": [
        {
          "type": "A",
          "name": "@",
          "value": "10 mx.zoho.com",
          "ttl": 0
        }
      ]
    }

    The Email setup dialog

    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.

    GET/v1/teams/{team}/domains/{domain}/email
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • domainstringrequired

      The domain's name, or its dom_ id.

    Response 200

    The dialog's state.
    • zonestringrequired
    • providerstring or nullrequired

      Set up now: the Active badge. Null when none is.

      One of zoho, google, microsoft.

    • email_recordsintegerrequired

      The zone's mail records now (MX, SPF, Microsoft's autodiscover), for "Already set up · 5 records".

    • providersarray of objectrequired
      Show 2 child fields
      • idstringrequired

        One of zoho, google, microsoft, other.

      • recordsarray of objectrequired

        What Setup would add; empty for other.

        Show 4 child fields
        • typestringrequired

          One of A, AAAA, CNAME, MX, TXT, CAA.

        • namestringrequired

          Relative to the zone; @ for the apex.

          At most 253 characters.

        • valuestringrequired

          An MX record's is its priority and server; a TXT record's is its text without quotes.

          At most 2048 characters.

        • ttlintegerrequired

          Seconds; 0 is Auto (5 minutes).

          One of 0, 60, 300, 3600, 86400.

    Errors

    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/domains/example.com/email" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "zone": "shadyventures.com",
      "provider": "zoho",
      "email_records": 1,
      "providers": [
        {
          "id": "zoho",
          "records": [
            {
              "type": "A",
              "name": "@",
              "value": "10 mx.zoho.com",
              "ttl": 0
            }
          ]
        }
      ]
    }

    Set up email for a zone

    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.

    PUT/v1/teams/{team}/domains/{domain}/email
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • domainstringrequired

      The domain's name, or its dom_ id.

    Body

    application/json
    • providerstringrequired

      One of zoho, google, microsoft, other.

    Response 200

    The zone's records after the change.
    • itemsarray of DnsRecordrequired
      Show 8 child fields
      • typestringrequired

        One of A, AAAA, CNAME, MX, TXT, CAA.

      • namestringrequired

        Relative to the zone; @ for the apex.

        At most 253 characters.

      • valuestringrequired

        An MX record's is its priority and server; a TXT record's is its text without quotes.

        At most 2048 characters.

      • ttlintegerrequired

        Seconds; 0 is Auto (5 minutes).

        One of 0, 60, 300, 3600, 86400.

      • idstringrequired
      • managedbooleanrequired

        Orbits keeps it for a project; it can't be changed here.

      • used_bynull or objectrequired
        Show 2 child fields
        • kindstringrequired

          One of project, email.

        • projectobject
          Show 3 child fields
          • idstringrequired
          • slugstringrequired
          • namestringrequired
      • updated_atstringrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    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
    {
      "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"
        }
      ]
    }

    Was this page helpful?

    Updated