API Reference

This section provides detailed documentation for all PocketDNS API endpoints, including request/response formats, parameters, and examples.

OpenAPI Specification

The complete API specification is available as an OpenAPI document:

📄 partner-api.yml - Complete OpenAPI 3.0 specification
🚀 Interactive API Documentation - Try the API directly in your browser

You can use this specification to:

• Try API calls interactively with our embedded Swagger UI
• Generate client SDKs in your preferred language
• Import into API testing tools (Postman, Insomnia, etc.)
• Validate requests and responses

Interactive Documentation

Visit our Interactive API Documentation page to:

• Explore all endpoints with a user-friendly interface
• Test API calls directly from your browser
• View detailed request/response examples
• Download the specification in various formats

Using the OpenAPI Spec

Client Generation: Use OpenAPI Generator to create client libraries:

npx @openapitools/openapi-generator-cli generate -i partner-api.yml -g typescript-fetch -o ./sdk

Postman Collection: Import the OpenAPI file directly into Postman for API testing.

Base URLs

Environment	Base URL
Sandbox	https://api.sandbox.pocketdns.com
Production	https://api.pocketdns.com

Authentication

All API requests require authentication using Bearer tokens:

Authorization: Bearer YOUR_API_KEY

User Management

Create User Session

Creates or finds a user and generates a session token for embedding the domain interface.

Endpoint: POST /api/v1/users

Request Body:

{
  "user_identifier": "string",  // Required: Your unique user ID
  "email": "string"             // Optional: User's email address
}

Response (201 Created):

{
  "user_identifier": "string",
  "login_url": "string"         // Valid for 24 hours
}

Example:

curl -X POST https://api.pocketdns.com/api/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_identifier": "user-123",
    "email": "[email protected]"
  }'

Domain Management

Get User Domains

Retrieves all domains owned by a specific user.

Endpoint: GET /api/v1/users/{user_id}/domains

Parameters:

• user_id (path, required): The user identifier

Response (200 OK):

{
  "domains": [
    {
      "id": "domain-uuid",
      "name": "example.com"
    }
  ]
}

Example:

curl -X GET https://api.pocketdns.com/api/v1/users/user-123/domains \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Domain Details

Retrieves detailed information about a specific domain.

Endpoint: GET /api/v1/domains/{domain_id}

Parameters:

• domain_id (path, required): The domain ID

Response (200 OK):

{
  "id": "domain-uuid",
  "name": "example.com"
}

Example:

curl -X GET https://api.pocketdns.com/api/v1/domains/domain-uuid \
  -H "Authorization: Bearer YOUR_API_KEY"

DNS Records Management

Create DNS Record

Creates a new DNS record for a domain.

Endpoint: POST /api/v1/dns_records

Request Body:

{
  "domain_id": "string",     // Required
  "type": "string",          // Required: A, AAAA, CNAME, MX, TXT
  "name": "string",          // Required: Record name (@ for root)
  "value": "string",         // Required: Record value
  "ttl": 3600,              // Optional: Time to live (default: 3600)
  "priority": 10,           // Optional: For MX records
  "weight": 0,              // Optional: For SRV records
  "port": 80,               // Optional: For SRV records
  "target": "string"        // Optional: For SRV records
}

Response (201 Created):

{
  "id": "record-uuid",
  "type": "A",
  "name": "@",
  "value": "192.168.1.1",
  "ttl": 3600
}

Get DNS Record

Retrieves a specific DNS record.

Endpoint: GET /api/v1/dns_records/{id}

Parameters:

• id (path, required): The DNS record ID

Response (200 OK):

{
  "id": "record-uuid",
  "type": "A",
  "name": "@",
  "value": "192.168.1.1",
  "ttl": 3600
}

Update DNS Record

Updates an existing DNS record.

Endpoint: PATCH /api/v1/dns_records/{id}

Parameters:

• id (path, required): The DNS record ID

Request Body:

{
  "type": "string",          // Optional
  "name": "string",          // Optional
  "value": "string",         // Optional
  "ttl": 3600,              // Optional
  "priority": 10,           // Optional
  "weight": 0,              // Optional
  "port": 80,               // Optional
  "target": "string"        // Optional
}

Response (200 OK):

{
  "id": "record-uuid",
  "type": "A",
  "name": "@",
  "value": "192.168.1.1",
  "ttl": 3600
}

Delete DNS Record

Deletes a DNS record.

Endpoint: DELETE /api/v1/dns_records/{id}

Parameters:

• id (path, required): The DNS record ID

Response (204 No Content): Empty response body

Error Responses

All error responses follow a consistent format:

Standard Error Response

{
  "errors": [
    "Error message 1",
    "Error message 2"
  ]
}

HTTP Status Codes

Code	Description	Common Causes
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Resource deleted successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource doesn't exist
422	Unprocessable Entity	Validation errors
500	Internal Server Error	Server-side error

Example Error Handling

try {
  const response = await fetch('/api/v1/users', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestData)
  });

  if (!response.ok) {
    if (response.status === 422) {
      const errorData = await response.json();
      throw new Error(`Validation errors: ${errorData.errors.join(', ')}`);
    }
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data = await response.json();
  return data;

} catch (error) {
  console.error('API Error:', error);
  throw error;
}

Rate Limits

API calls are subject to rate limiting:

• Default: 1000 requests per hour per API key
• Burst: Up to 100 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

API Libraries

JavaScript/TypeScript

npm install @pocketdns/sdk

import { PocketDNS } from '@pocketdns/sdk';

const client = new PocketDNS({
  apiKey: 'your-api-key',
  environment: 'production' // or 'sandbox'
});

const session = await client.users.createSession({
  user_identifier: 'user-123',
  email: '[email protected]'
});

Python

pip install pocketdns-python

from pocketdns import PocketDNS

client = PocketDNS(
    api_key='your-api-key',
    environment='production'
)

session = client.users.create_session(
    user_identifier='user-123',
    email='[email protected]'
)

Need another language?

Contact our support team at [email protected] for additional SDK requests.