REST API Reference

Complete reference for the ResolveDB REST API.

Base URL

All API requests should be made to:

https://api.resolvedb.io/api/v1

Authentication

The ResolveDB API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Bearer Token

Authorization: Bearer YOUR_API_KEY

Getting API Keys

Generate API keys from the API Keys section of your dashboard. Each key has configurable permissions and can be revoked at any time.

Important: API key tokens are only displayed once upon creation. Store them securely. If you lose a key, you must generate a new one.

Example Request

curl https://api.resolvedb.io/api/v1/me \
  -H "Authorization: Bearer rdb_live_abc123..."

Records

Records are the core data objects in ResolveDB. Each record is addressable via DNS and contains Base64-encoded data.

List Records

GET /records

List all records for the authenticated user. Supports filtering by namespace and resource.

Query Parameters:

Parameter	Type	Description
namespace	string	Filter by namespace
resource	string	Filter by resource name
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 25, max: 100)

Example Request:

curl "https://api.resolvedb.io/api/v1/records?namespace=myapp&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "records": [
    {
      "id": "rec_abc123",
      "key": "config.myapp.v1",
      "data": "eyJkYXRhYmFzZSI6InBvc3RncmVzIn0=",
      "namespace": "myapp",
      "resource": "config",
      "version": "v1",
      "ttl": 3600,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 1,
    "total_pages": 1
  }
}

Get Record

GET /records/:id

Retrieve a single record by ID.

Path Parameters:

Parameter	Type	Description
id	string	Record ID (e.g., rec_abc123)

Example Request:

curl https://api.resolvedb.io/api/v1/records/rec_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "record": {
    "id": "rec_abc123",
    "key": "config.myapp.v1",
    "data": "eyJkYXRhYmFzZSI6InBvc3RncmVzIn0=",
    "namespace": "myapp",
    "resource": "config",
    "version": "v1",
    "ttl": 3600,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Create Record

POST /records

Create a new record. The data field must be Base64 encoded.

Request Body:

Field	Type	Required	Description
record.key	string	Yes	DNS key (format: resource.namespace.version)
record.data	string	Yes	Base64 encoded data
record.ttl	integer	No	Cache TTL in seconds (default: 3600)

Example Request:

curl -X POST https://api.resolvedb.io/api/v1/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record": {
      "key": "config.myapp.v1",
      "data": "eyJkYXRhYmFzZSI6InBvc3RncmVzIn0=",
      "ttl": 3600
    }
  }'

Response:

{
  "record": {
    "id": "rec_abc123",
    "key": "config.myapp.v1",
    "data": "eyJkYXRhYmFzZSI6InBvc3RncmVzIn0=",
    "namespace": "myapp",
    "resource": "config",
    "version": "v1",
    "ttl": 3600,
    "dns_query": "get.config.myapp.v1.resolvedb.net",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Update Record

PATCH /records/:id

Update an existing record. Only include fields you want to change.

Path Parameters:

Parameter	Type	Description
id	string	Record ID

Request Body:

Field	Type	Description
record.data	string	New Base64 encoded data
record.ttl	integer	New cache TTL in seconds

Example Request:

curl -X PATCH https://api.resolvedb.io/api/v1/records/rec_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record": {
      "data": "eyJkYXRhYmFzZSI6Im15c3FsIn0=",
      "ttl": 7200
    }
  }'

Response:

{
  "record": {
    "id": "rec_abc123",
    "key": "config.myapp.v1",
    "data": "eyJkYXRhYmFzZSI6Im15c3FsIn0=",
    "namespace": "myapp",
    "resource": "config",
    "version": "v1",
    "ttl": 7200,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:45:00Z"
  }
}

Delete Record

DELETE /records/:id

Delete a record. This action is permanent.

Path Parameters:

Parameter	Type	Description
id	string	Record ID

Example Request:

curl -X DELETE https://api.resolvedb.io/api/v1/records/rec_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

Returns HTTP 204 No Content on success.

API Keys

Manage API keys for programmatic access to the ResolveDB API.

List API Keys

GET /api_keys

List all API keys for the authenticated user. Note: The actual token values are not returned for security reasons.

Example Request:

