Skip to content
Bitelex Docs

API overview

The Dinio API is a JSON REST API. Everything the CLI and the SDKs do is a call described in this section.

https://api-dinio.bitelex.com/api/v1

All resource routes are under /api/v1. Two system routes are unversioned and need no key: /api/health and /api/docs/openapi.json. The free domain routes and the price list, GET /plans, need no key either.

A first request

Section titled “A first request”
Terminal window
curl -H "Authorization: Bearer $DINIO_API_KEY" https://api-dinio.bitelex.com/api/v1/zones
{
  "success": true,
  "data": [
    {
      "uuid": "6f1c2a9e-3d4b-4c8a-9a51-0e2f7b1d4c33",
      "name": "example.com",
      "has_api_key": true,
      "suspended": false,
      "owner_suspended": false,
      "created_at": 1760000000,
      "updated_at": 1760000000
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
}

Authentication

Section titled “Authentication”

Send an API key as Authorization: Bearer <key> on every /api/v1 request. A personal key (du_…) acts as your user; a zone key (dz_…) is limited to DNS hosting in its zone.

Requests

Section titled “Requests”
  • Bodies are JSON: send Content-Type: application/json. The exceptions are a zone import and a sinkhole list import, whose body is the file itself.
  • Unknown fields in a body are rejected with 422, so send only the documented fields.
  • Ids in paths, queries and bodies are uuids. Where a route says :ref, a name works too; redirects are addressed by their host name only (:name).
  • Record and zone names are full names: www.example.com, not www.

Responses

Section titled “Responses”

Every response — success or error — has the same envelope:

{
  success: boolean,
  data?: T,                                          // on success
  error?: { code: string, message: string, details?: unknown },
  meta?: { page, per_page, total, total_pages },     // on paginated lists
  warnings?: { code: string, message: string, details?: unknown }[]  // on some writes
}

Check success before reading data. A POST that creates something returns 201 with the new object; a DELETE that succeeds returns 200 with success: true and no data. Errors are described in Errors.

A successful write can carry warnings: notices that don’t stop the request, such as a package limit at 80 % or more. Show them to the user. Zone and sinkhole list exports return the file itself, not the envelope.

Every /api/v1 response carries a Request-Id header. Quote it when you contact support; the audit log can be filtered by it.

Pagination

Section titled “Pagination”

GET /records, GET /redirects and GET /certificates are paginated and return meta. Use page (from 1) and per_page, and read pages until page reaches total_pages. The default and maximum per_page depend on the list:

List Default per_page Maximum
/records 20 500
/redirects 50 500
/certificates 50 200

GET /zones returns every zone you can see at once, with meta describing a single page. The audit log and the rules of a sinkhole list page with a cursor instead. All other lists return every item at once, without meta.

Conventions

Section titled “Conventions”
Timestamps created_at, updated_at, health check last_checked_at: Unix seconds. Statistics responses: Unix milliseconds. Audit log ts, and the from/to query of both: ISO 8601.
Durations Health check interval, timeout, retry_interval: seconds.
Enums Always strings: "Country", "Blacklist", "HEALTHY". Unknown labels are rejected with 422.
Record types Strings such as "A", "MX"; case-insensitive on input, uppercase on output.
Record data Returned in canonical form: lowercase names with a trailing dot, compressed IPv6, quoted TXT.

Resources

Section titled “Resources”

The resources fall into Dinio’s two services. Both use the same keys, envelope and errors.

DNS hosting — your zones and everything in them:

Resource Routes
Zones /zones
Zone files /zones/:ref/export, /zones/:ref/import, /zones/:ref/discover
Free domains /free-domains
Records /records
Health checks /health-checks
Geo bans /geo-bans, /geo
Zone members /zone-members
Redirects /redirects
Certificates /certificates

DNS filtering — your clients and what they may resolve; personal key only:

Resource Routes
Client identities /client-identities
Sinkhole lists /sinkhole-lists, /sinkhole-roles, /sinkhole-links

Each service has its own package with its own limits.

Other:

Resource Routes
Statistics /stats/zones/…, /stats/clients/…
Audit log /audit-logs
Your account /users
Packages and usage /plans, /account
System /api/health, /api/docs/openapi.json