OrbitsDocs
esc
    Open Orbits
    API reference · DomainsDomains

    Domains

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

    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.

    The domain object

    Fields

    • idstringrequired
    • namestringrequired
    • apexstringrequired

      The registrable part.

    • hoststringrequired

      What precedes the apex; @ for the apex itself.

    • dnsstringrequired

      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.

    • statestringrequired

      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.

    • projectnull or objectrequired

      What it serves or redirects for; null is "Not in use".

      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • branchstring or nullrequired

      The branch whose newest ready preview it serves; null for production.

    • redirectnull or Redirectrequired
      Show 2 child fields
      • tostringrequired

        The hostname it sends visitors to, keeping the path.

      • statusintegerrequired

        One of 301, 308.

    • required_recordobject or nullrequired

      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.

      Show 3 child fields
      • typestringrequired

        One of A, CNAME.

      • namestringrequired
      • valuestringrequired
    • seenstring or nullrequired

      What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.

    • nameserversobject or nullrequired

      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.

      Show 2 child fields
      • namesarray of stringrequired
      • pointingbooleanrequired
    • emailstring or nullrequired

      The provider Email setup added records for, on an Orbits DNS zone.

      One of zoho, google, microsoft.

    • certificateobjectrequired
      Show 3 child fields
      • statestringrequired

        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_atstring or nullrequired
      • expires_atstring or nullrequired

        It renews on its own about 30 days before.

    • checked_atstring or nullrequired
    • created_atstringrequired

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

    GET/v1/teams/{team}/projects/{project}/branch-addresses
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Response 200

    The project's branches with a ready preview, the most recently deployed first.
    • itemsarray of objectrequired
      Show 5 child fields
      • branchstringrequired
      • hoststringrequired
      • urlstringrequired
      • deployment_idstringrequired
      • deployed_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/projects/my-app/branch-addresses" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "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"
        }
      ]
    }

    The team's 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.

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

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    Query parameters

    • qstring

      Part of a domain's name or its project's name.

      At most 253 characters.

    • statestring

      One of pending, valid, misconfigured.

    • dnsstring

      One of external, orbits.

    • projectstring

      A project's id or slug.

    Response 200

    The team's domains that match.
    • as_ofstringrequired
    • itemsarray of Domainrequired
      Show 16 child fields
      • idstringrequired
      • namestringrequired
      • apexstringrequired

        The registrable part.

      • hoststringrequired

        What precedes the apex; @ for the apex itself.

      • dnsstringrequired

        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.

      • statestringrequired

        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.

      • projectnull or objectrequired

        What it serves or redirects for; null is "Not in use".

        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
      • branchstring or nullrequired

        The branch whose newest ready preview it serves; null for production.

      • redirectnull or Redirectrequired
        Show 2 child fields
        • tostringrequired

          The hostname it sends visitors to, keeping the path.

        • statusintegerrequired

          One of 301, 308.

      • required_recordobject or nullrequired

        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.

        Show 3 child fields
        • typestringrequired

          One of A, CNAME.

        • namestringrequired
        • valuestringrequired
      • seenstring or nullrequired

        What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.

      • nameserversobject or nullrequired

        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.

        Show 2 child fields
        • namesarray of stringrequired
        • pointingbooleanrequired
      • emailstring or nullrequired

        The provider Email setup added records for, on an Orbits DNS zone.

        One of zoho, google, microsoft.

      • certificateobjectrequired
        Show 3 child fields
        • statestringrequired

          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_atstring or nullrequired
        • expires_atstring or nullrequired

          It renews on its own about 30 days before.

      • checked_atstring or nullrequired
      • created_atstringrequired
    • summaryobjectrequired

      The team's domains whatever the filters.

      Show 5 child fields
      • totalintegerrequired
      • apexintegerrequired

        How many are apex domains; the rest are subdomains.

      • orbitsarray of stringrequired

        Names of the domains on Orbits DNS.

      • pendingintegerrequired
      • misconfiguredintegerrequired
    • projectsarray of objectrequired

      The team's projects, for the project filter.

      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired

    Errors

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

    Add a domain

    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.

    POST/v1/teams/{team}/domains
    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.

    Body

    application/json
    • domainstringrequired

      As typed: a scheme, path or trailing dot comes off, and it is lowercased.

      At most 253 characters.

    • dnsstring

      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.

    • projectstring or null

      A project's id or slug.

    • branchstring or null

      Serve this branch's newest ready preview instead of production. Needs project.

      At most 128 characters.

    • tostring or null

      Redirect every request (308, same path) to this hostname instead of serving.

      At most 253 characters.

    Response 200

    The team already had this domain and it served nothing (a zone moved to Orbits DNS before a project was picked, say): it now serves what the request asks, as PATCH .../domains/{domain} would. dns is ignored; the domain keeps its own.
    • idstringrequired
    • namestringrequired
    • apexstringrequired

      The registrable part.

    • hoststringrequired

      What precedes the apex; @ for the apex itself.

    • dnsstringrequired

      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.

    • statestringrequired

      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.

    • projectnull or objectrequired

      What it serves or redirects for; null is "Not in use".

      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • branchstring or nullrequired

      The branch whose newest ready preview it serves; null for production.

    • redirectnull or Redirectrequired
      Show 2 child fields
      • tostringrequired

        The hostname it sends visitors to, keeping the path.

      • statusintegerrequired

        One of 301, 308.

    • required_recordobject or nullrequired

      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.

      Show 3 child fields
      • typestringrequired

        One of A, CNAME.

      • namestringrequired
      • valuestringrequired
    • seenstring or nullrequired

      What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.

    • nameserversobject or nullrequired

      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.

      Show 2 child fields
      • namesarray of stringrequired
      • pointingbooleanrequired
    • emailstring or nullrequired

      The provider Email setup added records for, on an Orbits DNS zone.

      One of zoho, google, microsoft.

    • certificateobjectrequired
      Show 3 child fields
      • statestringrequired

        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_atstring or nullrequired
      • expires_atstring or nullrequired

        It renews on its own about 30 days before.

    • checked_atstring or nullrequired
    • created_atstringrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 409This 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).
    • 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" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "domain": "shop.shadyventures.ng"
      }'
    Response 200
    {
      "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"
    }

    What adding a domain would do

    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.

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

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    Query parameters

    • domainstringrequired

      At most 253 characters.

    • dnsstring

      One of external, orbits.

    Response 200

    What Add would do.
    • domainstringrequired

      As Add would store it: scheme, path and trailing dot off, lowercased.

    • apexstringrequired
    • hoststringrequired
    • dnsstringrequired

      What it would use. A name inside one of the team's zones is on Orbits DNS whatever was asked.

      One of external, orbits.

    • zonestring or nullrequired

      The team's Orbits DNS zone it would be in (itself, when it would become a zone); null on outside DNS.

    • required_recordobject or nullrequired

      The one record to add at the team's DNS provider, on outside DNS.

      Show 3 child fields
      • typestringrequired

        One of A, CNAME.

      • namestringrequired
      • valuestringrequired
    • nameserversarray of stringrequired

      When it would become a zone: the nameservers to set (an apex) or add as NS records at its parent's DNS (a subdomain).

    • existingnull or Domainrequired

      The team has this domain already. Add links it to the request's project or redirect when it serves nothing; otherwise it's a 409.

      Show 16 child fields
      • idstringrequired
      • namestringrequired
      • apexstringrequired

        The registrable part.

      • hoststringrequired

        What precedes the apex; @ for the apex itself.

      • dnsstringrequired

        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.

      • statestringrequired

        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.

      • projectnull or objectrequired

        What it serves or redirects for; null is "Not in use".

        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
      • branchstring or nullrequired

        The branch whose newest ready preview it serves; null for production.

      • redirectnull or Redirectrequired
        Show 2 child fields
        • tostringrequired

          The hostname it sends visitors to, keeping the path.

        • statusintegerrequired

          One of 301, 308.

      • required_recordobject or nullrequired

        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.

        Show 3 child fields
        • typestringrequired

          One of A, CNAME.

        • namestringrequired
        • valuestringrequired
      • seenstring or nullrequired

        What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.

      • nameserversobject or nullrequired

        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.

        Show 2 child fields
        • namesarray of stringrequired
        • pointingbooleanrequired
      • emailstring or nullrequired

        The provider Email setup added records for, on an Orbits DNS zone.

        One of zoho, google, microsoft.

      • certificateobjectrequired
        Show 3 child fields
        • statestringrequired

          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_atstring or nullrequired
        • expires_atstring or nullrequired

          It renews on its own about 30 days before.

      • checked_atstring or nullrequired
      • created_atstringrequired

    Errors

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

    Every code is explained in Errors.

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

    A 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.

    GET/v1/teams/{team}/domains/{domain}
    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 domain.
    • idstringrequired
    • namestringrequired
    • apexstringrequired

      The registrable part.

    • hoststringrequired

      What precedes the apex; @ for the apex itself.

    • dnsstringrequired

      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.

    • statestringrequired

      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.

    • projectnull or objectrequired

      What it serves or redirects for; null is "Not in use".

      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • branchstring or nullrequired

      The branch whose newest ready preview it serves; null for production.

    • redirectnull or Redirectrequired
      Show 2 child fields
      • tostringrequired

        The hostname it sends visitors to, keeping the path.

      • statusintegerrequired

        One of 301, 308.

    • required_recordobject or nullrequired

      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.

      Show 3 child fields
      • typestringrequired

        One of A, CNAME.

      • namestringrequired
      • valuestringrequired
    • seenstring or nullrequired

      What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.

    • nameserversobject or nullrequired

      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.

      Show 2 child fields
      • namesarray of stringrequired
      • pointingbooleanrequired
    • emailstring or nullrequired

      The provider Email setup added records for, on an Orbits DNS zone.

      One of zoho, google, microsoft.

    • certificateobjectrequired
      Show 3 child fields
      • statestringrequired

        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_atstring or nullrequired
      • expires_atstring or nullrequired

        It renews on its own about 30 days before.

    • checked_atstring or nullrequired
    • created_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" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "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"
    }

    Change what a domain serves

    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.

    PATCH/v1/teams/{team}/domains/{domain}
    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
    • projectstring or null
    • branchstring or null

      At most 128 characters.

    • tostring or null

      At most 253 characters.

    Response 200

    Updated.
    • idstringrequired
    • namestringrequired
    • apexstringrequired

      The registrable part.

    • hoststringrequired

      What precedes the apex; @ for the apex itself.

    • dnsstringrequired

      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.

    • statestringrequired

      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.

    • projectnull or objectrequired

      What it serves or redirects for; null is "Not in use".

      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • branchstring or nullrequired

      The branch whose newest ready preview it serves; null for production.

    • redirectnull or Redirectrequired
      Show 2 child fields
      • tostringrequired

        The hostname it sends visitors to, keeping the path.

      • statusintegerrequired

        One of 301, 308.

    • required_recordobject or nullrequired

      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.

      Show 3 child fields
      • typestringrequired

        One of A, CNAME.

      • namestringrequired
      • valuestringrequired
    • seenstring or nullrequired

      What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.

    • nameserversobject or nullrequired

      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.

      Show 2 child fields
      • namesarray of stringrequired
      • pointingbooleanrequired
    • emailstring or nullrequired

      The provider Email setup added records for, on an Orbits DNS zone.

      One of zoho, google, microsoft.

    • certificateobjectrequired
      Show 3 child fields
      • statestringrequired

        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_atstring or nullrequired
      • expires_atstring or nullrequired

        It renews on its own about 30 days before.

    • checked_atstring or nullrequired
    • created_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 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
    {
      "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"
    }

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

    DELETE/v1/teams/{team}/domains/{domain}
    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.

    Response 204

    Removed. No body.

    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 DELETE "https://api.theorbits.app/v1/teams/my-team/domains/example.com" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    HTTP/1.1 204 No Content

    Look for the domain's DNS now

    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.

    POST/v1/teams/{team}/domains/{domain}/checks
    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 domain after the check.
    • idstringrequired
    • namestringrequired
    • apexstringrequired

      The registrable part.

    • hoststringrequired

      What precedes the apex; @ for the apex itself.

    • dnsstringrequired

      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.

    • statestringrequired

      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.

    • projectnull or objectrequired

      What it serves or redirects for; null is "Not in use".

      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • branchstring or nullrequired

      The branch whose newest ready preview it serves; null for production.

    • redirectnull or Redirectrequired
      Show 2 child fields
      • tostringrequired

        The hostname it sends visitors to, keeping the path.

      • statusintegerrequired

        One of 301, 308.

    • required_recordobject or nullrequired

      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.

      Show 3 child fields
      • typestringrequired

        One of A, CNAME.

      • namestringrequired
      • valuestringrequired
    • seenstring or nullrequired

      What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.

    • nameserversobject or nullrequired

      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.

      Show 2 child fields
      • namesarray of stringrequired
      • pointingbooleanrequired
    • emailstring or nullrequired

      The provider Email setup added records for, on an Orbits DNS zone.

      One of zoho, google, microsoft.

    • certificateobjectrequired
      Show 3 child fields
      • statestringrequired

        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_atstring or nullrequired
      • expires_atstring or nullrequired

        It renews on its own about 30 days before.

    • checked_atstring or nullrequired
    • created_atstringrequired

    Errors

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

    Every code is explained in Errors.

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

    Was this page helpful?

    Updated