Skip to content
Bitelex Docs

Records

Records are stored and written one value at a time. A record set — all values of one name and type — has no uuid of its own: it is every value with the same zone_id, name and type, and they all share one TTL. See DNS hosting.

interface RecordValue {
  uuid: string;
  zone_id: string;
  name: string;          // full owner name: "www.example.com"
  type: string;          // "A", "MX", ...
  ttl: number;           // seconds — the record set's TTL, the same on every value
  data: string;          // canonical form, e.g. "10 mail.example.com."
  geo_routing?: boolean;
  balance_ratio?: number;
  host_health: 'None' | 'Up' | 'Down' | 'Auto';
  managed_by?: 'System' | 'Redirect' | 'Acme';  // absent for your own values
  created_at: number;
  updated_at: number;
  geoBans?: GeoBan[];    // only with ?include=geoBans
}


interface RecordSet {
  zone_id: string;
  name: string;
  type: string;
  ttl: number;
  values: RecordValue[];
}

zone_id scopes every records route. With a zone key it can be left out — the key’s zone is used. With a personal key it is required.

Records Dinio keeps

Section titled “Records Dinio keeps”

A value with managed_by exists because of something else (see DNS hosting):

managed_by Through /records
System — the zone’s apex SOA/NS Can be changed. NS pointing elsewhere takes the zone off Dinio’s nameservers, so ask before you do it. The SOA and the last apex NS can’t be removed (409).
Redirect — a redirect’s CNAME/A/AAAA Change, removal and TTL change are refused with 409 MANAGED_RECORD. Change or delete the redirect.
Acme — _acme-challenge TXT during issuance Change and removal are refused with 409 MANAGED_RECORD. It goes away on its own within minutes.

Adding your own A, AAAA or CNAME at a name a redirect holds is refused with 409 MANAGED_RECORD too.

Options by type

Section titled “Options by type”

geo_routing, balance_ratio, host_health, health checks and geo bans only make sense for some record types. Setting one on another type is refused with 422:

A, AAAA SRV, MX CNAME Other types
geo_routing, balance_ratio ✓
host_health, health check ✓ ✓
Geo ban ✓ SRV only ✓

The neutral values are accepted on every type: geo_routing: false, host_health: "None", and leaving balance_ratio out. Any number in balance_ratio, 0 too, counts as set.

List record values

Section titled “List record values”
GET /api/v1/records

A flat list of values, ordered by name, type and creation, so the values of one record set come next to each other. Paginated per value: a page boundary can split a record set, so read every page, or read one set with Get a record set.

Query
zone_id Zone uuid. Required with a personal key.
name Only this full owner name.
type Only this type.
page, per_page Pagination, per_page up to 500.
Terminal window
curl -H "Authorization: Bearer $DINIO_API_KEY" \
  "https://api-dinio.bitelex.com/api/v1/records?zone_id=$ZONE_ID&type=A"
{
  "success": true,
  "data": [
    {
      "uuid": "c3f40d12-8b7e-4f5a-a1c9-2d6e8f0b3a71",
      "zone_id": "6f1c2a9e-3d4b-4c8a-9a51-0e2f7b1d4c33",
      "name": "www.example.com",
      "type": "A",
      "ttl": 300,
      "data": "192.0.2.1",
      "geo_routing": false,
      "created_at": 1760000000,
      "updated_at": 1760000000
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
}

Get a record set

Section titled “Get a record set”
GET /api/v1/records/:name

One record set by full name, as a RecordSet. type and zone_id are required query parameters (zone_id can be left out with a zone key). include=geoBans adds each value’s geoBans. Returns 404 if the set does not exist.

Terminal window
curl -H "Authorization: Bearer $DINIO_API_KEY" \
  "https://api-dinio.bitelex.com/api/v1/records/www.example.com?zone_id=$ZONE_ID&type=A&include=geoBans"

Add a value

Section titled “Add a value”
POST /api/v1/records

Adds one value. If the record set does not exist yet, this creates it — and then ttl is required. If the set exists, leave ttl out (or send the set’s current TTL); a different TTL is rejected with 422. Change a set’s TTL with Set the TTL.

Field Type
zone_id uuid
name string Full owner name, inside the zone.
type string Record type; see supported types.
data string Record data in presentation format: 192.0.2.1, 10 mail.example.com, v=spf1 -all.
ttl integer Seconds. Required only for a new record set.
geo_routing boolean Optional. A and AAAA only.
balance_ratio integer Optional, 0–65535. A and AAAA only.
host_health string Optional: None (default), Up or Down; other than None, A, AAAA, SRV and MX only. Auto is refused — create a health check for the value, which switches it to Auto.
Terminal window
curl -X POST -H "Authorization: Bearer $DINIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"zone_id":"'$ZONE_ID'","name":"www.example.com","type":"A","data":"192.0.2.1","ttl":300}' \
  https://api-dinio.bitelex.com/api/v1/records

Returns 201 with the new value, ttl included. 422 for invalid data, a TTL mismatch, or an option the type doesn’t take (see Options by type); 409 CONFLICT if the value breaks a zone rule — a duplicate value, or a CNAME next to other records; 409 MANAGED_RECORD for an A/AAAA/CNAME at a redirect’s name.

Change a value

Section titled “Change a value”
PATCH /api/v1/records/:uuid

Changes one value by its uuid. Any of data, geo_routing, balance_ratio, host_health, within the options of its type. The name, type and TTL cannot change here. 409 MANAGED_RECORD for a Redirect or Acme value.

host_health takes any of None, Up, Down, Auto (see DNS hosting); Auto needs a health check on the value, 422 otherwise. Every change of the mode resets the check’s status to UNKNOWN.

Terminal window
curl -X PATCH -H "Authorization: Bearer $DINIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"data":"192.0.2.2"}' \
  https://api-dinio.bitelex.com/api/v1/records/c3f40d12-8b7e-4f5a-a1c9-2d6e8f0b3a71

Set the TTL

Section titled “Set the TTL”
PATCH /api/v1/records/:name/ttl

Sets the TTL of a whole record set. Query zone_id; body type and ttl. Returns the record set. 409 MANAGED_RECORD for a redirect’s record set.

Terminal window
curl -X PATCH -H "Authorization: Bearer $DINIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"type":"A","ttl":600}' \
  "https://api-dinio.bitelex.com/api/v1/records/www.example.com/ttl?zone_id=$ZONE_ID"

Remove a value

Section titled “Remove a value”
DELETE /api/v1/records/:uuid

Removes one value, with its geo bans and its health check. Removing the last value removes the record set; adding to it again needs a ttl. 409 MANAGED_RECORD for a Redirect or Acme value; 409 CONFLICT for the zone’s SOA or its last apex NS.

Terminal window
curl -X DELETE -H "Authorization: Bearer $DINIO_API_KEY" \
  https://api-dinio.bitelex.com/api/v1/records/c3f40d12-8b7e-4f5a-a1c9-2d6e8f0b3a71

There is no single call that removes a whole record set: remove its values one by one. The CLI (dinio record rm … --all) and the SDKs (removeRecordGroup, ops::remove_group) do this for you, and refuse up front a set with values Dinio keeps.