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
idstringrequirednamestringrequiredapexstringrequiredThe registrable part.
hoststringrequiredWhat precedes the apex;
@for the apex itself.dnsstringrequiredexternal: 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.statestringrequiredpending: its record isn't there yet.valid: DNS points at Orbits.misconfigured: a record is there but points elsewhere (seensays where).One of
pending,valid,misconfigured.projectnull or objectrequiredWhat it serves or redirects for; null is "Not in use".
Show 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
branchstring or nullrequiredThe branch whose newest ready preview it serves; null for production.
redirectnull or RedirectrequiredShow 2 child fieldsHide child fields
tostringrequiredThe hostname it sends visitors to, keeping the path.
statusintegerrequiredOne of
301,308.
required_recordobject or nullrequiredThe 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 fieldsHide child fields
typestringrequiredOne of
A,CNAME.namestringrequiredvaluestringrequired
seenstring or nullrequiredWhat the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.
nameserversobject or nullrequiredAn 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.
pointingonce the zone is handed to them. Null for any other domain, including names inside a zone.Show 2 child fieldsHide child fields
namesarray of stringrequiredpointingbooleanrequired
emailstring or nullrequiredThe provider Email setup added records for, on an Orbits DNS zone.
One of
zoho,google,microsoft.certificateobjectrequiredShow 3 child fieldsHide child fields
statestringrequirednone: 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 nullrequiredexpires_atstring or nullrequiredIt renews on its own about 30 days before.
checked_atstring or nullrequiredcreated_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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Response 200
The project's branches with a ready preview, the most recently deployed first.itemsarray of objectrequiredShow 5 child fieldsHide child fields
branchstringrequiredhoststringrequiredurlstringrequireddeployment_idstringrequireddeployed_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"{
"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Query parameters
qstringPart of a domain's name or its project's name.
At most 253 characters.
statestringOne of
pending,valid,misconfigured.dnsstringOne of
external,orbits.projectstringA project's
idorslug.
Response 200
The team's domains that match.as_ofstringrequireditemsarray of DomainrequiredShow 16 child fieldsHide child fields
idstringrequirednamestringrequiredapexstringrequiredThe registrable part.
hoststringrequiredWhat precedes the apex;
@for the apex itself.dnsstringrequiredexternal: 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.statestringrequiredpending: its record isn't there yet.valid: DNS points at Orbits.misconfigured: a record is there but points elsewhere (seensays where).One of
pending,valid,misconfigured.projectnull or objectrequiredWhat it serves or redirects for; null is "Not in use".
Show 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
branchstring or nullrequiredThe branch whose newest ready preview it serves; null for production.
redirectnull or RedirectrequiredShow 2 child fieldsHide child fields
tostringrequiredThe hostname it sends visitors to, keeping the path.
statusintegerrequiredOne of
301,308.
required_recordobject or nullrequiredThe 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 fieldsHide child fields
typestringrequiredOne of
A,CNAME.namestringrequiredvaluestringrequired
seenstring or nullrequiredWhat the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.
nameserversobject or nullrequiredAn 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.
pointingonce the zone is handed to them. Null for any other domain, including names inside a zone.Show 2 child fieldsHide child fields
namesarray of stringrequiredpointingbooleanrequired
emailstring or nullrequiredThe provider Email setup added records for, on an Orbits DNS zone.
One of
zoho,google,microsoft.certificateobjectrequiredShow 3 child fieldsHide child fields
statestringrequirednone: 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 nullrequiredexpires_atstring or nullrequiredIt renews on its own about 30 days before.
checked_atstring or nullrequiredcreated_atstringrequired
summaryobjectrequiredThe team's domains whatever the filters.
Show 5 child fieldsHide child fields
totalintegerrequiredapexintegerrequiredHow many are apex domains; the rest are subdomains.
orbitsarray of stringrequiredNames of the domains on Orbits DNS.
pendingintegerrequiredmisconfiguredintegerrequired
projectsarray of objectrequiredThe team's projects, for the project filter.
Show 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
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"{
"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA 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
teamstringrequiredTeam slug or
team_id.
Body
application/jsondomainstringrequiredAs typed: a scheme, path or trailing dot comes off, and it is lowercased.
At most 253 characters.
dnsstringexternal: 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 nullA project's
idorslug.branchstring or nullServe this branch's newest ready preview instead of production. Needs
project.At most 128 characters.
tostring or nullRedirect 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, asPATCH .../domains/{domain} would. dns is ignored; the domain keeps its own.idstringrequirednamestringrequiredapexstringrequiredThe registrable part.
hoststringrequiredWhat precedes the apex;
@for the apex itself.dnsstringrequiredexternal: 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.statestringrequiredpending: its record isn't there yet.valid: DNS points at Orbits.misconfigured: a record is there but points elsewhere (seensays where).One of
pending,valid,misconfigured.projectnull or objectrequiredWhat it serves or redirects for; null is "Not in use".
Show 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
branchstring or nullrequiredThe branch whose newest ready preview it serves; null for production.
redirectnull or RedirectrequiredShow 2 child fieldsHide child fields
tostringrequiredThe hostname it sends visitors to, keeping the path.
statusintegerrequiredOne of
301,308.
required_recordobject or nullrequiredThe 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 fieldsHide child fields
typestringrequiredOne of
A,CNAME.namestringrequiredvaluestringrequired
seenstring or nullrequiredWhat the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.
nameserversobject or nullrequiredAn 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.
pointingonce the zone is handed to them. Null for any other domain, including names inside a zone.Show 2 child fieldsHide child fields
namesarray of stringrequiredpointingbooleanrequired
emailstring or nullrequiredThe provider Email setup added records for, on an Orbits DNS zone.
One of
zoho,google,microsoft.certificateobjectrequiredShow 3 child fieldsHide child fields
statestringrequirednone: 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 nullrequiredexpires_atstring or nullrequiredIt renews on its own about 30 days before.
checked_atstring or nullrequiredcreated_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].fieldisdomain). - 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"
}'{
"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Query parameters
domainstringrequiredAt most 253 characters.
dnsstringOne of
external,orbits.
Response 200
What Add would do.domainstringrequiredAs Add would store it: scheme, path and trailing dot off, lowercased.
apexstringrequiredhoststringrequireddnsstringrequiredWhat 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 nullrequiredThe team's Orbits DNS zone it would be in (itself, when it would become a zone); null on outside DNS.
required_recordobject or nullrequiredThe one record to add at the team's DNS provider, on outside DNS.
Show 3 child fieldsHide child fields
typestringrequiredOne of
A,CNAME.namestringrequiredvaluestringrequired
nameserversarray of stringrequiredWhen 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 DomainrequiredThe 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 fieldsHide child fields
idstringrequirednamestringrequiredapexstringrequiredThe registrable part.
hoststringrequiredWhat precedes the apex;
@for the apex itself.dnsstringrequiredexternal: 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.statestringrequiredpending: its record isn't there yet.valid: DNS points at Orbits.misconfigured: a record is there but points elsewhere (seensays where).One of
pending,valid,misconfigured.projectnull or objectrequiredWhat it serves or redirects for; null is "Not in use".
Show 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
branchstring or nullrequiredThe branch whose newest ready preview it serves; null for production.
redirectnull or RedirectrequiredShow 2 child fieldsHide child fields
tostringrequiredThe hostname it sends visitors to, keeping the path.
statusintegerrequiredOne of
301,308.
required_recordobject or nullrequiredThe 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 fieldsHide child fields
typestringrequiredOne of
A,CNAME.namestringrequiredvaluestringrequired
seenstring or nullrequiredWhat the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.
nameserversobject or nullrequiredAn 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.
pointingonce the zone is handed to them. Null for any other domain, including names inside a zone.Show 2 child fieldsHide child fields
namesarray of stringrequiredpointingbooleanrequired
emailstring or nullrequiredThe provider Email setup added records for, on an Orbits DNS zone.
One of
zoho,google,microsoft.certificateobjectrequiredShow 3 child fieldsHide child fields
statestringrequirednone: 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 nullrequiredexpires_atstring or nullrequiredIt renews on its own about 30 days before.
checked_atstring or nullrequiredcreated_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].fieldisdomain). - 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"{
"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.domainstringrequiredThe domain's name, or its
dom_id.
Response 200
The domain.idstringrequirednamestringrequiredapexstringrequiredThe registrable part.
hoststringrequiredWhat precedes the apex;
@for the apex itself.dnsstringrequiredexternal: 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.statestringrequiredpending: its record isn't there yet.valid: DNS points at Orbits.misconfigured: a record is there but points elsewhere (seensays where).One of
pending,valid,misconfigured.projectnull or objectrequiredWhat it serves or redirects for; null is "Not in use".
Show 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
branchstring or nullrequiredThe branch whose newest ready preview it serves; null for production.
redirectnull or RedirectrequiredShow 2 child fieldsHide child fields
tostringrequiredThe hostname it sends visitors to, keeping the path.
statusintegerrequiredOne of
301,308.
required_recordobject or nullrequiredThe 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 fieldsHide child fields
typestringrequiredOne of
A,CNAME.namestringrequiredvaluestringrequired
seenstring or nullrequiredWhat the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.
nameserversobject or nullrequiredAn 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.
pointingonce the zone is handed to them. Null for any other domain, including names inside a zone.Show 2 child fieldsHide child fields
namesarray of stringrequiredpointingbooleanrequired
emailstring or nullrequiredThe provider Email setup added records for, on an Orbits DNS zone.
One of
zoho,google,microsoft.certificateobjectrequiredShow 3 child fieldsHide child fields
statestringrequirednone: 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 nullrequiredexpires_atstring or nullrequiredIt renews on its own about 30 days before.
checked_atstring or nullrequiredcreated_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"{
"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.domainstringrequiredThe domain's name, or its
dom_id.
Body
application/jsonprojectstring or nullbranchstring or nullAt most 128 characters.
tostring or nullAt most 253 characters.
Response 200
Updated.idstringrequirednamestringrequiredapexstringrequiredThe registrable part.
hoststringrequiredWhat precedes the apex;
@for the apex itself.dnsstringrequiredexternal: 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.statestringrequiredpending: its record isn't there yet.valid: DNS points at Orbits.misconfigured: a record is there but points elsewhere (seensays where).One of
pending,valid,misconfigured.projectnull or objectrequiredWhat it serves or redirects for; null is "Not in use".
Show 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
branchstring or nullrequiredThe branch whose newest ready preview it serves; null for production.
redirectnull or RedirectrequiredShow 2 child fieldsHide child fields
tostringrequiredThe hostname it sends visitors to, keeping the path.
statusintegerrequiredOne of
301,308.
required_recordobject or nullrequiredThe 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 fieldsHide child fields
typestringrequiredOne of
A,CNAME.namestringrequiredvaluestringrequired
seenstring or nullrequiredWhat the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.
nameserversobject or nullrequiredAn 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.
pointingonce the zone is handed to them. Null for any other domain, including names inside a zone.Show 2 child fieldsHide child fields
namesarray of stringrequiredpointingbooleanrequired
emailstring or nullrequiredThe provider Email setup added records for, on an Orbits DNS zone.
One of
zoho,google,microsoft.certificateobjectrequiredShow 3 child fieldsHide child fields
statestringrequirednone: 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 nullrequiredexpires_atstring or nullrequiredIt renews on its own about 30 days before.
checked_atstring or nullrequiredcreated_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
}'{
"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.domainstringrequiredThe 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"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.domainstringrequiredThe domain's name, or its
dom_id.
Response 200
The domain after the check.idstringrequirednamestringrequiredapexstringrequiredThe registrable part.
hoststringrequiredWhat precedes the apex;
@for the apex itself.dnsstringrequiredexternal: 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.statestringrequiredpending: its record isn't there yet.valid: DNS points at Orbits.misconfigured: a record is there but points elsewhere (seensays where).One of
pending,valid,misconfigured.projectnull or objectrequiredWhat it serves or redirects for; null is "Not in use".
Show 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
branchstring or nullrequiredThe branch whose newest ready preview it serves; null for production.
redirectnull or RedirectrequiredShow 2 child fieldsHide child fields
tostringrequiredThe hostname it sends visitors to, keeping the path.
statusintegerrequiredOne of
301,308.
required_recordobject or nullrequiredThe 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 fieldsHide child fields
typestringrequiredOne of
A,CNAME.namestringrequiredvaluestringrequired
seenstring or nullrequiredWhat the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.
nameserversobject or nullrequiredAn 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.
pointingonce the zone is handed to them. Null for any other domain, including names inside a zone.Show 2 child fieldsHide child fields
namesarray of stringrequiredpointingbooleanrequired
emailstring or nullrequiredThe provider Email setup added records for, on an Orbits DNS zone.
One of
zoho,google,microsoft.certificateobjectrequiredShow 3 child fieldsHide child fields
statestringrequirednone: 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 nullrequiredexpires_atstring or nullrequiredIt renews on its own about 30 days before.
checked_atstring or nullrequiredcreated_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"{
"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"
}