API Documentation

Introduction Authentication Rate Limits Error Handling Endpoints

Subdomains Domains User Plans Stats

Examples SDKs & Libraries

API Access

API access is available exclusively to Premium plan subscribers.

View Plans

API Documentation

Our API allows you to programmatically manage your DNS subdomains and integrate our services into your applications.

API Access

API access is available exclusively to Premium plan subscribers. Upgrade your plan to access the API.

Base URL

https://freedns.ccom.one/api/v1

All API requests must use HTTPS. HTTP requests will be rejected.

Authentication

All API requests require authentication using an API key. You can create and manage your API keys in the API Keys section of your dashboard.

To authenticate your requests, include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Security Note

Keep your API keys secure and do not share them publicly. Anyone with your API key can access and modify your subdomains.

Rate Limits

To ensure a fair usage of the API, we apply rate limits to all API requests:

Plan	Rate Limit	Daily Limit
Premium	100 requests per minute	5,000 requests per day

If you exceed these limits, the API will return a 429 Too Many Requests response. The response will include headers indicating your remaining quota and when the limit will reset.

Rate Limit Headers

Header	Description
`X-RateLimit-Limit`	The maximum number of requests you're permitted to make per minute
`X-RateLimit-Remaining`	The number of requests remaining in the current rate limit window
`X-RateLimit-Reset`	The time at which the current rate limit window resets (UTC epoch seconds)

Error Handling

When an error occurs, the API will return an appropriate HTTP status code along with a JSON response that provides more information about the error.

Error Response Format

{
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Missing required field: name"
  }
}

Common Error Codes

Status Code	Description
`400 Bad Request`	The request was malformed or missing required parameters
`401 Unauthorized`	Authentication failed (invalid or missing API key)
`403 Forbidden`	The authenticated user does not have permission to perform the requested action
`404 Not Found`	The requested resource does not exist
`409 Conflict`	The request conflicts with the current state of the resource
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	An unexpected error occurred on the server

Endpoints

The API provides the following endpoints to manage your subdomains and access account information.

Subdomains

GET /subdomains

List Subdomains

Returns a list of all subdomains owned by the authenticated user.

Query Parameters

Parameter	Type	Description
`limit`	Integer	Maximum number of subdomains to return (default: 100)
`offset`	Integer	Number of subdomains to skip (default: 0)
`active`	Boolean	Filter by active status (true/false)

Example Response

{
  "data": {
    "subdomains": [
      {
        "id": 123,
        "name": "test",
        "domain": "example.com",
        "full_domain": "test.example.com",
        "type": "A",
        "content": "192.168.1.1",
        "ttl": 3600,
        "proxied": true,
        "active": true,
        "created_at": "2023-01-01T12:00:00Z",
        "updated_at": "2023-01-01T12:00:00Z"
      },
      // ... more subdomains
    ],
    "pagination": {
      "total": 15,
      "limit": 10,
      "offset": 0
    }
  }
}

GET /subdomains/{id}

Get Subdomain

Returns the details of a specific subdomain.

Path Parameters

Parameter	Type	Description
`id`	Integer	The ID of the subdomain to retrieve

Example Response

