API reference

OrbiDNS REST API v1

Base path /api/v1. JSON in, JSON out. The full machine-readable schema is published as OpenAPI.

Authentication

Create a key under Dashboard → API keys and send it as Authorization: Bearer odns_…. Each key carries scopes; calls outside them return 403 insufficient_scope.

Asynchronous writes

Record writes return 202 with status: "pending". Poll the record until it is active or failed.

Rate limits

120 requests per minute per key, plus your plan's daily quota. Responses include X-RateLimit-Limit and X-RateLimit-Remaining; 429 responses include Retry-After.

Errors

Every error uses one envelope. Quote the request ID when contacting support.

{
  "error": {
    "code": "namespace_violation",
    "message": "Record name is outside your subdomain",
    "details": {
      "field": "name"
    },
    "request_id": "5f0c…"
  }
}

HTTP	Code	Meaning
400	invalid_token / invalid_code	Bad token or verification code
401	unauthorized / invalid_api_key	Missing, expired or revoked credentials
403	insufficient_scope	The key lacks the required permission
403	namespace_violation	Record name is outside your subdomain
403	quota_exceeded	Plan limit reached (subdomains or records)
404	not_found	Resource does not exist or is not yours
409	subdomain_taken / subdomain_reserved	Name not available
409	cname_conflict / duplicate_record / record_busy	Conflicting record or change in progress
422	validation_error / invalid_dns_input	Input failed validation; see details
429	rate_limited / quota_exceeded	Too many requests; honour Retry-After

Domains

GET/api/v1/domains

List root domains open for registration.

Scope: domains:read

[
  {
    "id": "4b0e…",
    "name": "orbinex.in",
    "registration_enabled": true,
    "min_label_length": 3,
    "max_label_length": 63,
    "allowed_record_types": [
      "A",
      "AAAA",
      "CNAME",
      "TXT",
      "MX",
      "SRV",
      "CAA"
    ]
  }
]

curl -X GET "https://orbidns.example/api/v1/domains" \
  -H "Authorization: Bearer $ORBIDNS_KEY"

GET/api/v1/domains/{domain_id}/availability?label=demo

Check whether a label is available.

Scope: domains:read

{
  "domain": "orbinex.in",
  "label": "demo",
  "fqdn": "demo.orbinex.in",
  "available": true,
  "reason": null
}

curl -X GET "https://orbidns.example/api/v1/domains/{domain_id}/availability" \
  -H "Authorization: Bearer $ORBIDNS_KEY"

Subdomains

GET/api/v1/subdomains?offset=0&limit=50

List your subdomains (paginated).

Scope: subdomains:read

{
  "items": [
    {
      "id": "9f1c…",
      "fqdn": "demo.orbinex.in",
      "status": "active",
      "record_count": 2
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

curl -X GET "https://orbidns.example/api/v1/subdomains" \
  -H "Authorization: Bearer $ORBIDNS_KEY"

POST/api/v1/subdomains

Claim a subdomain. Atomic: concurrent claims for the same name return 409.

Scope: subdomains:write

{
  "id": "9f1c…",
  "fqdn": "demo.orbinex.in",
  "status": "active"
}

curl -X POST "https://orbidns.example/api/v1/subdomains" \
  -H "Authorization: Bearer $ORBIDNS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain_id":"4b0e…","label":"demo"}'

GET/api/v1/subdomains/{id}

Get one subdomain.

Scope: subdomains:read

curl -X GET "https://orbidns.example/api/v1/subdomains/{id}" \
  -H "Authorization: Bearer $ORBIDNS_KEY"

DELETE/api/v1/subdomains/{id}

Release a subdomain and remove all its records from DNS.

Scope: subdomains:write

curl -X DELETE "https://orbidns.example/api/v1/subdomains/{id}" \
  -H "Authorization: Bearer $ORBIDNS_KEY"

DNS records

GET/api/v1/subdomains/{id}/records?type=A&q=www

List records, optionally filtered by type or text.

Scope: dns:read

curl -X GET "https://orbidns.example/api/v1/subdomains/{id}/records" \
  -H "Authorization: Bearer $ORBIDNS_KEY"

POST/api/v1/subdomains/{id}/records

Create a record. Returns 202 with status pending.

Scope: dns:write

{
  "id": "c71d…",
  "type": "A",
  "name": "demo.orbinex.in",
  "content": "1.2.3.4",
  "ttl": 300,
  "status": "pending"
}

curl -X POST "https://orbidns.example/api/v1/subdomains/{id}/records" \
  -H "Authorization: Bearer $ORBIDNS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","name":"@","content":"1.2.3.4","ttl":300,"proxied":false}'

PUT/api/v1/subdomains/{id}/records/{record_id}

Update a record (type is immutable). Returns 202.

Scope: dns:write

curl -X PUT "https://orbidns.example/api/v1/subdomains/{id}/records/{record_id}" \
  -H "Authorization: Bearer $ORBIDNS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"1.2.3.5","ttl":600}'

DELETE/api/v1/subdomains/{id}/records/{record_id}

Delete a record. Returns 202 with status deleting.

Scope: dns:write

curl -X DELETE "https://orbidns.example/api/v1/subdomains/{id}/records/{record_id}" \
  -H "Authorization: Bearer $ORBIDNS_KEY"

Account

GET/api/v1/usage?days=30

Plan limits, current usage and daily request history.

Scope: usage:read

curl -X GET "https://orbidns.example/api/v1/usage" \
  -H "Authorization: Bearer $ORBIDNS_KEY"

GET/api/v1/api-keys

List API keys (secrets are never returned).

Scope: api_keys:read

curl -X GET "https://orbidns.example/api/v1/api-keys" \
  -H "Authorization: Bearer $ORBIDNS_KEY"

POST/api/v1/api-keys

Create a key. The secret is in the response once.

Scope: api_keys:write

curl -X POST "https://orbidns.example/api/v1/api-keys" \
  -H "Authorization: Bearer $ORBIDNS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci","scopes":["dns:read","dns:write"],"expires_at":"2027-01-01T00:00:00Z"}'

DELETE/api/v1/api-keys/{id}

Revoke a key immediately.

Scope: api_keys:write

curl -X DELETE "https://orbidns.example/api/v1/api-keys/{id}" \
  -H "Authorization: Bearer $ORBIDNS_KEY"