# Cacholong API documentation > Version 1.0 · Base URL `https://api.cacholong.eu/api/v1` This document and the files it links are generated from the OpenAPI description published alongside them. They exist so automated consumers can read the API documentation without executing JavaScript. Everything below is also available as a single document: [llms-full.txt](llms-full.txt). ## Endpoints - [Accounts](md/accounts.md) — Manage accounts; 3 operations - [Addresses](md/addresses.md) — Manage addresses for users and companies; 7 operations - [Companies](md/companies.md) — Manage companies; 4 operations - [Dns Records](md/dns-records.md) — Manage DNS records; 5 operations - [Dns Templates](md/dns-templates.md) — Manage DNS templates; 5 operations - [Dns Zone Restore Points](md/dns-zone-restore-points.md) — Manage DNS zone restore points (snapshots for rollback); 8 operations - [Dns Zones](md/dns-zones.md) — Manage DNS zones; 5 operations - [Inbox Messages](md/inbox-messages.md) — Read your received messages; 2 operations - [Mail Address Aliases](md/mail-address-aliases.md) — Manage mail address aliases; 6 operations - [Mail Addresses](md/mail-addresses.md) — Manage mail addresses; 7 operations - [Mail Domains](md/mail-domains.md) — Manage mail domains; 5 operations - [Mail Forwards](md/mail-forwards.md) — Manage mail forwards; 7 operations - [Products](md/products.md) — Manage products; 2 operations - [Purchases](md/purchases.md) — Manage purchases; 3 operations - [Service Bundles](md/service-bundles.md) — A service bundle is a named set of services that together deliver a product. It works as the "recipe": it states which PHP versions, which nginx, which MySQL and so on are used, and therefore on which servers or at which provider a product ends up. **How products, service bundles, services and service groups fit together:** These resources describe two different things: - **What the platform can deliver** (configuration, maintained by Cacholong): services, service options and service bundles. - **What a customer has bought** (created automatically when ordering): service groups. ``` Product ──(linked to one or more)──▶ Service bundle ──(contains)──▶ Services ──(configured by)──▶ Service options │ ▲ │ │ order │ records which bundle └─▶ runs on program instances (servers) ▼ │ was used and/or external service providers Purchase ──(creates)──▶ Service group ─────┘ │ └─▶ groups the delivered resources: web hosting, OS user, nginx vhosts, PHP pools, MySQL databases, SSL certificates, … ``` A **product** is what you order, a **service bundle** decides where and how it is delivered, the **services** in that bundle are the building blocks, **service options** tune those building blocks, and the **service group** holds everything delivered for one order. **Bundles and products:** - A bundle is linked to one or more products, and a product can be linked to one or more bundles. A hosting product can be deliverable on two web clusters, where each cluster is its own bundle. - A bundle is either **global** (no account, available to every account) or **account-specific** (for example dedicated infrastructure for one customer). You see global bundles and the bundles of your own accounts. - When a service is picked from a bundle by category and version, the newest matching version is used. **Choosing a bundle when ordering:** When you create a purchase (`domain-registrations`, `dns-zones`, `vps`, `web-hostings`, `ssl-certificates`, standalone `web-redirects`), the system decides which bundle delivers it: - If exactly one bundle of the product is available to your account, it is chosen automatically and you do not need to send anything. - If two or more are available, you must choose one by sending the `service-bundle` relationship. Leaving it out returns **422**. - The available bundles are listed at `GET /products/{product_id}/service-bundles`. The choice is made once, at creation, and cannot be changed afterwards. **Worked example:** 1. Product **Enterprise Hosting Bronze** is linked to two bundles, *Webcluster A* and *Webcluster B*. 2. *Webcluster A* contains the services nginx, PHP 8.2, PHP 8.3, MySQL, OS user and SSL, each tied to the servers of cluster A. The OS user service has service options that set the allowed shells and the home directory prefix. 3. A customer orders the product through `POST /web-hostings`. Two bundles are available, so they send `service-bundle` = *Webcluster A*. 4. A purchase and a service group are created. The service group records the account, the purchase and *Webcluster A*. 5. The web hosting, its OS user, vhosts and PHP pools are created on cluster A, and all of them belong to that service group. Anything added to this hosting later also ends up on cluster A. ; 8 operations - [Tlds](md/tlds.md) — Top-level domains available for domain registration; 2 operations - [Users](md/users.md) — Manage users; 2 operations ## Introduction The Cacholong API provides comprehensive programmatic access to manage your hosting infrastructure and services. All functionality available in the control panel at https://cp.cacholong.eu is accessible through this API. **Note:** Not all endpoints are publicly available yet. Only the endpoints visible in this documentation are currently available for use. Additional endpoints will be released progressively as they become ready for production use. This API enables you to manage: - **DNS Management**: DNS zones, DNS records, DNS templates, DNSSEC configurations, nameserver groups - **Web Hosting**: Hosting environments, VPS instances, Nginx virtual hosts, PHP pool configurations, web redirects - **Email Services**: Mail domains, mail addresses, mail aliases, mail forwards - **Database Services**: MySQL databases and database user grants - **SSL/TLS Certificates**: Certificate management with automatic renewal support - **Domain Registration**: Domain management, TLDs, domain contacts - **User & Account Management**: Users, companies, accounts, user groups, roles, permissions, addresses - **Authentication**: API tokens, TOTP authentication, WebAuthn, login IP restrictions - **Infrastructure**: Servers, services, service groups, SSH keys - **Firewall Management**: Account firewall rules - **Billing**: Purchases, contracts, invoices, payments, mailings - **Activity Logging**: Activity logs, ESP activities, communications The API follows the JSON:API 1.0 specification and is documented using the OpenAPI 3.1 standard. This introduction provides an overview of authentication, versioning, request patterns, and response structures, followed by detailed reference information for all available endpoints. ### Authentication The Cacholong API uses HTTP Bearer token authentication. All API requests must include a valid API token in the `Authorization` header. #### Creating API Tokens API tokens can be created through the control panel at https://cp.cacholong.eu/#/user/settings/api. Each token is displayed only once upon creation and must be saved immediately. Tokens are used to authenticate automated scripts, CI/CD pipelines, mobile applications, and production servers. #### Authentication Header Include your API token in the `Authorization` header using the Bearer scheme: ```http GET /api/v1/dns-zones?filter[name]=example.com HTTP/1.1 Host: api.cacholong.eu Authorization: Bearer 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f Accept: application/vnd.api+json ``` #### Required Headers All API requests must include the following headers: - `Accept: application/vnd.api+json` - Specifies the expected response format - `Content-Type: application/vnd.api+json` - Required for POST and PATCH requests with a request body #### Multi-Factor Authentication For enhanced account security, multi-factor authentication (MFA) is supported using TOTP (Time-based One-Time Password) or WebAuthn (hardware security keys). MFA protects your account while API tokens provide secure programmatic access. ### Versioning Strategy The Cacholong API uses URL-based versioning to ensure stability and backward compatibility. #### Current Version - **API Version**: v1.0 - **Base URL**: `https://api.cacholong.eu/api/v1` - **JSON:API Version**: 1.0 (indicated in all responses as `jsonapi.version: "1.0"`) #### Versioning Policy - **Backward Compatibility**: The API maintains backward compatibility within major versions (v1.x). No breaking changes will be introduced in minor version updates. - **Deprecation Notice**: Features scheduled for removal receive a minimum 3-month advance notice. Deprecated endpoints and fields are marked with `deprecated: true` in the OpenAPI specification and include clear deprecation notices in their descriptions. - **Migration Support**: When upgrading between major versions, migration documentation is provided to help transition your integrations smoothly. The version number in the URL path ensures that your integrations remain stable even as new API versions are released. ### JSON:API standard JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should response to those requests. It is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility or discoverability. Because JSON:API is an official standard it has registered a media type (application/vnd.api+json). Because of that you need to send the header Accept or Content-Type with this value. ### Requests Cacholong API makes use of JSON to process client requests in accordance with the JSON:API specification. #### Request body structure Every `POST` and `PATCH` request body must contain a single resource object under the top-level `data` member. The resource object holds `type`, `id` (on update), `attributes`, `relationships` and `meta`. ```http POST /api/v1/dns-zones HTTP/1.1 Accept: application/vnd.api+json Content-Type: application/vnd.api+json { "data": { "type": "dns-zones", "attributes": { "domain": "example.com" }, "relationships": { "account": { "data": { "type": "accounts", "id": "16aeda2f-f1e5-4407-b7dd-e2862a9fb85f" } } } } } ``` On update, `type` and `id` are required and must match the resource being addressed by the URL. ```http PATCH /api/v1/dns-zones/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f HTTP/1.1 Accept: application/vnd.api+json Content-Type: application/vnd.api+json { "data": { "type": "dns-zones", "id": "16aeda2f-f1e5-4407-b7dd-e2862a9fb85f", "attributes": { "dnssec": true } } } ``` Omitting the `data` member returns **400 Bad Request**. A request body that sends `type`, `attributes` or `relationships` at the top level, without wrapping them in `data`, is not valid JSON:API and is rejected. Options that control how a request is processed rather than what it contains — such as `sync` — live in the resource object's `meta` member, at `data.meta`. ```http POST /api/v1/dns-zones HTTP/1.1 Accept: application/vnd.api+json Content-Type: application/vnd.api+json { "data": { "type": "dns-zones", "attributes": { "domain": "example.com" }, "meta": { "sync": true } } } ``` Relationship linkage endpoints (`/{resource}/{id}/relationships/{relationship}`) also use the top-level `data` member, but carry resource identifier objects (`type` and `id` only) instead of a full resource object. ### Query Parameters Query parameters can be used to limit or filter the results returned by the API. Query parameters are optional and can be combined to get specific results. #### Fields Limit the fields returned by the API. If fields is not given all available fields are returned. ```http GET /api/v1/dns-zones?fields[dns-zones]=name,status HTTP/1.1 Accept: application/vnd.api+json ``` This request will return all DNS zones with fields `name` and `status`. ```http GET /api/v1/users?fields[users]=name,email HTTP/1.1 Accept: application/vnd.api+json ``` This request will return all users with fields `name` and `email`. #### Pagination Determine the amount of results with `page[size]` and which page to show with `page[number]`. If `page[size]` is not given, a default number of results will be returned (typically 10-15, varies by endpoint). If `page[number]` is not given, the request will return page **1**. ```http GET /api/v1/dns-zones?page[size]=10 HTTP/1.1 Accept: application/vnd.api+json ``` This request will return DNS zones with a page size of **10**. ```http GET /api/v1/dns-zones?page[number]=2 HTTP/1.1 Accept: application/vnd.api+json ``` This request will return page **2** of DNS zones. #### Sorting Sorting allows a client to specify the order in which resources are returned from the API. Sorting can be done ascending or descending (prepend with `-`). ```http GET /api/v1/dns-zones?sort=name HTTP/1.1 Accept: application/vnd.api+json ``` This request will sort DNS zones by `name` in ascending order. ```http GET /api/v1/dns-zones?sort=-created_at HTTP/1.1 Accept: application/vnd.api+json ``` This request will sort DNS zones by `created_at` in descending order (newest first). ```http GET /api/v1/dns-zones?sort=status,-created_at HTTP/1.1 Accept: application/vnd.api+json ``` This request will sort DNS zones first by `status` ascending, then by `created_at` descending. **Note**: There is limited support for sorting on related fields. Sorting on polymorphic or recursive relations is not supported. #### Filters Filters can be used to limit the amount of results for an index query. Filters can be combined to make more specific queries to the Cacholong API. ##### String fields Searched with operator **ILIKE** (case-insensitive). If the value does not have a wildcard `%`, it is automatically surrounded with wildcards. ```http GET /api/v1/dns-zones?filter[name]=example.com HTTP/1.1 Accept: application/vnd.api+json ``` Will filter DNS zones on `name` with value **example.com**. Because no wildcard is present, the value will be surrounded with wildcards (`%example.com%`). ##### Date fields Date filters support the following mutators: - `_eq`: Date must be equal to given date (same as without mutator) - `_gt`: Date must be greater than given date - `_gte`: Date must be greater than or equal to given date - `_lt`: Date must be less than given date - `_lte`: Date must be less than or equal to given date ```http GET /api/v1/dns-zones?filter[created_at_gte]=2026-01-01 HTTP/1.1 Accept: application/vnd.api+json ``` Will filter DNS zones where `created_at` is greater than or equal to **2026-01-01**. ##### Numeric fields Numeric filters allow integers or floats depending on the field. Supported mutators: - `_eq`: Number must be equal to given number (same as without mutator) - `_gt`: Number must be greater than given number - `_gte`: Number must be greater than or equal to given number - `_lt`: Number must be less than given number - `_lte`: Number must be less than or equal to given number **Float formatting rules**: Decimal separator can be comma or point. Thousand separators are not supported. Negative numbers are supported. Invalid formats: `.1`, `,1`, `1.`, `1,`, `10.000,00`, `10,000.00`. ##### Nullable filters Nullable filters query resources based on whether a specific field is `null` or not. These filters accept `true` or `false` values using the `_is_null` suffix. ```http GET /api/v1/companies?filter[kvknr_is_null]=true HTTP/1.1 Accept: application/vnd.api+json ``` Returns all companies where the `kvknr` field is `null`. Use `false` to filter records where the field is not `null`. ##### ID and relationship fields ID and relationship filters require exact values. Multiple values can be provided as comma-separated lists. ```http GET /api/v1/dns-zones?filter[id]=16aeda2f-f1e5-4407-b7dd-e2862a9fb85f HTTP/1.1 Accept: application/vnd.api+json ``` Filter DNS zones by exact `id`. ```http GET /api/v1/dns-records?filter[dns-zone]=16aeda2f-f1e5-4407-b7dd-e2862a9fb85f HTTP/1.1 Accept: application/vnd.api+json ``` Filter DNS records by related `dns-zone` ID. Multiple IDs can be provided by separating them with commas. Most relationship fields support comma-separated values to search for multiple related resources at once. #### Include Include can be used to allow the client to customize which related resources should be returned from the API. Related resources are included in the `included` array of the response. ```http GET /api/v1/dns-zones?include=dns-records HTTP/1.1 Accept: application/vnd.api+json ``` Include related DNS records with the request for DNS zones. ```http GET /api/v1/dns-zones/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f?include=dns-records HTTP/1.1 Accept: application/vnd.api+json ``` Include related DNS records with the specific DNS zone. ##### Account visibility of included resources Included resources and relationship linkage (`relationships..data`) only contain records you are allowed to see. This applies to every endpoint and every include depth (for example `GET /api/v1/services?include=service-bundles.products`), and also to the response of a `POST` or `PATCH` request with `include`. | Resource type | Not a superadmin | Superadmin | |---|---|---| | `service-bundles` | Global bundles (no account) and bundles of your own accounts | All bundles. With `filter[account]`: global bundles and bundles of the filtered accounts | | `products` | Global products, products of your own accounts and products of the direct parent account of one of your accounts | All products. `filter[account]` does not narrow them | | `user-roles` | Roles in your own accounts. With `filter[account]`: roles in the filtered accounts | All roles. With `filter[account]`: roles in the filtered accounts | | `contracts` | Contracts of your own accounts, and contracts without an account that you are a contract user of | All contracts | | `contract-users` | Your own contract users | All contract users | | `nginx-vhost-templates` | Global templates (no account) and templates of your own accounts | All templates | - A to-one relationship to a record you cannot see is returned as `"data": null`, as if it were empty, and the record is not added to `included`. - Records you cannot see are left out of a to-many relationship and of `included`; the other records are returned as usual. - `filter[account]` narrows included resources on every endpoint that accepts it. - Exception: the `user-roles` of an account (`GET /api/v1/accounts?include=user-roles` or `GET /api/v1/accounts/{id}?include=user-roles`) always contain only your own roles on that account. This applies to every user, including superadmins. ```http GET /api/v1/purchases?filter[account]=16aeda2f-f1e5-4407-b7dd-e2862a9fb85f&include=product HTTP/1.1 Accept: application/vnd.api+json ``` When the product of a purchase belongs to an account you cannot see, that purchase's `relationships.product.data` is `null` and the product is not included. ### Responses The API returns responses in JSON:API format, structured according to the JSON:API 1.0 specification. Response structure varies based on the type of request and operation outcome. #### Success Responses The API uses standard HTTP status codes to indicate successful operations: - **200 OK**: Returned for successful GET requests (collections and single resources) and PATCH/POST requests that return a response body - **201 Created**: Returned when a POST request successfully creates a new resource. Includes a `Location` header with the URL of the newly created resource - **202 Accepted**: Returned for operations accepted for asynchronous processing. The response body contains information about the operation status or a reference to check processing progress - **204 No Content**: Returned for successful DELETE operations and PATCH operations that don't return a response body ##### Example Success Response Structure A typical JSON:API collection response includes `jsonapi`, `data`, `links`, and optionally `included` and `meta` objects: ```json { "jsonapi": { "version": "1.0" }, "data": [ { "type": "dns-zones", "id": "16aeda2f-f1e5-4407-b7dd-e2862a9fb85f", "attributes": { "name": "example.com", "status": "success", "created_at": "2026-01-15T10:30:00.000000Z" }, "relationships": { "dns-records": { "links": { "self": "/api/v1/dns-zones/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f/relationships/dns-records", "related": "/api/v1/dns-zones/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f/dns-records" }, "data": [ { "type": "dns-records", "id": "a1b2c3d4-e5f6-4a5b-8c7d-9e8f7a6b5c4d" } ] } } } ], "included": [ { "type": "dns-records", "id": "a1b2c3d4-e5f6-4a5b-8c7d-9e8f7a6b5c4d", "attributes": { "name": "www", "dns_record_type": "A", "content": "192.0.2.1", "ttl": 3600 } } ], "links": { "first": "/api/v1/dns-zones?page[number]=1", "last": "/api/v1/dns-zones?page[number]=5", "prev": null, "next": "/api/v1/dns-zones?page[number]=2", "self": "/api/v1/dns-zones?page[number]=1" }, "meta": { "current_page": 1, "total_pages": 5, "total_count": 47 } } ``` #### Error Responses Error responses follow the JSON:API error object specification. The response includes an `errors` array containing one or more error objects with `status`, `title`, `detail`, and optionally `source` fields. ##### Standard Error Codes - **400 Bad Request**: Invalid request syntax or validation errors - **401 Unauthorized**: Missing or invalid authentication credentials - **403 Forbidden**: Authenticated but insufficient permissions - **404 Not Found**: Requested resource does not exist - **406 Not Acceptable**: Unsupported `Accept` header value - **409 Conflict**: Request conflicts with current resource state - **415 Unsupported Media Type**: Invalid `Content-Type` header - **422 Unprocessable Entity**: Semantic validation errors in request data - **429 Too Many Attempts**: Rate limit exceeded - **500 Internal Server Error**: Unexpected server error ##### Example Error Response ```json { "jsonapi": { "version": "1.0" }, "errors": [ { "status": "400", "title": "Invalid Query Parameter", "detail": "Sparse field set [dns-zones].[invalid_field] is not allowed.", "source": { "parameter": "fields[dns-zones]" } } ] } ``` #### Security Headers All API responses automatically include standardized security headers to protect against common vulnerabilities: - **X-Frame-Options**: Prevents clickjacking attacks by controlling iframe embedding - **X-Content-Type-Options**: Prevents MIME type sniffing - **X-XSS-Protection**: Enables browser XSS filtering - **Referrer-Policy**: Controls referrer information sent with requests - **Content-Security-Policy**: Defines content security policies - **Access-Control-Allow-Origin**: Configures CORS (Cross-Origin Resource Sharing) Rate limiting information is also included in response headers: - **X-RateLimit-Limit**: Maximum number of requests allowed per minute for your role - **X-RateLimit-Remaining**: Number of requests remaining in the current window - **X-RateLimit-Reset**: Unix epoch timestamp when the oldest request expires - **Retry-After**: Number of seconds to wait before retrying (included in 429 and 503 responses) Detailed specifications for all headers are available in the `components/headers/` section of this documentation. ### Rate limiting Requests through the API are rate limited per role. The current rate limits are: API requests are subject to rate limits based on the user's role. The current rate limits are as follows: - **Default**: 30 requests per minute - **Guest**: 30 requests per minute - **Admin**: 30 requests per minute - **Reseller Admin**: 60 requests per minute If you exceed the limit for your role, you will be rate limited until the next cycle begins. To optimize your experience, it's advisable to space out requests instead of sending them in bursts. Rate limiting details are included in the response headers of each request. The relevant headers are: - **X-RateLimit-Limit**: Indicates the maximum number of requests allowed per minute based on your role. - **X-RateLimit-Remaining**: Shows the number of requests you can still make before reaching your limit. This value will expire as requests are made. - **X-RateLimit-Reset**: Represents the time when the oldest request will expire, provided in Unix epoch time. Additional rate limiting information is available in the burst limit error response headers: - **Retry-After**: Specifies the number of seconds to wait before making another request when you are rate limited. As long as the `X-RateLimit-Remaining` count is above zero, you can continue to make requests. Understanding how requests expire and are removed from the current limit count is crucial. Instead of resetting the `X-RateLimit-Remaining` value at the end of the minute, each request has its own timer. This means that each request contributes to the `X-RateLimit-Remaining` count for one full minute after it is made. Once that request's timer expires, it no longer counts toward the limit. This also affects the `X-RateLimit-Reset` header. Since the entire rate limit does not reset simultaneously, this header indicates when the oldest request will expire. If you notice the `X-RateLimit-Reset` value changing without moving a full minute into the future, keep this in mind. When the `X-RateLimit-Remaining` reaches zero, subsequent requests will return a **429** error code until the request reset occurs. Reaching zero can also indicate that the burst limit has been met for your role. In this case, the **429** error response will include a `Retry-After` header indicating how long to wait (in seconds) before retrying the request. ##### Sample Rate Limit Headers ``` . . . X-RateLimit-Limit: 30 X-RateLimit-Remaining: 29 X-RateLimit-Reset: 1402425459 . . . ``` ##### Sample Rate Limit Headers When Burst Limit is Reached ``` . . . X-RateLimit-Limit: 30 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1402425459 Retry-After: 29 . . . ``` ##### Sample Rate Exceeded Response ```json { "errors": [ { "status": "429", "title": "Too Many Requests", "detail": "API Rate limit exceeded." } ] } ## Shared response behaviour Every operation returns the security headers `X-Frame-Options`, `X-Content-Type-Options`, `X-XSS-Protection`, `Referrer-Policy`, `Content-Security-Policy` and `Access-Control-Allow-Origin`, plus the rate limit headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. A `429` or `503` additionally carries `Retry-After`. These are identical everywhere and are not repeated per operation. Error responses share one body shape: ```json { "errors": [ { "status": "422", "title": "Unprocessable Entity", "detail": "...", "source": { "pointer": "..." } } ] } ```