{
  "data": {
    "id": 123,
    "name": "test",
    "domain": "example.com",
    "full_domain": "test.example.com",
    "type": "A",
    "content": "192.168.1.1",
    "ttl": 3600,
    "proxied": true,
    "active": true,
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
}

POST /subdomains

Create Subdomain

Creates a new subdomain.

Request Body

Parameter	Type	Required	Description
`name`	String	Yes	The subdomain name (without the domain part)
`domain_id`	Integer	Yes	The ID of the domain
`type`	String	Yes	The DNS record type (A, AAAA, CNAME, TXT, MX)
`content`	String	Yes	The content of the DNS record
`ttl`	Integer	No	Time to live in seconds (default: 3600)
`proxied`	Boolean	No	Whether to proxy through Cloudflare (default: false)

Example Request

{
  "name": "test",
  "domain_id": 1,
  "type": "A",
  "content": "192.168.1.1",
  "ttl": 3600,
  "proxied": true
}

Example Response

{
  "data": {
    "id": 123,
    "name": "test",
    "domain": "example.com",
    "full_domain": "test.example.com",
    "type": "A",
    "content": "192.168.1.1",
    "ttl": 3600,
    "proxied": true,
    "active": true,
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
}

PUT /subdomains/{id}

Update Subdomain

Updates an existing subdomain.

Path Parameters

Parameter	Type	Description
`id`	Integer	The ID of the subdomain to update

Request Body

Parameter	Type	Required	Description
`type`	String	No	The DNS record type (A, AAAA, CNAME, TXT, MX)
`content`	String	No	The content of the DNS record
`ttl`	Integer	No	Time to live in seconds
`proxied`	Boolean	No	Whether to proxy through Cloudflare
`active`	Boolean	No	Whether the subdomain is active

Example Request

{
  "content": "192.168.1.2",
  "proxied": false
}

Example Response

{
  "data": {
    "id": 123,
    "name": "test",
    "domain": "example.com",
    "full_domain": "test.example.com",
    "type": "A",
    "content": "192.168.1.2",
    "ttl": 3600,
    "proxied": false,
    "active": true,
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:30:00Z"
  }
}

DELETE /subdomains/{id}

Delete Subdomain

Deletes a subdomain.

Path Parameters

Parameter	Type	Description
`id`	Integer	The ID of the subdomain to delete

Response

Returns a 204 No Content status code on success.

Domains

GET /domains

List Domains

Returns a list of all available domains for the authenticated user.

Example Response

{
  "data": [
    {
      "id": 1,
      "domain": "example.com",
      "description": "Our primary free domain",
      "premium": false,
      "created_at": "2023-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "domain": "premium.example.com",
      "description": "Premium domain for paid plans",
      "premium": true,
      "created_at": "2023-01-01T00:00:00Z"
    }
  ]
}

GET /domains/{id}

Get Domain

Returns the details of a specific domain.

Path Parameters

Parameter	Type	Description
`id`	Integer	The ID of the domain to retrieve

Example Response

{
  "data": {
    "id": 1,
    "domain": "example.com",
    "description": "Our primary free domain",
    "premium": false,
    "created_at": "2023-01-01T00:00:00Z"
  }
}

User

GET /user

Get User Info

Returns information about the authenticated user.

Example Response

{
  "data": {
    "id": 123,
    "username": "johndoe",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "user",
    "plan": {
      "name": "Premium",
      "max_subdomains": 100,
      "can_use_premium": true
    },
    "subdomains": {
      "used": 5,
      "available": 95
    },
    "subscription": {
      "id": 456,
      "start_date": "2023-01-01T00:00:00Z",
      "end_date": "2024-01-01T00:00:00Z",
      "status": "completed"
    },
    "created_at": "2022-01-01T00:00:00Z"
  }
}

Plans

GET /plans

List Plans

Returns a list of all available subscription plans.

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "Free",
      "description": "Basic free plan with limited features",
      "price": 0,
      "billing_cycle": "monthly",
      "max_subdomains": 3,
      "features": {
        "can_use_premium": false,
        "custom_dns": false,
        "priority_support": false,
        "ad_free": false,
        "api_access": false
      }
    },
    {
      "id": 4,
      "name": "Premium",
      "description": "Premium plan with unlimited features",
      "price": 9.99,
      "billing_cycle": "monthly",
      "max_subdomains": 100,
      "features": {
        "can_use_premium": true,
        "custom_dns": true,
        "priority_support": true,
        "ad_free": true,
        "api_access": true
      }
    }
  ]
}

Stats

GET /stats

Get User Stats

Returns statistics about the authenticated user's account.

Example Response

{
  "data": {
    "subdomains": {
      "total": 5,
      "active": 4,
      "inactive": 1
    },
    "domains": {
      "total": 2
    },
    "by_type": {
      "A": 3,
      "CNAME": 1,
      "TXT": 1
    },
    "recent_activity": [
      {
        "id": 123,
        "full_domain": "test.example.com",
        "type": "A",
        "active": true,
        "updated_at": "2023-01-01T12:30:00Z"
      },
      // ... more activities
    ]
  }
}

Examples

Here are some examples of how to use the API with different programming languages:

cURL

curl -X GET \
  'https://freedns.ccom.one/api/v1/subdomains' \
  -H 'Authorization: Bearer YOUR_API_KEY'

JavaScript (Fetch API)

fetch('https://freedns.ccom.one/api/v1/subdomains', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Python (Requests)

import requests

url = 'https://freedns.ccom.one/api/v1/subdomains'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

PHP (cURL)

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://freedns.ccom.one/api/v1/subdomains');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

curl_close($ch);
print_r($data);

Have questions about the API? Contact us for support.