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
typestringrequiredOne of
A,AAAA,CNAME,MX,TXT,CAA.namestringrequiredRelative to the zone;
@for the apex.At most 253 characters.
valuestringrequiredAn MX record's is its priority and server; a TXT record's is its text without quotes.
At most 2048 characters.
ttlintegerrequiredSeconds;
0is Auto (5 minutes).One of
0,60,300,3600,86400.idstringrequiredmanagedbooleanrequiredOrbits keeps it for a project; it can't be changed here.
used_bynull or objectrequiredShow 2 child fieldsHide child fields
kindstringrequiredOne of
project,email.projectobjectShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
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.
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 zone's records, by name then type.itemsarray of DnsRecordrequiredShow 8 child fieldsHide child fields
typestringrequiredOne of
A,AAAA,CNAME,MX,TXT,CAA.namestringrequiredRelative to the zone;
@for the apex.At most 253 characters.
valuestringrequiredAn MX record's is its priority and server; a TXT record's is its text without quotes.
At most 2048 characters.
ttlintegerrequiredSeconds;
0is Auto (5 minutes).One of
0,60,300,3600,86400.idstringrequiredmanagedbooleanrequiredOrbits keeps it for a project; it can't be changed here.
used_bynull or objectrequiredShow 2 child fieldsHide child fields
kindstringrequiredOne of
project,email.projectobjectShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
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"{
"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.
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.domainstringrequiredThe domain's name, or its
dom_id.
Body
application/jsontypestringrequiredOne of
A,AAAA,CNAME,MX,TXT,CAA.namestringrequiredRelative to the zone;
@for the apex.At most 253 characters.
valuestringrequiredAn MX record's is its priority and server; a TXT record's is its text without quotes.
At most 2048 characters.
ttlintegerrequiredSeconds;
0is Auto (5 minutes).One of
0,60,300,3600,86400.
Response 201
Added.typestringrequiredOne of
A,AAAA,CNAME,MX,TXT,CAA.namestringrequiredRelative to the zone;
@for the apex.At most 253 characters.
valuestringrequiredAn MX record's is its priority and server; a TXT record's is its text without quotes.
At most 2048 characters.
ttlintegerrequiredSeconds;
0is Auto (5 minutes).One of
0,60,300,3600,86400.idstringrequiredmanagedbooleanrequiredOrbits keeps it for a project; it can't be changed here.
used_bynull or objectrequiredShow 2 child fieldsHide child fields
kindstringrequiredOne of
project,email.projectobjectShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
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
}'{
"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.domainstringrequiredThe domain's name, or its
dom_id.recordstringrequired
Body
application/jsontypestringrequiredOne of
A,AAAA,CNAME,MX,TXT,CAA.namestringrequiredRelative to the zone;
@for the apex.At most 253 characters.
valuestringrequiredAn MX record's is its priority and server; a TXT record's is its text without quotes.
At most 2048 characters.
ttlintegerrequiredSeconds;
0is Auto (5 minutes).One of
0,60,300,3600,86400.
Response 200
Updated.typestringrequiredOne of
A,AAAA,CNAME,MX,TXT,CAA.namestringrequiredRelative to the zone;
@for the apex.At most 253 characters.
valuestringrequiredAn MX record's is its priority and server; a TXT record's is its text without quotes.
At most 2048 characters.
ttlintegerrequiredSeconds;
0is Auto (5 minutes).One of
0,60,300,3600,86400.idstringrequiredmanagedbooleanrequiredOrbits keeps it for a project; it can't be changed here.
used_bynull or objectrequiredShow 2 child fieldsHide child fields
kindstringrequiredOne of
project,email.projectobjectShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
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
}'{
"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.domainstringrequiredThe 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"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.
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.domainstringrequiredThe domain's name, or its
dom_id.
Body
application/jsonzonestringrequiredThe zone file as text.
At most 200000 characters.
dry_runbooleanDefaults to
false.
Response 200
What the file holds, and what was (or would be) added.foundintegerrequiredRecords in the file Orbits can use.
addedintegerrequiredexistingintegerrequiredAlready in the zone.
skippedintegerrequiredLines Orbits can't use.
recordsarray of objectrequiredThe ones added (or to be added).
Show 4 child fieldsHide child fields
typestringrequiredOne of
A,AAAA,CNAME,MX,TXT,CAA.namestringrequiredRelative to the zone;
@for the apex.At most 253 characters.
valuestringrequiredAn MX record's is its priority and server; a TXT record's is its text without quotes.
At most 2048 characters.
ttlintegerrequiredSeconds;
0is 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"
}'{
"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.
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 dialog's state.zonestringrequiredproviderstring or nullrequiredSet up now: the Active badge. Null when none is.
One of
zoho,google,microsoft.email_recordsintegerrequiredThe zone's mail records now (MX, SPF, Microsoft's autodiscover), for "Already set up · 5 records".
providersarray of objectrequiredShow 2 child fieldsHide child fields
idstringrequiredOne of
zoho,google,microsoft,other.recordsarray of objectrequiredWhat Setup would add; empty for
other.Show 4 child fieldsHide child fields
typestringrequiredOne of
A,AAAA,CNAME,MX,TXT,CAA.namestringrequiredRelative to the zone;
@for the apex.At most 253 characters.
valuestringrequiredAn MX record's is its priority and server; a TXT record's is its text without quotes.
At most 2048 characters.
ttlintegerrequiredSeconds;
0is 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"{
"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.
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/jsonproviderstringrequiredOne of
zoho,google,microsoft,other.
Response 200
The zone's records after the change.itemsarray of DnsRecordrequiredShow 8 child fieldsHide child fields
typestringrequiredOne of
A,AAAA,CNAME,MX,TXT,CAA.namestringrequiredRelative to the zone;
@for the apex.At most 253 characters.
valuestringrequiredAn MX record's is its priority and server; a TXT record's is its text without quotes.
At most 2048 characters.
ttlintegerrequiredSeconds;
0is Auto (5 minutes).One of
0,60,300,3600,86400.idstringrequiredmanagedbooleanrequiredOrbits keeps it for a project; it can't be changed here.
used_bynull or objectrequiredShow 2 child fieldsHide child fields
kindstringrequiredOne of
project,email.projectobjectShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
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"
}'{
"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"
}
]
}