API Overview

Base URL: https://api.1bytedns.ru/client/v1

All endpoints return JSON responses. Every response contains a success field.

Quick Start

Create an API Token

API tokens can only be created through the web interface. Log in to your account, navigate to API Tokens, and create a new token with the desired name, permissions, scope, and expiry.

Important: The full token value is shown only once at creation time. Store it securely.

List Your Zones

curl -s https://api.1bytedns.ru/client/v1/zones \
  -H "Authorization: Bearer abc123def456ghi789jkl012mno345pqr678stu901vwx234" | python3 -m json.tool

Create a Zone

curl -s -X POST https://api.1bytedns.ru/client/v1/zones \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com", "default_ttl": 3600}'

Add a DNS Record

curl -s -X POST https://api.1bytedns.ru/client/v1/zones/42/dns_records \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "A", "name": "www.example.com", "content": "192.0.2.1", "ttl": 3600}'

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer <api_token>

Permissions

Permission	Description
zones:read	GET zones
zones:edit	POST/PATCH/DELETE zones
records:read	GET records
records:edit	POST/PATCH/DELETE records
groups:read	GET address groups
groups:edit	POST/PATCH/DELETE address groups
health:read	GET health status
health:edit	PATCH health config

Token Scope (Optional)

Tokens can be scoped to specific zones (scope_zone_ids) or records (scope_record_ids). If scope is set, requests outside the scope return 403.

Failed Authentication

{
  "success": false,
  "result": null,
  "errors": [
    {"code": 1011, "message": "Missing Authorization header"}
  ],
  "messages": []
}

Response Format

Success

{
  "success": true,
  "result": { ... },
  "errors": [],
  "messages": []
}

Error

{
  "success": false,
  "result": null,
  "errors": [
    {"code": 1001, "message": "Zone not found"}
  ],
  "messages": []
}

Paginated

{
  "success": true,
  "result": [ ... ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 5,
    "total_count": 42,
    "total_pages": 3
  },
  "errors": [],
  "messages": []
}

Success with Warnings

{
  "success": true,
  "result": { ... },
  "errors": [],
  "messages": [
    {"code": 20001, "message": "Example informational message", "type": "warn"}
  ]
}

Rate Limiting

Endpoint	Limit	Window
All (global)	1200 requests	60 seconds
Batch operations	60 requests	60 seconds
Zone creation	30 requests	60 seconds

Every response includes rate limit headers:

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1195
X-RateLimit-Reset: 1705312860

When exceeded, the API returns HTTP 429:

{
  "success": false,
  "result": null,
  "errors": [{"code": 1010, "message": "Rate limit exceeded"}],
  "messages": []
}

Error Codes

Code	HTTP	Description
1000	400	Bad Request — validation error
1001	404	Resource not found (zone, record, token)
1002	403	Access denied — resource doesn't belong to user
1003	409	User already has a zone with this name (per-user uniqueness)
1004	400	Invalid domain name
1005	400	CNAME conflict — cannot coexist with other types
1006	404	Record not found
1007	400	Invalid record data
1008	400	NS apex locked — system-managed records cannot be modified
1009	400	Zone not empty — cannot delete
1010	429	Rate limit exceeded
1011	401	Invalid or expired API token
1012	400/422	Invalid change batch
1013	404	Address group not found
1014	400	Member or group already exists
1015	400	Invalid IP address
1016	400	Maximum zones reached (300)
1017	409	IXFR requires zone transfer to be enabled first
1018	409	Cannot enable IXFR: zone has records bound to address groups
1019	409	Cannot bind address group: IXFR is enabled for this zone