curl https://api.resolvedb.io/api/v1/api_keys \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "api_keys": [
    {
      "id": "key_xyz789",
      "name": "Production API Key",
      "prefix": "rdb_live_abc",
      "scopes": ["read", "write"],
      "last_used_at": "2024-01-15T09:00:00Z",
      "expires_at": null,
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "key_def456",
      "name": "CI/CD Pipeline",
      "prefix": "rdb_live_def",
      "scopes": ["read"],
      "last_used_at": "2024-01-14T18:30:00Z",
      "expires_at": "2024-12-31T23:59:59Z",
      "created_at": "2024-01-10T12:00:00Z"
    }
  ]
}

Create API Key

POST /api_keys

Create a new API key. The full token is only returned once in this response - store it securely.

Request Body:

Field	Type	Required	Description
api_key.name	string	Yes	Descriptive name for the key
api_key.scopes	array	No	Permissions: read, write (default: both)
api_key.expires_at	string	No	ISO 8601 expiration date

Example Request:

curl -X POST https://api.resolvedb.io/api/v1/api_keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "name": "Production API Key",
      "scopes": ["read", "write"],
      "expires_at": "2025-12-31T23:59:59Z"
    }
  }'

Response:

Important: The token field is only returned once. Store it immediately in a secure location.

{
  "api_key": {
    "id": "key_xyz789",
    "name": "Production API Key",
    "token": "rdb_live_abc123def456ghi789...",
    "prefix": "rdb_live_abc",
    "scopes": ["read", "write"],
    "expires_at": "2025-12-31T23:59:59Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Revoke API Key

DELETE /api_keys/:id

Revoke an API key. This action is immediate and permanent. Any requests using this key will be rejected.

Path Parameters:

Parameter	Type	Description
id	string	API key ID

Example Request:

curl -X DELETE https://api.resolvedb.io/api/v1/api_keys/key_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

Returns HTTP 204 No Content on success.

Account

Endpoints for managing your account and retrieving profile information.

Get Current User

GET /me

Get the current authenticated user's profile information.

Example Request:

curl https://api.resolvedb.io/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "user": {
    "id": "usr_abc123",
    "email": "developer@example.com",
    "name": "Jane Developer",
    "plan": "pro",
    "records_count": 42,
    "records_limit": 10000,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Error Handling

The API uses conventional HTTP response codes to indicate success or failure of requests. Errors include a JSON body with details.

Error Response Format

{
  "error": {
    "code": "validation_error",
    "message": "The request body contains invalid data",
    "details": [
      {
        "field": "record.key",
        "message": "is required"
      }
    ]
  }
}

HTTP Status Codes

Code	Name	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded, no body returned
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks required scope
404	Not Found	Resource does not exist
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error (contact support)

Error Codes

Code	Description
authentication_error	Invalid or missing API key
authorization_error	API key lacks required permissions
validation_error	Request body failed validation
not_found	Requested resource does not exist
rate_limit_exceeded	Too many requests
quota_exceeded	Account record limit reached
server_error	Internal server error

DNS Error Code Mapping

When querying records via DNS, errors are returned as UQRP status codes. See UQRP Protocol - Error Codes for the complete mapping (E001-E017).

API Error	DNS Status	DNS Error Code
authentication_error	`auth`	E006, E007, E008
authorization_error	`forbidden`	E009
validation_error	`invalid`	E001, E002, E003
not_found	`notfound`	E004, E005
rate_limit_exceeded	`ratelimit`	E010
server_error	`error`	E012

Rate Limits

API requests are rate limited to ensure fair usage and system stability. Limits vary by plan and endpoint type.

Rate Limit Headers

Every response includes headers indicating your current rate limit status:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Limits by Plan

Plan	Requests/min	Records
Free	60	100
Pro	600	10,000
Enterprise	Custom	Unlimited

Handling Rate Limits

When rate limited, the API returns HTTP 429. Implement exponential backoff:

// Example: Exponential backoff in JavaScript
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitMs = (resetTime * 1000) - Date.now();
      await new Promise(r => setTimeout(r, Math.max(waitMs, 1000 * (i + 1))));
      continue;
    }

    return response;
  }
  throw new Error('Rate limit exceeded after retries');
}

Next Steps

Quickstart Guide - Get up and running in 5 minutes
UQRP Protocol - Learn the DNS query format
Security - Authentication and encryption options