openapi: 3.1.0 info: title: Cacholong API documentation version: '1.0' license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html description: | # 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." } ] } summary: Cacholong API documentation contact: name: Matthijs Möhlmann url: https://www.cacholong.nl/contact/ email: dev@cacholong.nl termsOfService: https://www.cacholong.nl/algemene-voorwaarden/ servers: - url: https://api.cacholong.eu/api/v1 x-internal: false security: - API-token: [] tags: - name: Accounts description: Manage accounts x-cacholong-public: true - name: Addresses description: Manage addresses for users and companies x-cacholong-public: true - name: Companies description: Manage companies x-cacholong-public: true - name: Dns Records description: Manage DNS records x-cacholong-public: true - name: Dns Templates description: Manage DNS templates x-cacholong-public: true - name: Dns Zone Restore Points description: Manage DNS zone restore points (snapshots for rollback) x-cacholong-public: true - name: Dns Zones description: Manage DNS zones x-cacholong-public: true - name: Inbox Messages description: Read your received messages x-cacholong-public: true - name: Mail Address Aliases description: Manage mail address aliases x-cacholong-public: true - name: Mail Addresses description: Manage mail addresses x-cacholong-public: true - name: Mail Domains description: Manage mail domains x-cacholong-public: true - name: Mail Forwards description: Manage mail forwards x-cacholong-public: true - name: Products description: Manage products x-cacholong-public: true - name: Purchases description: Manage purchases x-cacholong-public: true - name: Service Bundles x-cacholong-public: true description: | 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. - name: Tlds description: Top-level domains available for domain registration x-cacholong-public: true - name: Users description: Manage users x-cacholong-public: true paths: /accounts: get: x-cacholong-public: true summary: Get accounts x-cli-help: Get accounts x-cli-group: accounts x-cli-name: list x-cli-display-fields: - name x-cli-positional-params: [] x-permission: index.account security: - API-token: [] responses: '200': description: Returns a collection of accounts with pagination links. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/AccountShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: accounts.index description: | Retrieve a paginated collection of accounts. Accounts represent the top-level organizational units within the system that group users, services, and resources. **Account types:** - **Private account** - Account without a company relationship (for individuals) - **Business account** - Account with a company relationship (for organizations) **Account hierarchy:** - Accounts can be created as a sub-account of a parent account (see `parent` relationship and the `account-accounts` resource) - Parent accounts can access and manage their sub-account resources - Each account has an associated user, address, and optionally a company **User access:** - Users are connected to accounts through user-roles - Users can be associated with multiple accounts - Use `include=user-roles` to see all user-roles associated with an account x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: | Filter results by specific fields. [How to use filters](/#/#filters). **Available filters:** - `filter[search]` - Search across name and description (case-insensitive) name: filter[field] schema: enum: - search - id - name - description - created_at{_eq|_gt|_gte|_lt|_lte} - updated_at{_eq|_gt|_gte|_lt|_lte} - schema: type: string example: company enum: - company - user-roles - parent in: query name: include description: |- Related resources to include. [How to use include](/#/#include). `user-roles` contains only your own roles on each account, also for superadmins. See [Account visibility of included resources](/#/#account-visibility-of-included-resources). tags: - Accounts /accounts/{account_id}: get: x-cacholong-public: true summary: Get account x-cli-help: Get account with account id x-cli-group: accounts x-cli-name: show x-cli-positional-params: - account_id x-permission: view.account security: - API-token: [] responses: '200': description: Returns the account details including all attributes and relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/AccountShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: accounts.show description: | Retrieve detailed information about a specific account by its ID. Accounts represent the top-level organizational units within the system. **Account types:** - **Private account** - No `company` relationship (for individuals) - **Business account** - Has a `company` relationship (for organizations, include with `include=company`) - Accounts created as a sub-account expose their parent via the `parent` relationship (include with `include=parent`) **User access:** - Users are connected to accounts through user-roles - Use `include=user-roles` to see all user-roles associated with this account x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: company enum: - company - user-roles - parent in: query name: include description: |- Related resources to include. [How to use include](/#/#include). `user-roles` contains only your own roles on each account, also for superadmins. See [Account visibility of included resources](/#/#account-visibility-of-included-resources). tags: - Accounts parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: account_id in: path required: true description: Account Id /accounts/{account_id}/user-roles: get: summary: List account user-roles description: | Retrieve all user-roles associated with a specific account. This endpoint provides an alternative to using the `include=user-roles` parameter when fetching an account. **Account user-roles:** - User-roles represent the join between users, accounts, and roles (permissions) - Each user-role grants a specific user access to an account with a defined role - User-roles are managed separately via the user-roles endpoint - this endpoint is read-only - To create or modify user-roles, use the user-roles endpoints **When to use this endpoint:** - Use this endpoint when you only need user-role details without the full account object - Use `include=user-roles` on the account endpoint when you need both account and user-role data together **Pagination:** - Default page size: 10 user-roles - Maximum page size: 50 user-roles - Response includes pagination links: `first`, `last`, `prev`, `next`, `self` - See [How to use pagination](/#/#pagination) for navigation details **Sorting:** - Available sort fields: `created_at` - Use `-` prefix for descending order - See [How to use sorting](/#/#sorting) for sorting syntax **Fields:** - Use `fields[user-roles]` parameter to request specific attributes only (sparse fieldsets) - Reduces payload size when only certain fields are needed - See [How to use fields](/#/#fields) for field selection syntax **Related resources:** - Include `user` to get user details for each user-role - Include `role` to get role/permission details for each user-role operationId: accounts.user-roles.index x-cli-help: List all user-roles for an account tags: - Accounts x-internal: false x-cacholong-public: true x-cli-group: accounts x-cli-name: list-user-roles x-cli-positional-params: - account_id x-permission: index.user.role security: - API-token: [] parameters: - name: account_id in: path required: true description: The ID of the account schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - schema: type: string example: user enum: - user - role - account in: query name: include description: '[How to use include](/#/#include)' required: false responses: '200': description: Returns a collection of user-roles with pagination links. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/UserRoleShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /addresses: get: x-cacholong-public: true summary: Get addresses x-cli-group: addresses x-cli-name: list x-cli-help: Retrieve a paginated collection of addresses x-cli-display-fields: - company.name - user.name - street - number - city x-cli-require-one-of: - user - company x-permission: index.address security: - API-token: [] responses: '200': description: Returns a collection of addresses with pagination links. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/AddressShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: addresses.index description: | Retrieve a paginated collection of addresses. Addresses are used for billing and invoicing purposes. **Address ownership:** - Each address belongs to exactly one owner: either a user OR a company (never both) - Users and companies can have multiple addresses - No concept of primary or default address currently exists **Filtering:** - Required: Must filter by `filter[user]` OR `filter[company]` to scope results - Optional filters: `id`, `street`, `number`, `suffix`, `zipcode`, `city`, `state`, `country` - See [How to use filters](/#/#filters) for detailed filtering syntax **Pagination:** - Default page size: 10 addresses - Maximum page size: 50 addresses - Response includes pagination links: `first`, `last`, `prev`, `next`, `self` - See [How to use pagination](/#/#pagination) for navigation details **Sorting:** - Available sort fields: `street`, `city`, `country`, `created_at` - Use `-` prefix for descending order - See [How to use sorting](/#/#sorting) for sorting syntax **Fields:** - Use `fields[addresses]` parameter to request specific attributes only (sparse fieldsets) - Reduces payload size when only certain fields are needed - See [How to use fields](/#/#fields) for field selection syntax **Related resources:** - Use `include=company` or `include=user` to fetch the owner in a single request - See [How to use include](/#/#include) for details x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: | Filter results by specific fields. User or company is required filter. [How to use filters](/#/#filters). **Available filters:** - `filter[search]` - Search across street, city, and zipcode (case-insensitive) name: filter[field] schema: enum: - search - id - street - number - suffix - zipcode - city - state - country - company - user - schema: type: string example: company enum: - company - user in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Addresses post: x-cacholong-public: true summary: Create address operationId: addresses.create x-cli-group: addresses x-cli-name: create x-cli-help: Create a new address for a user or company x-permission: create.address security: - API-token: [] responses: '201': description: Address created successfully and returns the created resource with all attributes. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/AddressShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Create a new address for billing and invoicing purposes. The address must be associated with either a user or a company. **Address ownership:** - Must specify exactly one owner relationship: `user` OR `company` (never both) - Ownership is immutable and cannot be changed after creation - Users and companies can have multiple addresses **Required attributes:** - `street`, `number`, `zipcode`, `city`, `country` are typically required - Check validation rules for complete list of required fields **Validation rules:** - Must provide exactly one relationship: `user` OR `company` - Address fields must conform to expected formats - Country codes should follow ISO standards parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: oneOf: - $ref: '#/components/schemas/AddressCreateWithUser' - $ref: '#/components/schemas/AddressCreateWithCompany' tags: - Addresses /addresses/{address_id}: get: x-cacholong-public: true summary: Get address x-cli-group: addresses x-cli-name: show x-cli-positional-params: - address_id responses: '200': description: OK content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/AddressShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: addresses.show description: | Retrieve a specific address by ID. Each address is used for billing and invoicing and belongs to either a user or a company. **Address ownership:** - Each address belongs to exactly one owner: either a user OR a company (never both) - Ownership is immutable and cannot be changed after creation **Available includes:** - `include=company` - Include the company that owns this address (if applicable) - `include=user` - Include the user that owns this address (if applicable) - See [How to use include](/#/#include) for details **Sparse fieldsets:** - Use `fields[addresses]` parameter to request specific attributes only - See [How to use fields](/#/#fields) for field selection syntax x-cli-help: Retrieve a specific address by ID x-permission: show.address security: - API-token: [] x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: company enum: - company - user in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Addresses parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: address_id in: path required: true description: Address Id delete: x-cacholong-public: true summary: Delete address operationId: addresses.delete x-cli-group: addresses x-cli-name: delete x-cli-positional-params: - address_id x-cli-help: Delete a specific address x-permission: delete.address security: - API-token: [] responses: '204': $ref: '#/components/responses/204-NoContent' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Delete a specific address. The address is permanently removed from the system. **Deletion behavior:** - Address is permanently deleted - No constraints on deletion - addresses can be deleted at any time - Owner (user or company) is not affected - Users and companies can have multiple addresses, so removing one does not affect the owner parameters: - $ref: '#/components/parameters/Accept' tags: - Addresses patch: x-cacholong-public: true summary: Update address operationId: addresses.update x-cli-group: addresses x-cli-name: update x-cli-positional-params: - address_id x-cli-help: Update a specific address x-permission: update.address security: - API-token: [] responses: '200': description: Address updated successfully and returns the updated resource with all attributes. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/AddressShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Update a specific address. All address attributes can be modified except the ownership relationship. **Updatable attributes:** - All address fields: `street`, `number`, `suffix`, `zipcode`, `city`, `state`, `country` - Address details can be freely updated to reflect changes **Immutable fields:** - `id` - System-generated identifier cannot be changed - Owner relationship (`user` or `company`) - Ownership cannot be transferred after creation **Validation rules:** - Address fields must conform to expected formats - Country codes should follow ISO standards parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/AddressUpdate' tags: - Addresses /addresses/{address_id}/company: get: summary: Get address company description: | Retrieve the company that owns a specific address. This endpoint provides an alternative to using the `include=company` parameter when fetching an address. **Address ownership:** - Each address belongs to exactly one owner: either a user OR a company (never both) - Returns 404 if the address belongs to a user instead of a company - Ownership is immutable and cannot be changed after creation **When to use this endpoint:** - Use this endpoint when you only need company details without the full address object - Use `include=company` on the address endpoint when you need both address and company data together - Useful when starting from an address ID and needing to find its owner **Sparse fieldsets:** - Use `fields[companies]` parameter to request specific company attributes only - See [How to use fields](/#/#fields) for field selection syntax x-cli-help: Retrieve the company that owns a specific address operationId: addresses.company.show tags: - Addresses x-internal: false x-cacholong-public: true x-cli-group: addresses x-cli-name: show-company x-cli-positional-params: - address_id x-cli-display-fields: - id - name - kvknr x-permission: view.company security: - API-token: [] parameters: - name: address_id in: path required: true description: The ID of the address schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the company details including all attributes and available relationships. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/CompanyShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /addresses/{address_id}/user: get: summary: Get address user description: | Retrieve the user who owns a specific address. This endpoint provides an alternative to using the `include=user` parameter when fetching an address. **Address ownership:** - Each address belongs to exactly one owner: either a user OR a company (never both) - Returns 404 if the address belongs to a company instead of a user - Ownership is immutable and cannot be changed after creation **When to use this endpoint:** - Use this endpoint when you only need user details without the full address object - Use `include=user` on the address endpoint when you need both address and user data together - Useful when starting from an address ID and needing to find its owner **Sparse fieldsets:** - Use `fields[users]` parameter to request specific user attributes only - See [How to use fields](/#/#fields) for field selection syntax x-cli-help: Retrieve the user who owns a specific address operationId: addresses.user.show tags: - Addresses x-internal: false x-cacholong-public: true x-cli-group: addresses x-cli-name: show-user x-cli-positional-params: - address_id x-cli-display-fields: - id - name - email x-permission: view.user security: - API-token: [] parameters: - name: address_id in: path required: true description: The ID of the address schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the user details including all attributes and available relationships. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/UserShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /companies/{company_id}: get: x-cacholong-public: true summary: Get company security: - API-token: [] x-permission: view.company x-cli-help: Retrieve details of a specific company responses: '200': description: Returns the company details including all attributes and relationships content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/CompanyShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: companies.show description: | Retrieve detailed information about a specific company by its ID. Companies provide metadata and billing information for accounts. **Company-Account relationship:** - Each company is linked to exactly one account (1:1 relationship) - Use `include=account` to see the linked account details **Available includes:** - Use `include=account` to fetch the linked account in a single request - Use `include=addresses` to fetch company addresses - See [How to use include](/#/#include) for details **Sparse fieldsets:** - Use `fields[companies]` parameter to request only specific attributes - See [How to use fields](/#/#fields) for field selection syntax x-internal: false x-cli-group: companies x-cli-name: show x-cli-display-fields: - name - email - phone - account.name x-cli-positional-params: - company_id parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: addresses enum: - addresses - account in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Companies parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: company_id in: path required: true description: Company Id patch: x-cacholong-public: true summary: Update company operationId: companies.update security: - API-token: [] x-permission: update.company x-cli-help: Update a company's attributes x-cli-group: companies x-cli-name: update x-cli-positional-params: - company_id responses: '200': description: Returns the updated company with all attributes and relationships content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/CompanyShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Update an existing company's attributes. Use this operation to modify company metadata and billing information. **Updatable attributes:** - `name` - Company name - `email` - Company email address - `phone` - Company phone number - `kvknr` - Chamber of Commerce number (Dutch KVK) - `vat_number` - VAT identification number - Other business metadata fields **Immutable fields:** - `id` - Cannot be modified - `account` - Account relationship cannot be changed after creation (1:1 relationship is permanent) - `created_at`, `updated_at` - System-managed timestamps **Validation rules:** - Email must be valid format if changed - VAT number format validation if provided parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/CompanyUpdate' tags: - Companies /companies/{company_id}/addresses: get: summary: List company addresses description: | Retrieve all addresses associated with a specific company. This endpoint provides an alternative to using the `include=addresses` parameter when fetching a company. **Company addresses:** - Physical addresses for billing, shipping, and other business purposes - Companies typically have one address, but may have multiple (e.g., separate billing and shipping addresses) - Addresses are managed separately via the addresses endpoint - this endpoint is read-only - To create or modify addresses, use the addresses endpoints and link them to the company **When to use this endpoint:** - Use this endpoint when you only need address details without the full company object - Use `include=addresses` on the company endpoint when you need both company and address data together **Pagination:** - Default page size: 10 addresses - Maximum page size: 50 addresses - Response includes pagination links: `first`, `last`, `prev`, `next`, `self` - See [How to use pagination](/#/#pagination) for navigation details **Sorting:** - Available sort fields: `street`, `city`, `country`, `created_at` - Use `-` prefix for descending order - See [How to use sorting](/#/#sorting) for sorting syntax **Fields:** - Use `fields[addresses]` parameter to request specific attributes only (sparse fieldsets) - Reduces payload size when only certain fields are needed - See [How to use fields](/#/#fields) for field selection syntax operationId: companies.addresses.index x-cli-help: List all addresses for a company tags: - Companies x-internal: false x-cacholong-public: true x-cli-group: companies x-cli-name: list-addresses x-cli-positional-params: - company_id x-permission: index.address security: - API-token: [] parameters: - name: company_id in: path required: true description: The ID of the company schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' responses: '200': description: Returns a collection of addresses with pagination links. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/AddressShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /companies/{company_id}/account: get: summary: Get company account description: | Retrieve the account associated with a specific company. This endpoint provides an alternative to using the `include=account` parameter when fetching a company. **Company-account relationship:** - Every company has exactly one associated account (1:1 relationship) - This is the same account that was linked during company creation - The company-account relationship is immutable and cannot be changed after creation - The account owns all services and resources; the company provides billing and metadata **When to use this endpoint:** - Use this endpoint when you only need account details without the full company object - Use `include=account` on the company endpoint when you need both company and account data together **Sparse fieldsets:** - Use `fields[accounts]` parameter to request specific account attributes only - See [How to use fields](/#/#fields) for field selection syntax operationId: companies.account.show x-cli-help: Retrieve the account associated with a company tags: - Companies x-internal: false x-cacholong-public: true x-cli-group: companies x-cli-name: show-account x-cli-positional-params: - company_id x-cli-display-fields: - id - name - status x-permission: view.account security: - API-token: [] parameters: - name: company_id in: path required: true description: The ID of the company schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the account details including all attributes and available relationships. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/AccountShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /dns-records: get: x-cacholong-public: true summary: Get dns records responses: '200': description: Returns a paginated collection of DNS records. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/DnsRecordShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: dns-records.index x-cli-group: dns-records x-cli-name: list x-cli-help: Retrieve a paginated list of DNS records x-cli-display-fields: - dns_record_type - name - content - ttl - status x-cli-positional-params: [] x-cli-require-one-of: - dns-zone - dns-template x-permission: index.dns.record description: | Retrieve a paginated collection of DNS records. Records must be filtered by either dns-zone or dns-template (at least one is required). DNS records define how domain names resolve to IP addresses and other DNS information. Each record belongs to either a DNS zone (for active domain management) or a DNS template (for reusable record configurations). **Filtering:** - Required: Must filter by `dns-zone` OR `dns-template` to scope results - Optional filters: `dns_record_type`, `status`, `name`, `content`, `ttl`, `priority` - Comparison operators available for numeric fields (ttl, priority): `_eq`, `_gt`, `_gte`, `_lt`, `_lte` - See [How to use filters](/#/#filters) for detailed filtering syntax **Pagination:** - Default page size: 10 records - Maximum page size: 50 records - Use `page[number]` and `page[size]` parameters to navigate results - Response includes pagination links: `first`, `last`, `prev`, `next`, `self` - See [How to use pagination](/#/#pagination) for navigation details **Sorting:** - Available sort fields: `dns_record_type`, `name`, `content`, `ttl`, `priority`, `status` - Use `-` prefix for descending order (e.g., `sort=-created_at`) - See [How to use sorting](/#/#sorting) for sorting syntax **Fields:** - Use `fields[dns-records]` parameter to request specific attributes only (sparse fieldsets) - Reduces payload size when only certain fields are needed - See [How to use fields](/#/#fields) for field selection syntax **Related resources:** - Use `include` parameter to fetch related dns-zone or dns-template in a single request - See [How to use include](/#/#include) for details x-internal: false security: - API-token: [] parameters: - schema: type: string enum: - search - id - dns-zone - dns-template - dns_record_type - status - name - content - ttl{_eq|_gt|_gte|_lt|_lte} - priority{_eq|_gt|_gte|_lt|_lte} in: query name: filter[field] description: | Filter results by specific fields. Dns-zone or dns-template is required filter. [How to use filters](/#/#filters). **Available filters:** - `filter[search]` - Search across name and content (case-insensitive) required: true - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - schema: type: string example: dns-zone enum: - dns-zone - dns-template in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Dns Records post: x-cacholong-public: true summary: Create dns record operationId: dns-records.create x-cli-group: dns-records x-cli-name: create x-cli-help: Create a new DNS record in a zone or template x-cli-positional-params: [] x-permission: create.dns.record security: - API-token: [] responses: '201': description: Returns the created DNS record with all attributes. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsRecordShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '202': description: Request accepted for asynchronous processing and returns the record in pending status. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsRecordShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Create a new DNS record in a DNS zone or DNS template. The record will be created with an initial status that depends on the processing mode. DNS records define resource records for domain name resolution, such as A, AAAA, CNAME, MX, TXT, and other record types. Each record must belong to either a zone (for active domains) or a template (for reusable configurations). **Processing modes:** - `meta.sync: true` - Synchronous creation. Waits for validation and provider synchronization (slower, but record is immediately ready) - `meta.sync: false` (default) - Asynchronous creation. Returns immediately with `pending` status and processes in background (faster response) **Required relationships:** - Must provide exactly one: `dns-zone` OR `dns-template` - `dns-zone` - For records that will actively serve DNS queries for a domain - `dns-template` - For template records that can be copied to multiple zones **Validation rules:** - `dns_record_type` must be a valid DNS record type (A, AAAA, CNAME, MX, TXT, SRV, etc.) - `name` must be a valid hostname or subdomain format - The `name` of an NS record must be a subdomain of the zone domain; otherwise the request returns `422` with `source.pointer` `/data/attributes/name` and detail `The name of an NS record must be a subdomain of .` - When the `name` cannot be checked against the DNS zone or template domain, the request returns `422` with `source.pointer` `/data/attributes/name` and detail `The name cannot be checked against a DNS zone or template domain.` - `name` is stored lower-cased (RFC 4343). Submitting `WWW.example.com` stores and returns `www.example.com`; the submitted casing is not preserved - `content` format depends on record type (IP address for A/AAAA, domain for CNAME, etc.) - `content` is not normalised. A `TXT` or `CNAME` value retains the casing it was submitted with - `ttl` (Time To Live) must be a positive integer (typically 60-86400 seconds) - `priority` required for MX and SRV record types - Cannot create a record identical to an existing one in the same zone or template (same `dns_record_type`, `name`, `content` and `priority`). The error uses `source.pointer` `/data/attributes/name` with detail `This DNS record has already been taken for this DNS zone.` (or `This DNS record has already been taken for this DNS template.`) - A CNAME record must be the only record at its name (RFC 1034 section 3.6.2); see **CNAME co-existence** below - Because `name` is lower-cased before storage, the duplicate and CNAME co-existence checks treat names differing only in case as the same name - `spf_flatten` can only be set to `true` on a `TXT` record created with a `dns-zone` relationship; it is rejected on records created with a `dns-template` relationship - When `spf_flatten` is `true`, `content` holds the SPF policy and must start with `v=spf1`; otherwise the request returns `422` with `source.pointer` `/data/attributes/content`. The flattened result is published as `spf_flattened_content`; `content` is never overwritten - Setting `spf_flatten` requires the `flatten.dns.record` permission - The `dns-zone` must not be administratively disabled; otherwise the request returns `422` with `source.pointer` `/data/relationships/dns-zone`, for every user **CNAME co-existence:** Creation is rejected with `422` in both directions of a CNAME conflict within the owning DNS zone or DNS template: - The new record is a CNAME and a record of any type already exists at that `name` - detail `A CNAME record cannot coexist with other records for the same name. Remove the existing record(s) first.` - The new record is not a CNAME and a CNAME already exists at that `name` - detail `A CNAME record already exists for this name. A CNAME cannot coexist with other record types.` Both errors use `source.pointer` `/data/attributes/name`. Still permitted at a single name: - Records of differing types where none is a CNAME, for example `A`, `MX` and `TXT` - Multiple records of the same non-CNAME type with differing content (round-robin), for example two `A` records - The same name in a different DNS zone or DNS template, because the rule is scoped to the owning zone or template **Automatic restore points:** When creating a record in a DNS zone, an automatic restore point (snapshot) of the zone's current records is created before the first mutation within a 60-minute window. This allows you to roll back accidental changes via `POST /dns-zone-restore-points/{id}/rollback`. Template records do not trigger automatic restore points. parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: oneOf: - $ref: '#/components/schemas/DnsRecordCreateWithZone' - $ref: '#/components/schemas/DnsRecordCreateWithTemplate' tags: - Dns Records /dns-records/{dns_record_id}: get: x-cacholong-public: true summary: Get dns record responses: '200': description: OK content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsRecordShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: dns-records.show x-cli-group: dns-records x-cli-name: show x-cli-help: Retrieve detailed information about a specific DNS record x-cli-display-fields: - id - dns_record_type - name - content - ttl - priority - status - spf_status - created_at - updated_at x-cli-positional-params: - dns_record_id x-permission: show.dns.record description: | Retrieve detailed information about a specific DNS record by its unique identifier. Returns the complete DNS record resource including all attributes (type, name, content, TTL, priority, status, timestamps) and optionally related resources. **Available includes:** - `dns-zone` - Include the DNS zone that owns this record (for zone-based records) - `dns-template` - Include the DNS template that owns this record (for template-based records) - See [How to use include](/#/#include) for detailed usage **Sparse fieldsets:** - Use `fields[dns-records]` to retrieve only specific attributes - Reduces payload size for large result sets - See [How to use fields](/#/#fields) for field selection syntax x-internal: false security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: dns-zone enum: - dns-zone - dns-template in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Dns Records parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: dns_record_id in: path required: true description: The unique identifier (UUID v4) of the DNS record to retrieve, update, or delete. delete: x-cacholong-public: true summary: Delete dns record operationId: dns-records.delete x-cli-group: dns-records x-cli-name: delete x-cli-help: Permanently delete a DNS record x-cli-positional-params: - dns_record_id x-permission: delete.dns.record security: - API-token: [] responses: '204': $ref: '#/components/responses/204-NoContent' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Permanently delete a DNS record from its zone or template. This action is irreversible. For zone-based records, deletion will immediately affect DNS resolution once changes propagate to nameservers. The domain will no longer resolve using this record's configuration. For template-based records, deletion removes the record from the template but does not affect zones that were previously created from the template. The parent DNS zone or template remains unaffected and can continue to contain other records. A record in a DNS zone that is administratively disabled cannot be deleted, by any user; the request returns `422` with detail `This DNS zone is currently administratively disabled.` **Automatic restore points:** When deleting a record from a DNS zone, an automatic restore point (snapshot) of the zone's current records is created before the first mutation within a 60-minute window. This allows you to roll back accidental deletions via `POST /dns-zone-restore-points/{id}/rollback`. Template records do not trigger automatic restore points. parameters: - $ref: '#/components/parameters/Accept' tags: - Dns Records patch: x-cacholong-public: true summary: Update dns record operationId: dns-records.update x-cli-group: dns-records x-cli-name: update x-cli-help: Update DNS record attributes like type, name, content, TTL, or priority x-cli-positional-params: - dns_record_id x-permission: update.dns.record security: - API-token: [] responses: '200': description: Returns the updated DNS record with all current attribute values. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsRecordShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '202': description: Update accepted for asynchronous processing and returns the record in its current state. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsRecordShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Update an existing DNS record's attributes. Changes can be processed synchronously or asynchronously depending on the `meta.sync` parameter. **Updatable attributes:** - `dns_record_type` - Change the DNS record type (A, AAAA, CNAME, MX, TXT, etc.) - `name` - Update the hostname or subdomain - `content` - Modify the record's value (IP address, target domain, text content, etc.) - `ttl` - Adjust Time To Live in seconds - `priority` - Change priority (for MX and SRV records) - `status` - Update processing status - `spf_flatten` - Enable or disable SPF flattening of the policy in `content`. Only allowed on a `TXT` record belonging to a `dns-zone` (not a `dns-template`). Requires the `flatten.dns.record` permission. Disabling it clears all derived SPF state (`spf_status`, `spf_flattened_content`, `spf_last_flattened_at`, `spf_last_changed_at`); `content` is kept **Immutable fields:** - `id` - Record identifier cannot be changed - `type` - Resource type is always `dns-records` - `relationships` - DNS zone or template assignment cannot be changed after creation - `created_at` - Creation timestamp is system-managed - `updated_at` - Update timestamp is automatically set - `spf_flattened_content` - System-computed flattened SPF result; cannot be set directly - `spf_status` - System-computed outcome of the last SPF resolution attempt; cannot be set directly - `spf_last_flattened_at` - System-managed timestamp of the last successful SPF re-flattening - `spf_last_changed_at` - System-managed timestamp of the last change to the flattened SPF content **Processing modes:** - `meta.sync: true` - Synchronous update. Waits for validation and provider synchronization (slower, but changes are immediately active) - `meta.sync: false` (default) - Asynchronous update. Returns immediately and processes in background (faster response, monitor `status` field) **Validation rules:** - The updated record must not become identical to another record in the same zone or template (same `dns_record_type`, `name`, `content` and `priority`). The error uses `source.pointer` `/data/attributes/name` with detail `This DNS record has already been taken for this DNS zone.` (or `This DNS record has already been taken for this DNS template.`) - A CNAME record must be the only record at its name (RFC 1034 section 3.6.2); see **CNAME co-existence** below - `name` is stored lower-cased (RFC 4343); the submitted casing is not preserved. `content` is not normalised and retains its submitted casing - Because `name` is lower-cased before storage, the duplicate and CNAME co-existence checks treat names differing only in case as the same name; changing only the casing of a record's `name` therefore leaves it unchanged - The `name` of an NS record must be a subdomain of the zone domain; otherwise the request returns `422` with `source.pointer` `/data/attributes/name` and detail `The name of an NS record must be a subdomain of .` - When the `name` cannot be checked against the DNS zone or template domain, the request returns `422` with `source.pointer` `/data/attributes/name` and detail `The name cannot be checked against a DNS zone or template domain.` - Setting `spf_flatten` to `true` requires the record to belong to a `dns-zone` (not a `dns-template`) and `dns_record_type` to be `TXT` - When the record has `spf_flatten` `true` after the update, `content` holds the SPF policy and must start with `v=spf1`; otherwise the request returns `422` with `source.pointer` `/data/attributes/content`. This also applies when the request sends only `spf_flatten`, or only `content` of a record that is already flattened. The flattened result is published as `spf_flattened_content`; `content` is never overwritten - The record's DNS zone must not be administratively disabled; otherwise the request returns `422` with `source.pointer` `/data/relationships/dns-zone`, for every user. This also applies when the request does not send the `dns-zone` relationship, for example when only `content` is updated **CNAME co-existence:** Because both `dns_record_type` and `name` are updatable, an update can create a CNAME conflict: changing a record's type to CNAME, or moving it onto a name a CNAME already occupies, is rejected with `422`. The check runs in both directions within the owning DNS zone or DNS template: - The record becomes a CNAME while a record of any type already exists at that `name` - detail `A CNAME record cannot coexist with other records for the same name. Remove the existing record(s) first.` - The record is not a CNAME and a CNAME already exists at that `name` - detail `A CNAME record already exists for this name. A CNAME cannot coexist with other record types.` Both errors use `source.pointer` `/data/attributes/name`. A record never conflicts with itself, so updating only the `content` or `ttl` of an existing CNAME is unaffected. **Automatic restore points:** When updating a record in a DNS zone, an automatic restore point (snapshot) of the zone's current records is created before the first mutation within a 60-minute window. This allows you to roll back accidental changes via `POST /dns-zone-restore-points/{id}/rollback`. Template records do not trigger automatic restore points. parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DnsRecordUpdate' tags: - Dns Records /dns-templates: get: x-cacholong-public: true summary: Get dns templates x-cli-group: dns-templates x-cli-name: list x-cli-help: Retrieve a paginated list of DNS templates x-cli-display-fields: - account.name - name x-cli-positional-params: [] x-permission: list.dns.template security: - API-token: [] responses: '200': description: Returns a paginated collection of DNS templates. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/DnsTemplateShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: dns-templates.index description: Retrieve DNS templates filtered by account (required for most users). x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: Filter data per field or related field. Account is required filter for most users. [How to use filters](/#/#filters). name: filter[field] schema: enum: - id - name - account - schema: type: string example: dns-records enum: - dns-records - account in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Dns Templates post: x-cacholong-public: true summary: Create dns template operationId: dns-templates.create x-cli-group: dns-templates x-cli-name: create x-cli-help: Create a new DNS template x-cli-positional-params: [] x-permission: create.dns.template security: - API-token: [] responses: '201': description: Returns the created DNS template with all attributes. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsTemplateShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Create a new DNS template with reusable DNS record configurations. Templates can be applied when creating new domain registrations to automatically populate DNS zones with predefined records. **Template creation:** - Templates are created immediately and are ready to use (no processing delay) - Each template must have a unique name within your account - Templates are always account-specific (global templates are system-managed) **Variable usage:** - Use `$domain$` placeholder in DNS record names to substitute the actual domain name when the template is applied - For CNAME records, `$domain$` can also be used in the content field - Example: Template record name `www.$domain$` becomes `www.example.com` when applied to `example.com` **Required attributes:** - `name` - Unique identifier for the template **Required relationships:** - `account` - The account that owns this template **Validation rules:** - Template name must be unique within the account - DNS records can be added after template creation via the DNS records endpoint parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DnsTemplateCreate' tags: - Dns Templates /dns-templates/{dns_template_id}: get: x-cacholong-public: true summary: Get dns template x-cli-group: dns-templates x-cli-name: show x-cli-help: Retrieve detailed information about a specific DNS template x-cli-display-fields: - id - account.name - name - created_at - updated_at x-cli-positional-params: - dns_template_id x-permission: show.dns.template security: - API-token: [] responses: '200': description: OK content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsTemplateShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: dns-templates.show description: | Retrieve a specific DNS template by ID. Templates are reusable configurations containing DNS record blueprints that can be applied when creating new domain registrations. **Template structure:** - Templates contain blueprint DNS records with variable placeholders - The `$domain$` variable in record names is replaced with the actual domain when applied - For CNAME records, `$domain$` can also be used in the content field - Example: Template record `www.$domain$` pointing to `$domain$` becomes `www.example.com` → `example.com` **Template application:** - Templates are applied during domain registration creation - DNS records from the template are copied to the new zone - Once copied, zone records are independent from the template (modifications to template don't affect existing zones) x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: dns-records enum: - dns-records - account in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Dns Templates parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: dns_template_id in: path required: true description: Dns template Id delete: x-cacholong-public: true summary: Delete dns template operationId: dns-templates.delete x-cli-group: dns-templates x-cli-name: delete x-cli-help: Permanently delete a DNS template x-cli-positional-params: - dns_template_id x-permission: delete.dns.template security: - API-token: [] responses: '204': $ref: '#/components/responses/204-NoContent' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Permanently delete a DNS template. This operation is safe and has no side effects on existing DNS zones that were created using this template. **Deletion behavior:** - Template is immediately removed from your account - DNS zones created from this template remain unaffected - DNS records copied from this template to zones remain intact - Template cannot be recovered after deletion **No constraints:** - Templates can be deleted at any time, regardless of usage - No need to check for zones using the template before deletion - Deletion is immediate (no background processing) **Before deletion:** - Consider if you may need this template configuration in the future - Note that deletion cannot be undone - Existing zones using this template will not be affected parameters: - $ref: '#/components/parameters/Accept' tags: - Dns Templates patch: x-cacholong-public: true summary: Update dns template operationId: dns-templates.update x-cli-group: dns-templates x-cli-name: update x-cli-help: Update DNS template attributes like name x-cli-positional-params: - dns_template_id x-permission: update.dns.template security: - API-token: [] responses: '200': description: OK content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsTemplateShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Update DNS template attributes. Templates can be modified at any time without constraints or processing delays. **Updatable attributes:** - `name` - Change the template name (must remain unique within account) - Other template configuration attributes **Template records:** - To modify blueprint DNS records, use the DNS records endpoint - DNS records are managed separately from template attributes - Use `$domain$` variable in record names for domain substitution **No constraints:** - Templates can be updated at any time - No status field or processing delays - Changes are applied immediately - Updates don't affect DNS zones previously created from this template **Validation rules:** - Template name must be unique within your account - Cannot change the owning account parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DnsTemplateUpdate' tags: - Dns Templates /dns-zone-restore-points: get: x-cacholong-public: true summary: Get dns zone restore points responses: '200': description: Returns a paginated collection of DNS zone restore points for the specified zone. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/DnsZoneRestorePointShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: dns-zone-restore-points.index x-cli-group: dns-zone-restore-points x-cli-name: list x-cli-help: List all restore points for a DNS zone x-cli-display-fields: - name - is_manual - created_at - updated_at x-cli-positional-params: [] x-permission: index.dns.zone.restore.point description: | Retrieve a paginated collection of DNS zone restore points. Each restore point is a snapshot of a DNS zone's records at a specific point in time and can be used to roll back DNS record changes. **Filtering (required):** - `filter[dns-zone]` is required — you must always scope results to a specific DNS zone. **Restore point lifecycle:** - Restore points are created automatically before the first DNS record mutation (create, update, or delete) per zone within a configurable time window (default: 60 minutes). - Restore points can also be created manually via `POST /dns-zone-restore-points`. - Auto-created restore points (`is_manual: false`) are retained for 3 months by default. - Manually created restore points (`is_manual: true`) are retained for 12 months by default. - Retention is measured from `updated_at` — performing a rollback refreshes this timestamp and extends retention. x-internal: false security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/fields' - schema: type: string example: dns-zone enum: - dns-zone - dns-records in: query name: include description: | Include related resources in the response. [How to use include](/#/#include). **Available includes:** - `dns-zone` - Include the DNS zone this restore point belongs to - `dns-records` - Include all DNS records captured in this restore point - in: query description: | Filter results by specific fields. [How to use filters](/#/#filters). **Available filters:** - `filter[dns-zone]` — **(Required)** Filter by DNS zone UUID - `filter[is_manual]` — Filter by creation type: `true` (manual) or `false` (auto-snapshot) name: filter[field] required: true schema: enum: - dns-zone - is_manual tags: - Dns Zone Restore Points post: x-cacholong-public: true summary: Create dns zone restore point operationId: dns-zone-restore-points.create x-cli-group: dns-zone-restore-points x-cli-name: create x-cli-help: Manually create a restore point (snapshot) for a DNS zone x-cli-positional-params: [] x-permission: create.dns.zone.restore.point security: - API-token: [] responses: '201': description: Returns the created DNS zone restore point with all attributes. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsZoneRestorePointShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Manually create a restore point (snapshot) of a DNS zone's current records. The restore point captures all live DNS records in the zone at the time of creation and can later be used to roll back changes via `POST /dns-zone-restore-points/{id}/rollback`. **Automatic snapshots:** Restore points are also created automatically before the first DNS record mutation per zone within a 60-minute window. Manual restore points are useful when you want to explicitly bookmark a known-good state before making changes. **Required relationships:** - `dns-zone` — The DNS zone to snapshot. **Validation rules:** - `name` is required. - `name` maximum length: 255 characters. parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DnsZoneRestorePointCreate' tags: - Dns Zone Restore Points /dns-zone-restore-points/{dns_zone_restore_point_id}: get: x-cacholong-public: true summary: Get dns zone restore point responses: '200': description: Returns the DNS zone restore point details including all attributes and relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsZoneRestorePointShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: dns-zone-restore-points.show x-cli-group: dns-zone-restore-points x-cli-name: show x-cli-help: Retrieve detailed information about a specific DNS zone restore point x-cli-positional-params: - dns_zone_restore_point_id x-permission: show.dns.zone.restore.point description: | Retrieve detailed information about a specific DNS zone restore point by its unique identifier. The restore point represents a snapshot of a DNS zone's records at a specific point in time. **Retention:** - Auto-created restore points (`is_manual: false`) expire 3 months after `updated_at`. - Manually created restore points (`is_manual: true`) expire 12 months after `updated_at`. - Performing a rollback using this restore point refreshes `updated_at` and extends the retention period. x-internal: false security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: dns-zone enum: - dns-zone - dns-records in: query name: include description: | Include related resources in the response. [How to use include](/#/#include). **Available includes:** - `dns-zone` - Include the DNS zone this restore point belongs to - `dns-records` - Include all DNS records captured in this restore point tags: - Dns Zone Restore Points parameters: - schema: type: string format: uuid maxLength: 36 example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 name: dns_zone_restore_point_id in: path required: true description: '**UUID of the DNS zone restore point.** Use the list endpoint (`GET /dns-zone-restore-points?filter[dns-zone]={zone-id}`) to discover available restore points for a zone.' patch: x-cacholong-public: true summary: Update dns zone restore point operationId: dns-zone-restore-points.update x-cli-group: dns-zone-restore-points x-cli-name: update x-cli-help: Rename a DNS zone restore point x-cli-positional-params: - dns_zone_restore_point_id x-permission: update.dns.zone.restore.point security: - API-token: [] responses: '200': description: Returns the updated DNS zone restore point with all current attribute values. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsZoneRestorePointShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Rename an existing DNS zone restore point. Only the `name` attribute can be updated — restore points are otherwise immutable snapshots. **Updatable attributes:** - `name` — Change the human-readable name of the restore point. **Immutable fields:** - `id` — Restore point identifier cannot be changed. - `type` — Resource type is always `dns-zone-restore-points`. - `is_manual` — Creation type is set at creation and cannot be changed. - `relationships` — The associated DNS zone cannot be changed after creation. - `created_at` — Creation timestamp is system-managed. - `updated_at` — Update timestamp is automatically set. **Validation rules:** - `name` is required. - `name` maximum length: 255 characters. parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DnsZoneRestorePointUpdate' tags: - Dns Zone Restore Points delete: x-cacholong-public: true summary: Delete dns zone restore point operationId: dns-zone-restore-points.delete x-cli-group: dns-zone-restore-points x-cli-name: delete x-cli-help: Permanently delete a DNS zone restore point and its snapshot records x-cli-positional-params: - dns_zone_restore_point_id x-permission: delete.dns.zone.restore.point security: - API-token: [] responses: '204': $ref: '#/components/responses/204-NoContent' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Permanently delete a DNS zone restore point and all its associated snapshot records. This action is irreversible — the captured DNS state cannot be recovered after deletion. **Deletion behavior:** - The restore point metadata and all associated snapshot DNS records are permanently removed. - Live DNS records in the zone are not affected. parameters: - $ref: '#/components/parameters/Accept' tags: - Dns Zone Restore Points /dns-zone-restore-points/{dns_zone_restore_point_id}/rollback: post: x-cacholong-public: true summary: Rollback dns zone restore point operationId: dns-zone-restore-points.rollback x-cli-group: dns-zone-restore-points x-cli-name: rollback x-cli-help: Roll back a DNS zone's records to the state captured in this restore point x-cli-positional-params: - dns_zone_restore_point_id x-permission: rollback.dns.zone.restore.point security: - API-token: [] responses: '202': description: Rollback accepted for asynchronous processing. Returned when no body is sent or `data.meta.sync` is not `true`; DNS record changes are applied in the background. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '204': $ref: '#/components/responses/204-NoContent' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Roll back a DNS zone's live records to the state captured in this restore point. The operation computes a diff between the snapshot and the current live records, then applies only the necessary changes. **Diff logic:** Records are compared on `(type, name)` as key, then checked for differences in `content`, `ttl`, and `priority`: - **Snapshot-only** → new live record is created. - **Live-only** → live record is deleted. - **Differs** → live record is updated to match the snapshot. - **Identical** → no action taken. All changes are applied in a single transaction. **Processing modes:** - No request body — Asynchronous rollback. Returns `202 Accepted` immediately. - `meta.sync: true` — Synchronous rollback. Waits for the record changes to be processed and returns `204 No Content`. - `meta.sync: false` (default) — Asynchronous rollback. Returns `202 Accepted` immediately; monitor the DNS zone's `status` field to track when the rollback completes. **Validation rules:** - The request body is optional. When sent, it must be a JSON:API document with a `data` member; a body without `data` returns 400. - `data.type` must be `dns-zone-restore-points` and `data.id` must match the path parameter; a mismatch returns 409. - `data.meta.sync` must be a boolean; any other value returns 422. A top-level `meta.sync` is ignored. - The DNS zone must not be administratively disabled; a rollback for a disabled zone returns 400 with detail `This DNS zone is currently administratively disabled.` **Side effects:** - Performing a rollback refreshes the restore point's `updated_at` timestamp, extending its retention period. - This action triggers the same DNS record jobs as regular record create, update, and delete operations. - The SPF flattening state captured in the snapshot (`spf_flatten` and the derived `spf_*` attributes) is restored, and records with `spf_flatten` `true` are flattened again. parameters: - $ref: '#/components/parameters/Accept' requestBody: required: false content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DnsZoneRestorePointRollback' examples: sync: summary: Synchronous rollback value: data: type: dns-zone-restore-points id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 meta: sync: true tags: - Dns Zone Restore Points parameters: - schema: type: string format: uuid maxLength: 36 example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 name: dns_zone_restore_point_id in: path required: true description: '**UUID of the DNS zone restore point to roll back from.** Use the list endpoint (`GET /dns-zone-restore-points?filter[dns-zone]={zone-id}`) to discover available restore points.' /dns-zone-restore-points/{dns_zone_restore_point_id}/dns-zone: get: summary: Get dns zone description: | Retrieve the DNS zone that a DNS zone restore point belongs to. This endpoint returns the zone resource that the restore point was created from. **When to use this endpoint:** - Use this endpoint when you need full DNS zone details for a specific restore point. - Alternative: Use `include=dns-zone` parameter on the restore point GET endpoint to fetch both restore point and zone in a single request (more efficient). operationId: dns-zone-restore-points.dns-zone.show tags: - Dns Zone Restore Points x-cacholong-public: true x-cli-group: dns-zone-restore-points x-cli-name: show-dns-zone x-cli-help: Retrieve the DNS zone that a restore point belongs to x-cli-positional-params: - dns_zone_restore_point_id x-permission: show.dns.zone security: - API-token: [] parameters: - name: dns_zone_restore_point_id in: path required: true description: '**UUID of the DNS zone restore point.** Use the list endpoint (`GET /dns-zone-restore-points?filter[dns-zone]={zone-id}`) to discover available restore points for a zone.' schema: type: string format: uuid maxLength: 36 example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the DNS zone resource associated with the restore point. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsZoneShow' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /dns-zone-restore-points/{dns_zone_restore_point_id}/dns-records: get: summary: List dns records description: | Retrieve all DNS records captured in a specific DNS zone restore point. These records represent the snapshot of the DNS zone's state at the time the restore point was created. **When to use this endpoint:** - Use this endpoint when you need to inspect the exact DNS records captured in a restore point before performing a rollback. - Alternative: Use `include=dns-records` parameter on the restore point GET endpoint to fetch both the restore point and its snapshot records in a single request (more efficient for small record sets). operationId: dns-zone-restore-points.dns-records.index tags: - Dns Zone Restore Points x-cacholong-public: true x-cli-group: dns-zone-restore-points x-cli-name: list-dns-records x-cli-help: Retrieve all DNS records captured in a restore point snapshot x-cli-positional-params: - dns_zone_restore_point_id x-permission: index.dns.record security: - API-token: [] parameters: - name: dns_zone_restore_point_id in: path required: true description: '**UUID of the DNS zone restore point.** Use the list endpoint (`GET /dns-zone-restore-points?filter[dns-zone]={zone-id}`) to discover available restore points for a zone.' schema: type: string format: uuid maxLength: 36 example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' responses: '200': description: Returns a paginated collection of DNS records captured in the restore point snapshot. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/DnsRecordShow' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /dns-zones: get: x-cacholong-public: true summary: Get dns zones responses: '200': description: Returns a paginated collection of DNS zones with optional relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/DnsZoneShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: dns-zones.index x-cli-group: dns-zones x-cli-name: list x-cli-help: Retrieve a paginated list of DNS zones x-cli-display-fields: - account.name - domain - status - active x-cli-positional-params: [] x-permission: index.dns.zone description: | Retrieve a paginated collection of DNS zones associated with your account. A DNS zone is a specific portion of the DNS namespace managed by your organization, containing DNS records and subdomain configurations for your domains. **DNS zone status:** - `pending` - Zone created but not yet processed - `processing` - Zone configuration is currently being applied - `verifying` - Zone undergoing verification (e.g., SSL Labs checks) - `retrying` - Zone operation failed and is waiting for retry - `failed` - Zone operation failed (contact support for resolution) - `success` - Zone is fully configured and operational - **Note:** Zones can only be updated when status is `success` **Administratively disabled:** - `administratively_disabled: true` - A superadmin has disabled the zone: its records are removed at the DNS provider but kept here, so the zone does not resolve - While disabled, the zone and its DNS records cannot be changed or deleted - Filter with `filter[administratively_disabled]` and sort with `sort=administratively_disabled` or `sort=-administratively_disabled` **Account filter:** - `filter[account]` accepts several account ids, as an array (`filter[account][]=&filter[account][]=`) or comma-separated (`filter[account]=,`); both give the same result - A list that contains an account you may not see returns **403** x-internal: false security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: | Filter results by specific fields. [How to use filters](/#/#filters). **Available filters:** - `filter[id]` - Filter by zone UUID - `filter[status]` - Filter by processing status: `pending`, `processing`, `verifying`, `retrying`, `failed`, `success` - `filter[active]` - Filter by active state: `true` or `false` - `filter[administratively_disabled]` - Filter by administratively disabled state: `true` or `false` - `filter[dnssec]` - Filter by DNSSEC enabled: `true` or `false` - `filter[dnssec_status]` - Filter by DNSSEC status - `filter[domain]` - Filter by domain name (exact match or partial) - `filter[subaccount]` - Filter by subaccount ownership: `true` or `false`; with **true**, the result covers every account in `filter[account]` plus the sub-accounts of each listed account - `filter[account]` - One or more account ids (array or comma-separated) - `filter[name-server-group]` - One or more name server group ids (array or comma-separated) - `filter[created_at_*]` - Filter by creation date with operators: `_eq`, `_gt`, `_gte`, `_lt`, `_lte` (ISO 8601 format) - `filter[updated_at_*]` - Filter by update date with operators: `_eq`, `_gt`, `_gte`, `_lt`, `_lte` (ISO 8601 format) **Examples:** `filter[status]=success`, `filter[active]=true`, `filter[created_at_gte]=2026-01-01` name: filter[field] x-cli-filter-keys: subaccount: schema: type: boolean enum: - true help: Also list the resources of the account's reseller sub-accounts (one level deep); needs --account requires: account schema: enum: - id - status - active - administratively_disabled - dnssec - dnssec_status - domain - subaccount - account - name-server-group - created_at{_eq|_gt|_gte|_lt|_lte} - updated_at{_eq|_gt|_gte|_lt|_lte} - schema: type: string example: account enum: - account - name-server-group - dns-records in: query name: include description: | Include related resources in the response. [How to use include](/#/#include). **Available includes:** - `account` - Include account details (name, company information) - `name-server-group` - Include the name servers serving each zone - `dns-records` - Include all DNS records for each zone (**Warning:** May significantly increase response size) **Example:** `include=account,name-server-group` to include both the account and the name server group. tags: - Dns Zones post: x-cacholong-public: true summary: Create dns zone operationId: dns-zones.create x-cli-group: dns-zones x-cli-name: create x-cli-help: Create a new DNS zone for a domain x-cli-positional-params: [] x-permission: create.dns.zone security: - API-token: [] responses: '201': description: Returns the created DNS zone resource with all attributes. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsZoneShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '202': description: Request accepted for asynchronous processing and returns the zone in pending status. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsZoneShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Create a new DNS zone for managing a domain's DNS records and subdomain configurations. The zone represents a specific portion of the DNS namespace that you control. **Zone creation:** - Zone created with initial `pending` status - Status progresses: `pending` → `processing` → `success` (or `failed`/`retrying`) - Zone becomes operational when status reaches `success` - Monitor status field to track creation progress **Processing modes:** - `meta.sync: true` - Synchronous creation. Waits for zone to reach final status (up to 15 seconds, but zone is immediately ready) - `meta.sync: false` (default) - Asynchronous creation. Returns immediately with `pending` status (faster response, monitor `status` field) **Required relationships:** - `account` - The account that owns this DNS zone - `product` - The product/service associated with this zone (only used during creation) **DNSSEC support:** - Only superadmins can set `dnssec`; for other users a submitted value is ignored - DNSSEC keys are automatically fetched from the external service provider - Some domain extensions do not support DNSSEC **Validation rules:** - `domain` must be a valid hostname format (e.g., `example.com`, without protocol) - Maximum domain length: 255 characters - `domain` is stored lower-cased (RFC 4343). Submitting `Example.com` creates and returns `example.com`; the submitted casing is not preserved - `domain` must be unique within the service, compared case-insensitively. A domain differing from an existing zone's only in case is rejected with `422` using `source.pointer` `/data/attributes/domain` (**breaking change:** such domains previously created two separate zones) - `administratively_disabled` cannot be set on creation; sending it returns `422`, also for superadmins - `product` must be available: a product before its `publish_start` returns `422` with `detail` "The product is not available yet."; a product past its `publish_end` or a child product (one with a `parent`) also returns `422`. - `product` must be purchasable by `account`: a product that belongs to an account must belong to `account` or its parent account, and a prepaid product must belong to `account` itself, otherwise `422` on `/data/relationships/product` with `detail` "The selected product is invalid." Global products are not restricted. **Service bundle selection:** - Omit `service-bundle` when your account has exactly one applicable bundle — it is selected automatically. - Supply `service-bundle` when two or more bundles are applicable — **omitting it returns 422** (breaking change). - The submitted bundle must be linked to the account and applicable to the product, otherwise 422. - `service-bundle` is ignored on PATCH updates. **DNS template:** - Optionally supply `dns-template` to create the zone together with a copy of every record in the template (`type`, `name`, `content`, `ttl`, `priority`). - `$domain$` in the template records is replaced by the zone's domain. - The records are provisioned asynchronously; the response stays `202`. - The template must be global (no account) or belong to the `account` sent in the same request, otherwise `422` with `source.pointer` `/data/relationships/dns-template`. This applies to superadmins too. - An unknown or deleted template id returns `404`. - `dns-template` is create-only and never returned in responses. parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DnsZoneCreate' tags: - Dns Zones /dns-zones/{dns_zone_id}: get: x-cacholong-public: true summary: Get dns zone responses: '200': description: Returns the DNS zone details including all attributes and relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsZoneShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: dns-zones.show x-cli-group: dns-zones x-cli-name: show x-cli-help: Retrieve detailed information about a specific DNS zone x-cli-display-fields: - id - account.name - domain - status - active - administratively_disabled - dnssec - created_at - updated_at x-cli-positional-params: - dns_zone_id x-permission: show.dns.zone description: | Retrieve detailed information about a specific DNS zone by its unique identifier. A DNS zone is a specific portion of the DNS namespace managed by your organization. **DNS zone status:** - The `status` field indicates the zone's operational state - Possible values: `pending`, `processing`, `verifying`, `retrying`, `failed`, `success` - **Important:** Zone can only be updated when status is `success` - Contact support if zone is stuck in `failed` state **Active:** - `active: true` - Zone serves DNS queries (user-controllable) - `active: false` - Zone does not serve DNS queries (user-controllable) **Administratively disabled:** - `administratively_disabled: true` - A superadmin has disabled the zone: its records are removed at the DNS provider but kept here, so the zone does not resolve - Unlike `active`, only superadmins can change it - While disabled, the zone and its DNS records cannot be changed or deleted **DNSSEC configuration:** - DNSSEC can be enabled if domain extension supports it - DNSSEC keys are automatically fetched from external service provider - Some domain extensions do not support DNSSEC x-internal: false security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: account enum: - account - name-server-group - dns-records in: query name: include description: | Include related resources in the response. [How to use include](/#/#include). **Available includes:** - `account` - Include account owner details - `name-server-group` - Include the name servers serving this zone - `dns-records` - Include all DNS records (**Warning:** May be large for zones with many records) tags: - Dns Zones parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: dns_zone_id in: path required: true description: '**UUID of the DNS zone.** Use the list endpoint (`GET /dns-zones`) to discover available zone IDs for your account.' delete: x-cacholong-public: true summary: Delete dns zone operationId: dns-zones.delete x-cli-group: dns-zones x-cli-name: delete x-cli-help: Permanently delete a DNS zone and all associated DNS records x-cli-positional-params: - dns_zone_id x-permission: delete.dns.zone security: - API-token: [] responses: '204': $ref: '#/components/responses/204-NoContent' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Permanently delete a DNS zone and all associated DNS records. This action is irreversible and will cause the domain to stop resolving through our nameservers. **Deletion constraints:** - A zone that a domain registration uses cannot be deleted, by any user including superadmins; the request returns `422` with detail `This DNS zone is used by a domain registration. Point the domain registration at external name servers (a name server group) or delete the domain registration first.` To unblock it, send `dns-zone` `null` with a `name-server-group` in `PATCH /domain-registrations/{domain_registration_id}`, or delete the domain registration - All DNS records in the zone are permanently deleted - A zone that is administratively disabled cannot be deleted; the request returns `422` with detail `This DNS zone is currently administratively disabled.` - The zone must not already be locked by another pending operation; otherwise the request fails with `400 Bad Request` **Deletion behavior:** - Zone and all DNS records are permanently removed - Records cannot be recovered after deletion - No backup or recovery option available parameters: - $ref: '#/components/parameters/Accept' tags: - Dns Zones patch: x-cacholong-public: true summary: Update dns zone operationId: dns-zones.update x-cli-group: dns-zones x-cli-name: update x-cli-help: Update DNS zone attributes like active state or DNSSEC settings x-cli-positional-params: - dns_zone_id x-permission: update.dns.zone security: - API-token: [] responses: '200': description: Returns the updated DNS zone with all current attribute values. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsZoneShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '202': description: Update accepted for asynchronous processing and returns the zone in its current state. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/DnsZoneShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Update an existing DNS zone's attributes. Changes can be processed synchronously or asynchronously depending on the `meta.sync` parameter. **Update constraints:** - **Zone status must be `success` to allow updates** - Zones in `pending`, `processing`, `verifying`, `retrying`, or `failed` status cannot be updated - Wait for zone to reach `success` status before attempting updates - Adding/modifying DNS records will change the zone status temporarily - A zone that is administratively disabled cannot be updated; the request returns `422` with detail `This DNS zone is currently administratively disabled.` - The zone must not already be locked by another pending operation; otherwise the request fails with `400 Bad Request`. A request that fails validation returns `422` even when the zone is locked **Updatable attributes:** - `active` - Toggle active state (enables/disables DNS resolution) **Immutable fields:** - `id` - Zone identifier cannot be changed - `type` - Resource type is always `dns-zones` - `domain` - Set at creation and cannot be changed; delete the zone and create a new one to serve a different domain (see **Validation rules**) - `status` - Processing status is system-managed - `relationships` - Account assignment cannot be changed after creation (product only used during creation) - `created_at` - Creation timestamp is system-managed - `updated_at` - Update timestamp is automatically set **Processing modes:** - `meta.sync: true` - Synchronous update. Waits for validation and provider synchronization (up to 15 seconds, but changes are immediately active) - `meta.sync: false` (default) - Asynchronous update. Returns immediately and processes in background (faster response, monitor `status` field) **Validation rules:** - `domain` cannot be changed, also not by superadmins: a `domain` that differs from the stored domain (compared case-insensitively) returns `422` with `source.pointer` `/data/attributes/domain` and detail `The domain of a DNS zone cannot be changed. Delete the DNS zone and create a new one instead.` - Omitting `domain`, or sending the stored domain in any casing, is accepted; the stored domain is kept unchanged - `administratively_disabled` can only be set by superadmins; for other users sending it returns `422` with `source.pointer` `/data/attributes/administratively_disabled` **DNSSEC updates:** - Only superadmins can enable or disable DNSSEC; for other users a submitted `dnssec` value is ignored - DNSSEC keys are automatically fetched from external service provider - Some domain extensions do not support DNSSEC parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DnsZoneUpdate' tags: - Dns Zones /inbox-messages: get: summary: Get inbox messages responses: '200': description: Returns a collection of the authenticated user's inbox messages with pagination links. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/InboxMessageShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: inbox-messages.index x-cli-group: inbox-messages x-cli-name: list x-cli-help: Retrieve the messages in your inbox. x-cli-display-fields: - subject - from_name - received_at - read_at x-cli-positional-params: [] description: | Retrieve the messages in the authenticated user's inbox. No permission is required; every authenticated user can read their own inbox. Users only ever see their own inbox messages, superadmins included. Inbox messages are read-only; they cannot be created, updated or deleted. **Contents:** - One inbox message per message the user is a recipient of, once its delivery is settled: the mail was sent, or sending finally failed. - Drafts and messages that are still being sent are not listed. - Listing does **not** mark messages read, even though each item contains the full `message`. Open a message with `GET /inbox-messages/{inbox_message_id}` to mark it read. **Unread count:** - Request `filter[is_read]=false` and read `meta.page.total`, e.g. `GET /inbox-messages?filter[is_read]=false&page[size]=1`. **Sorting:** - Available sort field: `received_at` - Default: `-received_at` (newest first) x-internal: false x-cacholong-public: true security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: | Filter results by specific fields. [How to use filters](/#/#filters). Filters only narrow your own inbox. **Available filters:** - `filter[id]` - One or more inbox message IDs (comma-separated) - `filter[is_read]` - **true** for read messages only, **false** for unread messages only; any other value returns **400** - `filter[search]` - Search across subject, from_name, and from_email (case-insensitive, partial match) - `filter[subject]` - Filter by subject (case-insensitive, partial match) - `filter[message]` - Filter by message body (case-insensitive, partial match) - `filter[from_name]` - Filter by sender name (case-insensitive, partial match) - `filter[from_email]` - Filter by sender email address (case-insensitive, partial match) - `filter[received_at]`, `filter[received_at_*]` - Filter by the time the message reached the inbox with operators: `_eq`, `_gt`, `_gte`, `_lt`, `_lte` (ISO 8601 format) - `filter[read_at]`, `filter[read_at_*]` - Filter by the time the message was first opened with operators: `_eq`, `_gt`, `_gte`, `_lt`, `_lte` (ISO 8601 format) Text filters match anywhere in the value and are at most 255 characters. Include a `%` yourself (URL-encoded as `%25`) to control the wildcard position. name: filter[field] x-cli-filter-keys: is_read: schema: type: boolean help: Only read (true) or only unread (false) messages. schema: enum: - id - is_read - search - subject - message - from_name - from_email - received_at{_eq|_gt|_gte|_lt|_lte} - read_at{_eq|_gt|_gte|_lt|_lte} tags: - Inbox Messages /inbox-messages/{inbox_message_id}: get: summary: Get inbox message operationId: inbox-messages.show x-cli-group: inbox-messages x-cli-name: show x-cli-help: Retrieve a single inbox message by ID and mark it read. x-cli-positional-params: - inbox_message_id description: | Retrieve a single message from the authenticated user's inbox. No permission is required; every authenticated user can read their own inbox messages. Inbox messages are read-only; they cannot be updated or deleted. **Read marking:** - Fetching an inbox message through this endpoint marks it read. Every call counts, so do not use it to prefetch messages the user has not opened. - `read_at` is set on the first call and never changes after that. The response already contains the new `read_at`. - Listing the inbox with `GET /inbox-messages` does not mark anything read. **Access:** - Another user's inbox message returns **403**, superadmins included. - A message whose delivery is not settled yet (still being sent) returns **403**. - An unknown ID returns **404**. x-internal: false x-cacholong-public: true responses: '200': description: Returns the inbox message, with `read_at` already set by this request. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/InboxMessageShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: inbox_message_id in: path required: true description: Inbox message ID tags: - Inbox Messages /mail-addresses: get: x-cacholong-public: true summary: Get mail addresses x-cli-group: mail-addresses x-cli-name: list x-cli-help: Retrieve a paginated collection of mail addresses. responses: '200': description: Returns a collection of mail addresses with pagination links. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/MailAddressShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: mail-addresses.index description: | Retrieve a paginated collection of mail addresses. Mail addresses represent individual email addresses (e.g., user@example.com) configured within mail domains. **Mail address lifecycle:** - Addresses are created with initial status (typically `pending`) - Status progresses through: `pending` → `processing` → `success` - Status may become `retrying` if temporary issues occur, or `failed` if unrecoverable errors happen - Status changes when the address, its configuration, or its aliases are modified - Each mail address has independent status from its mail domain **Address configuration:** - `name` - Local part of email address (e.g., 'info' in 'info@example.com'), immutable after creation - `enabled` - Enable/disable the mail address - `allow_sending` - Control whether address can send email (can be disabled independently) - `allow_receiving` - Control whether address can receive email (can be disabled independently) - `keep_mail_on_forward` - When true, mail is delivered to both mailbox and forwards; when false, only forwarded - `catchall` - Receives all unmatched emails for the domain (superadmin-only, catches spam) **Related resources:** - Each mail address belongs to exactly one mail domain (immutable relationship) - Mail addresses can have multiple aliases (alternative email addresses that deliver to the same mailbox) x-internal: false x-permission: index.mail.address security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: Filter data per field or related field. Mail-domain is required filter for most users. [How to use filters](/#/#filters). name: filter[field] schema: enum: - id - name - enabled - catchall - allow_sending - allow_receiving - keep_mail_on_forward - mail-domain - status - schema: type: string example: mail-domain enum: - mail-domain - mail-domain.domain - mail-domain.domain.tld - aliases in: query name: include description: Related resources to include. Mail-domain, domain and tld included by default. tags: - Mail Addresses post: x-cacholong-public: true summary: Create mail address operationId: mail-addresses.create x-cli-group: mail-addresses x-cli-name: create x-cli-help: Create a new mail address for a mail domain. x-permission: create.mail.address security: - API-token: [] responses: '202': description: Accepts the request for background processing and returns the mail address with initial status. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailAddressShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Create a new mail address for a mail domain. The address will be created with an initial status and processed in the background. **Required attributes:** - `name` - Local part of email address (e.g., 'info' for 'info@example.com') - `password` - Password for mailbox access (minimum 10 characters, must include uppercase, lowercase, digit, and special character) - `password_confirmation` - Must match password - `allow_sending` - Whether address can send email (true/false) - `allow_receiving` - Whether address can receive email (true/false) - `keep_mail_on_forward` - Whether to keep mail in mailbox when forwards exist (true/false) **Optional attributes:** - `enabled` - Enable/disable the mail address (default: true) **Required relationships:** - `mail-domain` - The mail domain this address belongs to (immutable after creation) **Validation rules:** - Name must be valid email local part format (1-255 characters) - Name is immutable after creation (cannot be changed via PATCH) - Password must meet complexity requirements (enforced server-side) - Mail domain must exist and have status `success` - Combination of name and mail-domain must be unique - At least one of `allow_sending` or `allow_receiving` should be true for functional address - Catchall can only be set by superadmin **Forward configuration:** - Mail forwards are managed via a separate endpoint - Use `keep_mail_on_forward` to control whether mail is stored when forwards exist parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/MailAddressCreate' tags: - Mail Addresses /mail-addresses/{mail_address_id}: get: x-cacholong-public: true summary: Get mail address x-cli-group: mail-addresses x-cli-name: show x-cli-help: Retrieve details of a specific mail address. x-cli-positional-params: - mail_address_id responses: '200': description: Returns the mail address details including all attributes and relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailAddressShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: mail-addresses.show description: | Retrieve details of a specific mail address. Mail addresses represent individual email addresses configured within a mail domain. **Status values:** - `pending` - Address created but not yet processed - `processing` - Address configuration is currently in progress - `retrying` - Address operation encountered temporary issues and will retry - `failed` - Address operation failed (contact support) - `success` - Address is fully configured and operational **Configuration options:** - `name` - Local part of email (immutable after creation) - `enabled` - When false, address is disabled for sending and receiving - `allow_sending` - Can be disabled independently to prevent sending - `allow_receiving` - Can be disabled independently to prevent receiving - `keep_mail_on_forward` - Controls whether mail is stored when forwards exist - `catchall` - Receives unmatched emails for domain (superadmin-only, catches spam) **Relationships:** - `mail-domain` - The mail domain this address belongs to (immutable, many:1) - `aliases` - Alternative email addresses that deliver to this mailbox (1:many) x-internal: false x-permission: show.mail.address security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: mail-domain enum: - mail-domain - mail-domain.domain - mail-domain.domain.tld - aliases in: query name: include description: Related resources to include. Mail-domain, domain and tld included by default. tags: - Mail Addresses parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: mail_address_id in: path required: true description: Mail Address Id delete: x-cacholong-public: true summary: Delete mail address operationId: mail-addresses.delete x-cli-group: mail-addresses x-cli-name: delete x-cli-help: Delete a mail address permanently. x-cli-positional-params: - mail_address_id x-permission: delete.mail.address security: - API-token: [] responses: '202': $ref: '#/components/responses/202-NoContent' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Delete a mail address permanently. This operation is processed in the background and cannot be undone. **Impact:** - The mail address is permanently deleted - All aliases associated with this address are also deleted (cascade deletion) - All emails stored in the mailbox are permanently deleted - Historical data may be retained for audit purposes - The mail domain remains intact (not affected by address deletion) - The email address becomes available for re-creation parameters: - $ref: '#/components/parameters/Accept' tags: - Mail Addresses patch: x-cacholong-public: true summary: Update mail address operationId: mail-addresses.update x-cli-group: mail-addresses x-cli-name: update x-cli-help: Update a mail address configuration. x-cli-positional-params: - mail_address_id x-permission: update.mail.address security: - API-token: [] responses: '202': description: Accepts the request for background processing and returns the updated mail address. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailAddressShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Update a mail address configuration. The update will be processed in the background and the address status will change during processing. **Update constraints:** - Mail address must have status `success` to accept updates - Updates will trigger background processing - Address status will change during update processing - Alias changes also trigger status updates **Updatable attributes:** - `password` - Change mailbox password (can be omitted to leave unchanged) - `password_confirmation` - Required if changing password - `enabled` - Enable/disable the mail address - `allow_sending` - Enable/disable sending capability independently - `allow_receiving` - Enable/disable receiving capability independently - `keep_mail_on_forward` - Control mail storage when forwards exist **Immutable fields:** - `name` - Email local part cannot be changed after creation - `mail-domain` - Mail domain relationship cannot be changed - `created_at`, `updated_at` - System-managed timestamps **Validation rules:** - Password must meet complexity requirements if provided (enforced server-side) - Mail address must have status `success` to accept updates - Catchall can only be modified by superadmin parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/MailAddressUpdate' tags: - Mail Addresses /mail-addresses/{mail_address_id}/mail-domain: get: x-cacholong-public: true summary: Get mail address mail domain description: | Retrieve the mail domain associated with a specific mail address. This endpoint provides an alternative to using the `include=mail-domain` parameter when fetching a mail address. **Mail address-mail domain relationship:** - Every mail address belongs to exactly one mail domain (many:1 relationship) - This is the same mail domain that was linked during mail address creation - The mail address-mail domain relationship is immutable and cannot be changed after creation - The mail domain contains the domain name (e.g., 'example.com') for the address **When to use this endpoint:** - Use this endpoint when you only need mail domain details without the full mail address object - Use `include=mail-domain` on the mail address endpoint when you need both address and domain data together operationId: mail-addresses.mail-domain.show tags: - Mail Addresses x-internal: false x-cli-group: mail-addresses x-cli-name: show-mail-domain x-cli-help: Retrieve the mail domain associated with a mail address. x-cli-positional-params: - mail_address_id x-cli-display-fields: - id - name - enabled x-permission: show.mail.domain security: - API-token: [] parameters: - name: mail_address_id in: path required: true description: The ID of the mail address schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the mail domain associated with the mail address. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailDomainShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /mail-addresses/{mail_address_id}/aliases: get: x-cacholong-public: true summary: List mail address aliases description: | Retrieve all aliases belonging to a specific mail address. Aliases are alternative email addresses that deliver mail to the same mailbox. **Mail address-aliases relationship:** - Mail addresses can have multiple aliases (1:many relationship) - Aliases are created separately via the aliases endpoint - This endpoint is read-only - aliases are managed via the aliases endpoints - When a mail address is deleted, all its aliases are also deleted (cascade deletion) - Alias changes trigger status updates on the parent mail address **When to use this endpoint:** - Use this endpoint when you only need alias details without the full mail address object - Use `include=aliases` on the mail address endpoint when you need both address and alias data together operationId: mail-addresses.aliases.index tags: - Mail Addresses x-cli-group: mail-addresses x-cli-name: list-aliases x-cli-help: Retrieve all aliases for a mail address. x-cli-positional-params: - mail_address_id x-cli-display-fields: - id - alias - enabled - hidden x-permission: index.mail.address.alias security: - API-token: [] parameters: - name: mail_address_id in: path required: true description: The ID of the mail address schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' responses: '200': description: Returns a collection of mail address aliases belonging to the mail address. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/MailAddressAliasShow' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /mail-address-aliases: get: summary: Get mail address aliases x-cli-group: mail-address-aliases x-cli-name: list x-cli-help: Get mail address aliases. x-cacholong-public: true responses: '200': description: Returns a collection of mail address aliases with pagination links. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/MailAddressAliasShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: mail-address-aliases.index description: | Retrieve a paginated collection of mail address aliases. Mail address aliases provide alternative email addresses that deliver mail to a primary mail address. **Alias lifecycle:** - Aliases are created with initial status (pending or success depending on processing mode) - Status follows the standard lifecycle: pending → processing → success (or retrying/failed) - Aliases can only be updated when status is `success` - See status field documentation for complete lifecycle details **Uniqueness constraints:** - The `alias` value must be unique within the mail domain (across all mail addresses in that domain) - The same `alias` value can exist in different mail domains - For example, `info@domain1.com` and `info@domain2.com` can both exist as aliases x-internal: false x-permission: index.mail.address.alias security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - schema: type: string enum: - alias - enabled - id - mail-address - status in: query name: filter[field] description: Filter data per field or related field. Mail-address is required filter. [How to use filters](/#/#filters)..yaml' - schema: type: string example: mail-address enum: - mail-address in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Mail Address Aliases post: summary: Create mail address alias operationId: mail-address-aliases.create x-cli-group: mail-address-aliases x-cli-name: create x-cli-help: Create new mail address alias. x-cacholong-public: true x-permission: create.mail.address.alias security: - API-token: [] responses: '202': description: Accepts the request for background processing and returns the mail address alias with initial status. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailAddressAliasShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Create a new mail address alias for an existing mail address. The alias will be created with an initial status that depends on the processing mode. **Processing modes:** - `meta.sync: true` - Synchronous creation. Waits for validation (slower, but ready immediately) - `meta.sync: false` (default) - Asynchronous creation. Returns with `pending` status (faster response) **Required attributes:** - `alias` - The local part of the alias email address (e.g., 'info' for info@domain.com) - `enabled` - Whether the alias is enabled for mail handling **Required relationships:** - `mail-address` - The mail address this alias belongs to (immutable after creation) **Validation rules:** - `alias` must follow email local-part format validation - `alias` must be unique within the mail domain (across all mail addresses) - The same `alias` can exist in different mail domains - Associated mail address must exist and be accessible parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/MailAddressAliasCreate' tags: - Mail Address Aliases /mail-address-aliases/{mail_address_alias_id}: get: summary: Get mail address alias x-cli-group: mail-address-aliases x-cli-name: show x-cli-help: Get mail address alias with mail address alias id. x-cacholong-public: true x-cli-positional-params: - mail_address_alias_id responses: '200': description: Returns the mail address alias details including all attributes and relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailAddressAliasShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: mail-address-aliases.show description: | Retrieve detailed information about a specific mail address alias, including all attributes and relationships. **Alias configuration:** - `alias` - The local part of the email address (updatable) - `enabled` - Controls whether the alias can receive mail (updatable) - `status` - Current processing status (readonly) **Status values:** - `pending` - Alias created but not yet processed - `processing` - Alias operation is currently in progress - `success` - Alias is fully configured and operational - `retrying` - Alias operation failed and is waiting for retry - `failed` - Alias operation failed (contact support) x-internal: false x-permission: show.mail.address.alias security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: mail-address enum: - mail-address in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Mail Address Aliases parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: mail_address_alias_id in: path required: true description: Mail address alias Id delete: summary: Delete mail address alias operationId: mail-address-aliases.delete x-cli-group: mail-address-aliases x-cli-name: delete x-cli-help: Delete mail address alias with mail address alias id. x-cacholong-public: true x-cli-positional-params: - mail_address_alias_id x-permission: delete.mail.address.alias security: - API-token: [] responses: '202': $ref: '#/components/responses/202-NoContent' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Delete a mail address alias permanently. This action cannot be undone. **Deletion behavior:** - The alias is permanently removed from the mail system - Mail sent to the alias address will no longer be delivered to the mail address - The alias value becomes available for reuse within the same mail domain **Deletion constraints:** - Alias can only be deleted when status is `success` - Cannot delete aliases in `pending`, `processing`, or `retrying` states - Must wait for status to reach `success` or `failed` before deletion **Cascade deletion context:** - When a mail address is deleted, all its aliases are automatically deleted - Deleting an alias does NOT affect the associated mail address parameters: - $ref: '#/components/parameters/Accept' tags: - Mail Address Aliases patch: summary: Update mail address alias operationId: mail-address-aliases.update x-cli-group: mail-address-aliases x-cli-name: update x-cli-help: Update mail address alias with mail address alias id. x-cacholong-public: true x-cli-positional-params: - mail_address_alias_id x-permission: update.mail.address.alias security: - API-token: [] responses: '202': description: Accepts the request for background processing and returns the updated mail address alias. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailAddressAliasShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Update configuration settings for an existing mail address alias. The alias will be updated with an initial status that depends on the processing mode. **Processing modes:** - `meta.sync: true` - Synchronous update. Waits for validation (slower, but ready immediately) - `meta.sync: false` (default) - Asynchronous update. Returns with `pending` status (faster response) **Updatable attributes:** - `alias` - The local part of the alias email address - `enabled` - Whether the alias is enabled for mail handling **Immutable fields:** - `mail-address` relationship - Aliases cannot be moved between mail addresses - `status` - System-managed processing status - `created_at` / `updated_at` - System-managed timestamps **Validation rules:** - Alias can only be updated when current status is `success` - `alias` must follow email local-part format validation - `alias` must be unique within the mail domain when changed - Cannot update aliases in `pending`, `processing`, or `retrying` states parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/MailAddressAliasUpdate' tags: - Mail Address Aliases /mail-address-aliases/{mail_address_alias_id}/mail-address: get: summary: Get mail address alias mail address description: | Retrieve the mail address associated with a specific mail address alias. This endpoint provides an alternative to using the `include=mail-address` parameter when fetching an alias. **Alias-mail address relationship:** - Every alias belongs to exactly one mail address (many:1 relationship) - This is the same mail address that was linked during alias creation - The alias-mail address relationship is immutable and cannot be changed after creation - When a mail address is deleted, all its aliases are automatically deleted (cascade deletion) **When to use this endpoint:** - Use this endpoint when you only need mail address details without the full alias object - Use `include=mail-address` on the alias endpoint when you need both alias and mail address data together operationId: mail-address-aliases.mail-address.show tags: - Mail Address Aliases x-internal: false x-cacholong-public: true x-cli-group: mail-address-aliases x-cli-name: show-mail-address x-cli-help: Retrieve the mail address associated with a specific mail address alias. x-cli-positional-params: - mail_address_alias_id x-cli-display-fields: - id - name - enabled x-permission: show.mail.address security: - API-token: [] parameters: - name: mail_address_alias_id in: path required: true description: The ID of the mail address alias schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the mail address associated with the mail address alias. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailAddressShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /mail-domains: get: x-cacholong-public: true summary: Get mail domains operationId: mail-domains.index x-cli-display-fields: - domain - status - quota - enabled description: | Retrieve a paginated collection of mail domains. Mail domains represent email domains configured for an account to send and receive email. **Mail domain lifecycle:** - Domains are created with initial status (typically `pending`) - Status progresses through: `pending` → `processing` → `verifying` → `success` - Status may become `retrying` if temporary issues occur, or `failed` if unrecoverable errors happen - Status changes when the domain or its configuration is modified - Mail addresses and forwards have their own independent status attributes **Domain management:** - Each domain has a quota (storage limit in MB, range: 1024-1024000) - Domains can be enabled/disabled to control mail processing - Domains can be hidden (visible only to superadmins) - The domain name itself is immutable after creation **Related resources:** - Each mail domain belongs to exactly one account (immutable relationship) - Each mail domain has one service-mail resource (contains IMAP/SMTP connection settings) - Mail domains can have multiple mail-addresses and mail-forwards x-cli-group: mail-domains x-cli-name: list x-cli-help: Retrieve a paginated collection of mail domains. x-permission: index.mail.domain security: - API-token: [] responses: '200': description: Returns a collection of mail domains with pagination links. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/MailDomainShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - schema: type: string enum: - account - domain - enabled - hidden - id - status - quota{_eq|_gt|_gte|_lt|_lte} - service-mail in: query name: filter[field] x-cli-filter-keys: domain: schema: type: string maxLength: 255 help: Case-insensitive partial match on the domain name. description: | Filter data per field or related field. Account is required filter for most users. [How to use filters](/#/#filters). - `filter[domain]` - Partial, case-insensitive match on the domain name. - schema: type: string example: mail-addresses enum: - account - mail-addresses - service-mail in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Mail Domains requestBody: content: {} /mail-domains/{mail_domain_id}: get: x-cacholong-public: true summary: Get mail domain operationId: mail-domains.show description: | Retrieve details of a specific mail domain. Mail domains represent email domains configured for sending and receiving email. **Status values:** - `pending` - Domain created but not yet processed - `processing` - Domain configuration is currently in progress - `verifying` - Domain undergoing verification checks - `retrying` - Domain operation encountered temporary issues and will retry - `failed` - Domain operation failed (contact support) - `success` - Domain is fully configured and operational **Configuration options:** - `quota` - Storage limit in MB (range: 1024-1024000) - `enabled` - When false, mail delivery is stopped for this domain - `hidden` - When true, domain is visible only to superadmins - `domain` - Domain name is immutable after creation **Relationships:** - `account` - The account that owns this domain (immutable, 1:1) - `service-mail` - IMAP/SMTP connection settings (created separately, 1:1) - `mail-addresses` - Email addresses configured for this domain (1:many) x-cli-group: mail-domains x-cli-name: show x-cli-help: Retrieve details of a specific mail domain. x-cli-positional-params: - mail_domain_id x-permission: show.mail.domain security: - API-token: [] responses: '200': description: Returns the mail domain details including all attributes and relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailDomainShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: mail-addresses enum: - account - mail-addresses - service-mail in: query name: include description: Related resources to include. For some users service-mail is possible and included by default. [How to use include](/#/#include). tags: - Mail Domains parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: mail_domain_id in: path required: true description: mail domain Id /mail-domains/{mail_domain_id}/account: get: x-cacholong-public: true summary: Get mail domain account description: | Retrieve the account associated with a specific mail domain. This endpoint provides an alternative to using the `include=account` parameter when fetching a mail domain. **Mail domain-account relationship:** - Every mail domain belongs to exactly one account (1:1 relationship) - This is the same account that was linked during mail domain creation - The mail domain-account relationship is immutable and cannot be changed after creation - The account owns all mail addresses and configuration for this domain **When to use this endpoint:** - Use this endpoint when you only need account details without the full mail domain object - Use `include=account` on the mail domain endpoint when you need both domain and account data together operationId: mail-domains.account.show tags: - Mail Domains x-internal: false x-cli-group: mail-domains x-cli-name: show-account x-cli-help: Retrieve the account associated with a mail domain. x-cli-positional-params: - mail_domain_id x-permission: view.account security: - API-token: [] parameters: - name: mail_domain_id in: path required: true description: The ID of the mail domain schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the account associated with the mail domain. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/AccountShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /mail-domains/{mail_domain_id}/mail-addresses: get: x-cacholong-public: true summary: List mail domain mail addresses description: | Retrieve all mail addresses belonging to a specific mail domain. Mail addresses represent individual email addresses (e.g., user@example.com) configured within the domain. **Mail domain-mail addresses relationship:** - Mail domains can have multiple mail addresses (1:many relationship) - Mail addresses are created separately via the mail-addresses endpoint - This endpoint is read-only - mail addresses are managed via the mail-addresses endpoints - Each mail address has its own status attribute independent of the domain status **When to use this endpoint:** - Use this endpoint when you only need mail address details without the full mail domain object - Use `include=mail-addresses` on the mail domain endpoint when you need both domain and address data together operationId: mail-domains.mail-addresses.index tags: - Mail Domains x-internal: false x-cli-group: mail-domains x-cli-name: list-mail-addresses x-cli-help: Retrieve all mail addresses for a mail domain. x-cli-positional-params: - mail_domain_id x-permission: index.mail.address security: - API-token: [] parameters: - name: mail_domain_id in: path required: true description: The ID of the mail domain schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' responses: '200': description: Returns a collection of mail addresses belonging to the mail domain. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/MailAddressShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /mail-domains/{mail_domain_id}/service-mail: get: x-cacholong-public: true summary: Get mail domain service mail description: | Retrieve the service mail configuration associated with a specific mail domain. Service mail contains the connection details (IMAP/SMTP settings) that users need to configure their email clients. **Mail domain-service mail relationship:** - Every mail domain has exactly one service-mail resource (1:1 relationship) - Service-mail is created separately from the mail domain (not automatically created) - Service-mail contains IMAP and SMTP server settings, ports, and authentication details - This endpoint is read-only - service mail is managed via the service-mail endpoints **When to use this endpoint:** - Use this endpoint when you only need service-mail details without the full mail domain object - Use `include=service-mail` on the mail domain endpoint when you need both domain and service-mail data together operationId: mail-domains.service-mail.show tags: - Mail Domains x-internal: false x-cli-group: mail-domains x-cli-name: show-service-mail x-cli-help: Retrieve the service mail configuration for a mail domain. x-cli-positional-params: - mail_domain_id x-permission: view.service.mail security: - API-token: [] parameters: - name: mail_domain_id in: path required: true description: The ID of the mail domain schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the service mail configuration associated with the mail domain. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/ServiceMailShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /mail-forwards: get: summary: Get mail forwards x-cli-group: mail-forwards x-cli-name: list x-cli-display-fields: - src_address - dst_address - status x-cli-help: Get mail forwards. x-cacholong-public: true responses: '200': description: Returns a collection of mail forwards with pagination links. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/MailForwardShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: mail-forwards.index description: | Retrieve a paginated collection of mail forwards. Mail forwards automatically redirect incoming email from a source address to one or more destination addresses. **Mail forward lifecycle:** - Forwards are created with initial status (pending or success depending on processing mode) - Status follows the standard lifecycle: pending → processing → success (or retrying/failed) - Forwards can only be updated when status is `success` - See status field documentation for complete lifecycle details **Use cases:** - Individual routing: Forward all mail from one address to your personal mailbox - Distribution: Forward incoming mail to multiple recipients simultaneously - For complex distribution scenarios, consider using dedicated mailing software instead **DNS validation:** - By default, the system validates that email domains have valid MX records - Use `meta.src_address_ignore_dns_check: true` to skip validation for source address - Use `meta.dst_address_ignore_dns_check: true` to skip validation for destination addresses **Sorting:** - Available sort fields: `src_address`, `status`, `created_at`, `updated_at` - Default sort is `-created_at` x-internal: false x-permission: index.mail.forward parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: | Filter results by specific fields. Mail-domain is required filter for most users. [How to use filters](/#/#filters). **Available filters:** - `filter[id]` - One or more mail forward ids (comma-separated) - `filter[search]` - Search across src_address and dst_address (case-insensitive) - `filter[src_address]` - Partial, case-insensitive match on the source address - `filter[dst_address]` - Partial, case-insensitive match on any of the destination addresses - `filter[status]` - Processing status - `filter[mail-domain]` - One or more mail domain ids (comma-separated) name: filter[field] schema: enum: - search - id - src_address - dst_address - mail-domain - status - schema: type: string example: mail-domain enum: - mail-domain - mail-domain.domain - mail-domain.domain.tld in: query name: include description: Related resources to include. Mail-domain, domain and tld included by default. tags: - Mail Forwards post: summary: Create mail forward operationId: mail-forwards.create x-cli-group: mail-forwards x-cli-name: create x-cli-help: Create new mail forward. x-cacholong-public: true x-permission: create.mail.forward security: - API-token: [] responses: '202': description: Accepts the request for background processing and returns the mail forward with initial status. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailForwardShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Create a new mail forward to redirect incoming email from a source address to one or more destination addresses. The forward will be created with an initial status that depends on the processing mode. **Required attributes:** - `src_address` - Source email address that will receive mail (must be within the associated mail domain) - `dst_address` - Array of one or more destination email addresses (outside the forward's own mail domain) **Required relationships:** - `mail-domain` - The mail domain that the source address belongs to (immutable after creation) **Validation rules:** - `src_address` must be a valid email address ending with the name of the associated mail domain - `src_address` must be unique within the mail domain. A source address that already has a forward in the same mail domain returns **422** on `/data/attributes/src_address` (*The src_address has already been taken.*). Deleted forwards do not count - The same `src_address` may exist in another account's mail domain with the same name; mail domains are unique per account only - To send mail to more recipients, add them to the existing forward's `dst_address` instead of creating a second forward - `dst_address` must contain at least 1 and at most 100 valid email addresses - A missing or empty first `dst_address` entry returns **422** on `/data/attributes/dst_address/0` (*First destination email address is required.*) - `dst_address` entries must be distinct; a duplicate returns **422** on `/data/attributes/dst_address/` - `dst_address` entries must not end with the forward's own mail domain name - Both addresses are stored lower-cased - By default, system validates MX records for both source and destination domains - Use `meta.src_address_ignore_dns_check: true` to skip source address DNS validation - Use `meta.dst_address_ignore_dns_check: true` to skip destination addresses DNS validation parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/MailForwardCreate' tags: - Mail Forwards /mail-forwards/{mail_forward_id}: get: summary: Get mail forward x-cli-group: mail-forwards x-cli-name: show x-cli-help: Get mail forward with mail forward id. x-cacholong-public: true x-cli-positional-params: - mail_forward_id responses: '200': description: Returns the mail forward details including all attributes and relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailForwardShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: mail-forwards.show description: | Retrieve detailed information about a specific mail forward, including all attributes and relationships. **Forward configuration:** - `src_address` - Source email address (must be within mail domain, updatable) - `dst_address` - Array of destination email addresses (outside the forward's own mail domain, updatable) - `status` - Current processing status (readonly) **Status values:** - `pending` - Forward created but not yet processed - `processing` - Forward operation is currently in progress - `success` - Forward is fully configured and operational - `retrying` - Forward operation failed and is waiting for retry - `failed` - Forward operation failed (contact support) **DNS validation options:** - `meta.src_address_ignore_dns_check` - When true, skips MX record validation for source address - `meta.dst_address_ignore_dns_check` - When true, skips MX record validation for destination addresses x-internal: false x-permission: show.mail.forward security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: mail-domain enum: - mail-domain - mail-domain.domain - mail-domain.domain.tld in: query name: include description: Related resources to include. Mail-domain, domain and tld included by default. tags: - Mail Forwards parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: mail_forward_id in: path required: true description: mail forward Id delete: summary: Delete mail forward operationId: mail-forwards.delete x-cli-group: mail-forwards x-cli-name: delete x-cli-help: Delete mail forward with mail forward id. x-cacholong-public: true x-cli-positional-params: - mail_forward_id x-permission: delete.mail.forward security: - API-token: [] responses: '202': $ref: '#/components/responses/202-NoContent' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Delete a mail forward permanently. This action cannot be undone. **Deletion behavior:** - The forward is permanently removed from the mail system - Mail sent to the source address will no longer be forwarded to the destination addresses - The source address becomes available for reuse in other forwards - Deleting a forward does NOT affect the associated mail domain **Deletion constraints:** - Forward can only be deleted when status is `success` - Cannot delete forwards in `pending`, `processing`, or `retrying` states - Must wait for status to reach `success` or `failed` before deletion **Mail domain deletion dependency:** - Mail domains cannot be deleted if they have active forwards - All forwards must be deleted before the mail domain can be deleted parameters: - $ref: '#/components/parameters/Accept' tags: - Mail Forwards patch: summary: Update mail forward operationId: mail-forwards.update x-cli-group: mail-forwards x-cli-name: update x-cli-help: Update mail forward with mail forward id. x-cacholong-public: true x-cli-positional-params: - mail_forward_id x-permission: update.mail.forward security: - API-token: [] responses: '202': description: Accepts the request for background processing and returns the updated mail forward. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailForwardShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '409': $ref: '#/components/responses/409-Conflict' '415': $ref: '#/components/responses/415-UnsupportedMediaType' '422': $ref: '#/components/responses/422-UnprocessableEntity' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' description: | Update configuration settings for an existing mail forward. The forward will be updated with an initial status that depends on the processing mode. **Updatable attributes:** - `src_address` - Source email address (must be within the associated mail domain) - `dst_address` - Array of destination email addresses (outside the forward's own mail domain); replaces the full list - `meta.src_address_ignore_dns_check` - Skip DNS validation for source address - `meta.dst_address_ignore_dns_check` - Skip DNS validation for destination addresses **Immutable fields:** - `mail-domain` relationship - Forwards cannot be moved between mail domains - `status` - System-managed processing status - `created_at` / `updated_at` - System-managed timestamps **Validation rules:** - Forward can only be updated when current status is `success` - `src_address` must be a valid email address ending with the name of the associated mail domain - `src_address` must be unique within the mail domain. Changing it to an address that already has another forward in the same mail domain returns **422** on `/data/attributes/src_address` - Keeping the same `src_address` and re-sending the existing destinations is accepted - `dst_address` may be replaced by any reordering or subset of the current list (e.g. **[a, b]** → **[b, a]** or **[b]**) or by new addresses - `dst_address` must contain at least 1 and at most 100 valid email addresses - A missing or empty first `dst_address` entry returns **422** on `/data/attributes/dst_address/0` (*First destination email address is required.*) - `dst_address` entries must be distinct; a duplicate returns **422** on `/data/attributes/dst_address/` - `dst_address` entries must not end with the forward's own mail domain name - Cannot update forwards in `pending`, `processing`, or `retrying` states parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Content-Type' requestBody: required: true content: application/vnd.api+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/MailForwardUpdate' tags: - Mail Forwards /mail-forwards/{mail_forward_id}/mail-domain: get: summary: Get mail forward mail domain description: | Retrieve the mail domain associated with a specific mail forward. This endpoint provides an alternative to using the `include=mail-domain` parameter when fetching a forward. **Forward-mail domain relationship:** - Every forward belongs to exactly one mail domain (many:1 relationship) - This is the same mail domain that was linked during forward creation - The forward-mail domain relationship is immutable and cannot be changed after creation - The source address must always be within this mail domain - `src_address` is unique within this mail domain **Mail domain deletion dependency:** - Mail domains cannot be deleted if they have active forwards - All forwards must be deleted before the mail domain can be deleted - Deleting a forward does NOT affect the mail domain's status **When to use this endpoint:** - Use this endpoint when you only need mail domain details without the full forward object - Use `include=mail-domain` on the forward endpoint when you need both forward and mail domain data together operationId: mail-forwards.mail-domain.show tags: - Mail Forwards x-internal: false x-cacholong-public: true x-cli-group: mail-forwards x-cli-name: show-mail-domain x-cli-help: Retrieve the mail domain associated with a specific mail forward. x-cli-positional-params: - mail_forward_id x-permission: view.mail.domain security: - API-token: [] parameters: - name: mail_forward_id in: path required: true description: The ID of the mail forward schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the mail domain associated with the mail forward. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/MailDomainShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /mail-forwards/{mail_forward_id}/relationships/mail-domain: get: summary: Get mail forward mail domain relationship description: |- Retrieve the mail domain relationship linkage for a mail forward. The mail domain is set on create and read-only afterwards; there are no endpoints to change this relationship. **When to use this endpoint:** - Use this endpoint when you only need the mail domain identifier - Use `GET /mail-forwards/{mail_forward_id}/mail-domain` or `include=mail-domain` when you need the mail domain attributes operationId: mail-forwards.relationships.mail-domain.show x-internal: false x-cacholong-public: true x-permission: view.mail.domain x-cli-ignore: true x-cli-group: mail-forwards x-cli-name: show-mail-domain-relationship x-cli-help: Get the mail domain relationship linkage for a mail forward. x-cli-positional-params: - mail_forward_id security: - API-token: [] tags: - Mail Forwards parameters: - name: mail_forward_id in: path required: true description: The ID of the mail forward schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' responses: '200': description: Returns the mail domain relationship linkage. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: $ref: '#/components/schemas/RelationMailDomain' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /products: get: x-cacholong-public: true summary: Get products security: - API-token: [] x-permission: index.product x-cli-help: Retrieve a collection of products x-cli-group: products x-cli-name: list x-cli-display-fields: - name - product_type - price - publish_start responses: '200': description: Returns a collection of products with pagination links content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/ProductShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: products.index description: |+ Retrieve a paginated collection of products. A product is either global (no account) or owned by an account. **Visibility:** - Superadmins see all products and may omit `filter[account]` - Other users must pass `filter[account]`; without it the request returns **400** - `filter[account]` accepts only the user's own accounts, as an array or comma-separated list. Any other account returns **400** on `filter.account.0` - The result contains global products, products of the given accounts and products of their parent accounts. Prepaid products of the parent accounts are left out **Returned products:** - Only products whose publish window is open: `publish_start` in the past or `null`, and `publish_end` in the future or `null` - Only top-level products; child products are available through `include=children` - Only products with at least one service bundle, or prepaid products - These rules apply to the returned list only. Other endpoints that return products, and every `include` of products, return every product the user can see **Prepaid products:** - A prepaid product is a product with a `price` of **0** for a component that has already been paid for, such as the domain of a hosting order - It has product type **domain** or **ssl**, belongs to the purchasing account, has no service bundles and has a `publish_end` of `null` - It is named after the domain or service group it covers, and can only be used to order that domain or service - Once used, it is no longer returned - A parent account's prepaid products are not visible to its subaccounts; global prepaid products and an account's own prepaid products are - Recognise it by `prepaid` **true**. It has no service bundles, so do not ask for a service bundle choice - Filter with `filter[prepaid]=true|false` and sort with `sort=prepaid` / `sort=-prepaid`; both are available to every user Look up the prepaid product for a domain with: ``` GET /api/v1/products?filter[account]={account_id}&filter[name]={domain}&filter[product_type]=domain&filter[prepaid]=true ``` x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: | Filter results by specific fields. [How to use filters](/#/#filters). **Available filters:** - `filter[account]` - One or more of the user's own account ids (array or comma-separated). Required for non-superadmins; returns global products plus products of these accounts and their parent accounts, without the parent accounts' prepaid products - `filter[prepaid]` - **true** or **false**. Any other value returns **400** - `filter[search]` - Search across name and invoice_description (case-insensitive) - `filter[service-bundles]` - Filter by associated service bundle UUID name: filter[field] schema: enum: - account - prepaid - search - id - name - product_type - tlds.name - price{_eq|_gt|_gte|_lt|_lte} - created_at{_eq|_gt|_gte|_lt|_lte} - updated_at{_eq|_gt|_gte|_lt|_lte} - service-bundles - schema: type: string example: children enum: - account - children - parent - tlds - model-contracts - service-bundles - product-location in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Products /products/{product_id}: get: x-cacholong-public: true summary: Get product security: - API-token: [] x-permission: view.product x-cli-help: Retrieve details of a specific product x-cli-group: products x-cli-name: show x-cli-positional-params: - product_id responses: '200': description: Returns the product details including all attributes and relationships content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/ProductShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: products.show description: | Retrieve a single product. **Visibility:** - Superadmins can view every product - Other users can view a product when it is global, belongs to one of their accounts, or belongs to the parent account of one of their accounts and is not prepaid. Any other product, including a prepaid product of a parent account, returns **403** - Children the user cannot view are left out of the `children` include; a parent the user cannot view is returned as `null` in the `parent` include - The publish window, top-level and service bundle rules of the product list do not apply: unpublished, expired, child and bundle-less products are returned x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: children enum: - account - children - parent - tlds - model-contracts - service-bundles - product-location in: query name: include description: Related resources to include. [How to use include](/#/#include). tags: - Products parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: product_id in: path required: true description: Product Id /purchases: get: x-cacholong-public: true summary: Get purchases security: - API-token: [] x-permission: index.purchase x-cli-help: Retrieve a collection of purchases x-cli-group: purchases x-cli-name: list x-cli-display-fields: - account.name - product.name - description - units - date_activation responses: '200': description: Returns a collection of purchases with pagination links content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/PurchaseShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: purchases.index description: | Retrieve a paginated collection of purchases. x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: | Filter data per field or related field. Account is required filter for most users. [How to use filters](/#/#filters). **Available filters:** - `filter[product_type]` - Exact match on one product type or a comma-separated list (e.g. **dns,redirect**) - `filter[product]` - One or more product ids (array or comma-separated) name: filter[field] schema: enum: - id - product_type - description - units - date_purchase{_eq|_gt|_gte|_lt|_lte} - date_activation{_eq|_gt|_gte|_lt|_lte} - date_deactivation{_eq|_gt|_gte|_lt|_lte} - date_next_bill{_eq|_gt|_gte|_lt|_lte} - product - account - schema: type: string example: children enum: - children - parent - product - account in: query name: include description: |- Related resources to include. [How to use include](/#/#include). When you may not view the product of a purchase, its `relationships.product.data` is `null` and the product is not included. See [Account visibility of included resources](/#/#account-visibility-of-included-resources). tags: - Purchases /purchases/{purchase_id}: get: x-cacholong-public: true summary: Get purchase security: - API-token: [] x-permission: view.purchase x-cli-help: Retrieve details of a specific purchase x-cli-group: purchases x-cli-name: show x-cli-positional-params: - purchase_id responses: '200': description: Returns the purchase details including all attributes and relationships content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/PurchaseShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: purchases.show description: |- Get purchase with purchase id. **Visibility:** - The request returns **403** when the product of the purchase belongs to an account you cannot see, with or without `include=product`. Superadmins see every purchase. x-internal: false parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: children enum: - children - parent - product - account in: query name: include description: |- Related resources to include. [How to use include](/#/#include). When the product belongs to an account you cannot see, the request returns **403** instead of a `null` product. tags: - Purchases parameters: - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: purchase_id in: path required: true description: Purchase Id /purchases/{purchase_id}/product: get: x-cacholong-public: true summary: Get purchase product description: | Retrieve the product of a specific purchase. This endpoint provides an alternative to using the `include=product` parameter when fetching purchases. **Visibility:** - Superadmins see every product - Other users need the product `view` permission on the account of the purchase, and the product must be global, belong to one of their accounts, or belong to the direct parent account of one of their accounts. Otherwise the request returns **403** - The product is returned even when its publish window has closed **When to use this endpoint:** - Use this endpoint when you only need product details without the purchase - Use `include=product` on `GET /purchases` or `GET /purchases/{purchase_id}` when you need both purchase and product data together operationId: purchases.product.show tags: - Purchases x-internal: false x-cli-group: purchases x-cli-name: show-product x-cli-help: Retrieve the product of a specific purchase x-cli-positional-params: - purchase_id x-permission: view.product security: - API-token: [] parameters: - name: purchase_id in: path required: true description: Purchase Id schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the product of the purchase. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/ProductShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /service-bundles: get: x-cacholong-public: true summary: Get service bundles x-cli-help: Get service bundles representing collections of services responses: '200': description: Returns a collection of service bundles with pagination links. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/ServiceBundleShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: service-bundles.index description: | Retrieve a paginated collection of service bundles. 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. **Service bundle composition:** - A bundle contains one service per category, except PHP which can appear multiple times for different versions - When a service is picked from a bundle by category and version, the newest matching version is used - A bundle is linked to one or more products, and a product can be linked to one or more bundles (for example one bundle per web cluster) **Visibility:** - 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 **Sorting:** - Sortable fields: `name`, `description`, `created_at`, `updated_at` - Default sort: `-created_at` **Role when ordering:** When a purchase is created (`domain-registrations`, `dns-zones`, `vps`, `web-hostings`, `ssl-certificates`, standalone `web-redirects`) and the product has exactly one available bundle, it is chosen automatically. With two or more available bundles, the `service-bundle` relationship is required. The chosen bundle is recorded on the service group and cannot be changed afterwards. x-internal: false x-cli-group: service-bundles x-cli-name: list x-cli-display-fields: - account.name - name x-permission: index.service.bundle parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: | Filter results by specific fields. [How to use filters](/#/#filters). **Available filters:** - `filter[id]` - Filter by service bundle UUID (comma-separated for multiple) - `filter[name]` - Filter by bundle name (partial, case-insensitive match) - `filter[account]` - Filter by account UUID (comma-separated for multiple). Global bundles are always included in the result - `filter[service-category]` - Filter bundles containing a service of the given category (apache, cron, dns, domain, firewall, mysql, nginx, osuser, php, postgresql, shell, ssl, vps) - `filter[products]` - Filter by associated product UUID (comma-separated for multiple) - `filter[created_at_*]` - Filter by creation date with operators: `_eq`, `_gt`, `_gte`, `_lt`, `_lte` (ISO 8601 format) - `filter[updated_at_*]` - Filter by update date with operators: `_eq`, `_gt`, `_gte`, `_lt`, `_lte` (ISO 8601 format) **Examples:** `filter[name]=Webcluster`, `filter[service-category]=php`, `filter[created_at_gte]=2026-01-01` name: filter[field] x-cli-filter-keys: service-category: schema: type: string enum: - apache - cron - dns - domain - firewall - mysql - nginx - osuser - php - postgresql - shell - ssl - vps help: Only bundles containing a service of this category. schema: enum: - id - name - account - service-category - products - created_at{_eq|_gt|_gte|_lt|_lte} - updated_at{_eq|_gt|_gte|_lt|_lte} - schema: type: string example: account enum: - account - services - products in: query name: include description: | Include related resources in the response. [How to use include](/#/#include). **Available includes:** - `account` - Include the account that owns this service bundle - `services` - Include the services in the bundle - `products` - Include the products offered with this bundle **Example:** `include=account,services` to include both account owner and bundled services. tags: - Service Bundles /service-bundles/{service_bundle_id}: get: x-cacholong-public: true summary: Get service bundle x-cli-help: Get service bundle details by ID responses: '200': description: Returns the service bundle details including all attributes and relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/ServiceBundleShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: service-bundles.show description: | Retrieve a single service bundle. A service bundle is a named set of services that together deliver a product, and so decides on which servers or at which provider that product ends up. **Service bundle information:** - `account` - the owning account, or empty for a global bundle available to every account - `services` - the services in the bundle - `products` - the products offered with this bundle **Visibility:** - You can view global bundles and the bundles of your own accounts x-internal: false x-cli-group: service-bundles x-cli-name: show x-cli-positional-params: - service_bundle_id x-cli-display-fields: - account.name - name x-permission: show.service.bundle parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string example: account enum: - account - services - products in: query name: include description: | Include related resources in the response. [How to use include](/#/#include). **Available includes:** - `account` - Include the account owner details - `services` - Include the services in the bundle - `products` - Include the products offered with this bundle **When to use this parameter:** - Use `include` when you need the bundle and its related resources in a single request - Alternatively, use the dedicated endpoints (`GET /service-bundles/{service_bundle_id}/services`, `/products`, `/account`) when you only need the related resource - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: service_bundle_id in: path required: true description: UUID of the service bundle. Use the list endpoint (`GET /service-bundles`) to discover available service bundle IDs. tags: - Service Bundles /service-bundles/{service_bundle_id}/account: get: x-cacholong-public: true summary: Get service bundle account description: | Retrieve the account that owns a service bundle. `data` is `null` for a global bundle, which is available to every account. The account is set on create and cannot be changed afterwards. **When to use this endpoint:** - Use this endpoint when you only need the account, without the bundle itself - Use `include=account` on `GET /service-bundles/{service_bundle_id}` when you need the bundle and its account together operationId: service-bundles.account.show x-cli-help: Get the account associated with a service bundle x-internal: false security: - API-token: [] tags: - Service Bundles x-cli-group: service-bundles x-cli-name: show-account x-cli-positional-params: - service_bundle_id x-cli-display-fields: - name x-permission: view.account parameters: - name: service_bundle_id in: path required: true description: The ID of the service bundle schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' responses: '200': description: Returns the account that owns the service bundle, or `null` for a global bundle. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: oneOf: - $ref: '#/components/schemas/AccountShow' - type: 'null' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /service-bundles/{service_bundle_id}/relationships/account: get: x-cacholong-public: true summary: Get service bundle account relationship description: Retrieve the account relationship linkage for a service bundle. `data` is `null` for a global bundle. The account is set on create and cannot be changed afterwards. operationId: service-bundles.relationships.account.show x-internal: false x-permission: view.account x-cli-ignore: true x-cli-group: service-bundles x-cli-name: show-account-relationship x-cli-help: Get the account relationship linkage for a service bundle x-cli-positional-params: - service_bundle_id security: - API-token: [] tags: - Service Bundles parameters: - name: service_bundle_id in: path required: true description: The ID of the service bundle schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' responses: '200': description: Returns the account relationship linkage. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: $ref: '#/components/schemas/RelationAccountNullable' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /service-bundles/{service_bundle_id}/services: get: x-cacholong-public: true summary: List services description: | Retrieve the services in a service bundle. A bundle holds at most one service per service category, except PHP, which may appear several times for different versions. **When to use this endpoint:** - Use this endpoint when you only need the services, without the bundle itself - Use `include=services` on `GET /service-bundles/{service_bundle_id}` when you need the bundle and its services together operationId: service-bundles.services.index x-cli-help: List services for a service bundle x-internal: false security: - API-token: [] tags: - Service Bundles x-cli-group: service-bundles x-cli-name: list-services x-cli-positional-params: - service_bundle_id x-permission: index.services parameters: - name: service_bundle_id in: path required: true description: The ID of the service bundle schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' responses: '200': description: Returns a collection of services with pagination links. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/ServiceShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /service-bundles/{service_bundle_id}/relationships/services: get: x-cacholong-public: true summary: Get services relationship operationId: service-bundles.relationships.services.show description: Retrieve the services relationship linkage for a service bundle. x-cli-help: Get services relationship linkage x-internal: false x-cli-ignore: true x-cli-group: service-bundles x-cli-name: show-services-relationship x-cli-positional-params: - service_bundle_id x-permission: view.service.bundles parameters: - name: service_bundle_id in: path required: true description: The ID of the service bundle schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' responses: '200': description: Returns the services relationship linkage. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: $ref: '#/components/schemas/RelationServices' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' tags: - Service Bundles /service-bundles/{service_bundle_id}/products: get: x-cacholong-public: true summary: List products description: | Retrieve the products offered with a service bundle. This endpoint is read-only; products are changed through a full `POST` or `PATCH` of the service bundle, or through `/products/{product_id}/relationships/service-bundles`. **Visibility:** - Superadmins see every product offered with the bundle - Other users see a product when it is global, belongs to one of their accounts, or belongs to the parent account of one of their accounts and is not prepaid; other products are left out - The publish window and top-level rules of the product list do not apply: unpublished, expired and child products are returned - `include=products` on the service bundle returns the same products **When to use this endpoint:** - Use this endpoint when you only need the products, without the bundle itself - Use `include=products` on `GET /service-bundles/{service_bundle_id}` when you need the bundle and its products together operationId: service-bundles.products.index x-cli-help: List products for a service bundle x-internal: false security: - API-token: [] tags: - Service Bundles x-cli-group: service-bundles x-cli-name: list-products x-cli-positional-params: - service_bundle_id x-permission: index.products parameters: - name: service_bundle_id in: path required: true description: The ID of the service bundle schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' responses: '200': description: Returns a collection of products with pagination links. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/ProductShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /service-bundles/{service_bundle_id}/relationships/products: get: x-cacholong-public: true summary: Get service bundle products relationship description: Retrieve the products relationship linkage for a service bundle. This endpoint is read-only; products are changed through a full `POST` or `PATCH` of the service bundle, or through `/products/{product_id}/relationships/service-bundles`. operationId: service-bundles.relationships.products.show x-internal: false x-permission: index.products x-cli-ignore: true x-cli-group: service-bundles x-cli-name: show-products-relationship x-cli-help: Get the products relationship linkage for a service bundle x-cli-positional-params: - service_bundle_id security: - API-token: [] tags: - Service Bundles parameters: - name: service_bundle_id in: path required: true description: The ID of the service bundle schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' responses: '200': description: Returns the products relationship linkage. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: $ref: '#/components/schemas/RelationProducts' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /tlds: get: summary: Get tlds responses: '200': description: Returns a collection of TLDs with pagination links. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/TldShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: tlds.index description: | Retrieve the top-level domains (TLDs) available for domain registration, with their DNSSEC support and registration restrictions. TLDs are global and read-only: they cannot be created, updated or deleted through the API. No permission is required; every authenticated user can list every TLD, and `filter[account]` is not used. The `is_*auth_code*` attributes describe how the registry handles auth codes; they are `null` while not yet known. An authorization code can only be requested for a domain whose TLD has `is_auth_code_changeable` **true**. **Sorting:** - Available sort fields: `name`, `description`, `url`, `dnssec_algorithms`, `dnssec_allowed`, `dnssec_digests_allowed`, `dnssec_keys_allowed`, `restrictions`, `is_auth_code_requested`, `is_auth_code_available`, `is_auth_code_changeable`, `is_trade_auth_code_required`, `is_transfer_auth_code_required`, `status`, `created_at`, `updated_at` - `id` is not a sort field x-internal: false x-cacholong-public: true x-cli-group: tlds x-cli-name: list x-cli-help: List the top-level domains available for domain registration. x-cli-display-fields: - name - dnssec_allowed - status x-cli-positional-params: [] security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/fields' - in: query description: | Filter results by specific fields. [How to use filters](/#/#filters). **Available filters:** - `filter[search]` - Search across name and description (case-insensitive) - `filter[id]` - Filter by TLD UUID - `filter[name]` - Filter by TLD name without leading dot, e.g. **nl** - `filter[description]` - Filter by description - `filter[url]` - Filter by information URL - `filter[dnssec_algorithms]` - Filter by supported DNSSEC algorithms - `filter[dnssec_allowed]` - **true** or **false**: whether DNSSEC is allowed - `filter[dnssec_digests_allowed]` - **true** or **false**: whether DNSSEC digests are allowed - `filter[dnssec_keys_allowed]` - **true** or **false**: whether DNSSEC keys are allowed - `filter[restrictions]` - Filter by registration restrictions - `filter[is_auth_code_requested]` - **true** or **false**: whether the registry requests an auth code - `filter[is_auth_code_available]` - **true** or **false**: whether an auth code is available - `filter[is_auth_code_changeable]` - **true** or **false**: whether the auth code can be reset - `filter[is_trade_auth_code_required]` - **true** or **false**: whether an owner change requires an auth code - `filter[is_transfer_auth_code_required]` - **true** or **false**: whether a transfer requires an auth code The five `is_*auth_code*` filters are exact matches; a TLD whose value is `null` matches neither **true** nor **false**. - `filter[status]` - Case-insensitive substring match on the registrar status code (not the `status` attribute), e.g. **act** matches **ACT**; one value of at most 255 characters, a list is rejected with **400** - `filter[created_at_*]` - Filter by creation date with operators: `_eq`, `_gt`, `_gte`, `_lt`, `_lte` (ISO 8601 format) - `filter[updated_at_*]` - Filter by update date with operators: `_eq`, `_gt`, `_gte`, `_lt`, `_lte` (ISO 8601 format) **Examples:** `filter[name]=nl`, `filter[dnssec_allowed]=true` name: filter[field] schema: enum: - search - id - name - description - url - dnssec_algorithms - dnssec_allowed - dnssec_digests_allowed - dnssec_keys_allowed - restrictions - is_auth_code_requested - is_auth_code_available - is_auth_code_changeable - is_trade_auth_code_required - is_transfer_auth_code_required - status - created_at{_eq|_gt|_gte|_lt|_lte} - updated_at{_eq|_gt|_gte|_lt|_lte} tags: - Tlds /tlds/{tld_id}: get: summary: Get tld responses: '200': description: Returns the TLD details including all attributes. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/TldShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' operationId: tlds.show description: | Retrieve a single top-level domain (TLD) with its DNSSEC support and registration restrictions. TLDs are global and read-only. No permission is required; every authenticated user can retrieve every TLD. x-internal: false x-cacholong-public: true x-cli-group: tlds x-cli-name: show x-cli-help: Show a top-level domain with its DNSSEC support and registration restrictions. x-cli-positional-params: - tld_id security: - API-token: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f name: tld_id in: path required: true description: The ID of the TLD. tags: - Tlds /users/{user_id}/user-roles: get: summary: List user user-roles description: | Retrieve all user-roles associated with a specific user. This endpoint provides an alternative to using the `include=user-roles` parameter when fetching a user. **User-roles:** - User-roles represent the join between users, accounts, and roles (permissions) - Each user-role grants this user access to a specific account with a defined role - User-roles are managed separately via the user-roles endpoint - this endpoint is read-only - To create or modify user-roles, use the user-roles endpoints **When to use this endpoint:** - Use this endpoint when you only need user-role details without the full user object - Use `include=user-roles` on the user endpoint when you need both user and user-role data together **Pagination:** - Default page size: 10 user-roles - Maximum page size: 50 user-roles - Response includes pagination links: `first`, `last`, `prev`, `next`, `self` - See [How to use pagination](/#/#pagination) for navigation details **Sorting:** - Available sort fields: `created_at` - Use `-` prefix for descending order - See [How to use sorting](/#/#sorting) for sorting syntax **Fields:** - Use `fields[user-roles]` parameter to request specific attributes only (sparse fieldsets) - Reduces payload size when only certain fields are needed - See [How to use fields](/#/#fields) for field selection syntax **Related resources:** - Include `account` to get account details for each user-role - Include `role` to get role/permission details for each user-role operationId: users.user-roles.index x-cli-help: List all user-roles for a user tags: - Users x-internal: false x-cacholong-public: true x-cli-group: users x-cli-name: list-user-roles x-cli-positional-params: - user_id x-permission: index.user.role security: - API-token: [] parameters: - name: user_id in: path required: true description: The ID of the user schema: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/page_number_' - $ref: '#/components/parameters/page_size_' - schema: type: string example: account enum: - account - role - user in: query name: include description: '[How to use include](/#/#include)' required: false responses: '200': description: Returns a collection of user-roles with pagination links. headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiIndex' - type: object properties: data: type: array maxItems: 50 items: $ref: '#/components/schemas/UserRoleShow' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' /users/me: get: summary: Get me x-cli-help: Get my user data operationId: users.me description: Get my user data. x-internal: false x-cacholong-public: true x-cli-group: users x-cli-name: me x-cli-positional-params: [] x-permission: show.user responses: '200': description: Returns the current user's details including all attributes and relationships. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiShow' - type: object properties: data: $ref: '#/components/schemas/UserShow' headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': $ref: '#/components/responses/400-BadRequest' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': $ref: '#/components/responses/404-NotFound' '406': $ref: '#/components/responses/406-NotAcceptable' '429': $ref: '#/components/responses/429-TooManyAttempts' '500': $ref: '#/components/responses/500-InternalServerError' '503': $ref: '#/components/responses/503-ServiceUnavailable' parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/fields' tags: - Users components: schemas: AddressShow: x-cacholong-public: true title: Address description: Represents an address for either a user ór company. Users are allowed to work with all addresses from the same account. examples: - type: addresses id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: street: Seerob number: '21' suffix: zipcode: 9051 VA city: Stiens state: country: NL created_at: '2024-01-15T10:30:45.123456Z' updated_at: '2024-01-15T10:30:45.123456Z' relationships: user: data: type: users id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f company: data: links: self: /api/v1/addresses/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - type: addresses id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: street: Seerob number: '21' suffix: a zipcode: 9051 VA city: Stiens state: Friesland country: NL created_at: '2024-01-15T10:30:45.123456Z' updated_at: '2024-01-15T10:30:45.123456Z' relationships: user: data: company: data: type: companies id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f links: self: /api/v1/addresses/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f allOf: - $ref: '#/components/schemas/AddressBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 readOnly: true example: '2024-01-15T10:30:45.123456Z' description: Timestamp when the address was created. updated_at: type: string format: date-time maxLength: 27 readOnly: true example: '2024-01-15T10:30:45.123456Z' description: Timestamp when the address was last updated. relationships: type: object properties: user: $ref: '#/components/schemas/RelationUser' description: The user associated with this address. company: $ref: '#/components/schemas/RelationCompany' description: The company associated with this address. Company: $ref: '#/components/schemas/CompanyShow' DnsRecord: $ref: '#/components/schemas/DnsRecordShow' DnsZoneRestorePoint: $ref: '#/components/schemas/DnsZoneRestorePointShow' DnsZoneRestorePointCreate: x-cacholong-public: true x-internal: true title: Dns zone restore point create description: Schema for creating a new DNS zone restore point via POST request. allOf: - $ref: '#/components/schemas/DnsZoneRestorePointBase' DnsZoneRestorePointUpdate: x-cacholong-public: true x-internal: true title: Dns zone restore point update description: Schema for renaming a DNS zone restore point via PATCH request. allOf: - $ref: '#/components/schemas/DnsZoneRestorePointBase' - type: object properties: relationships: type: object properties: dns-zone: readOnly: true DnsZoneRestorePointRollback: x-cacholong-public: true title: Dns zone restore point rollback description: Resource object for rolling back a DNS zone to a restore point. type: object required: - type - id properties: type: type: string format: const const: dns-zone-restore-points id: type: string format: uuid maxLength: 36 description: UUID of the restore point; must match the `dns_zone_restore_point_id` path parameter. example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 meta: type: object properties: sync: type: - boolean - 'null' description: Controls whether the rollback is processed synchronously or asynchronously. x-cli-help: Process rollback synchronously (true) or asynchronously (false) default: false DnsRecordBase: x-cacholong-public: true title: Dns record base description: Base schema for DNS records containing shared properties across all operations. type: object properties: type: type: string format: const const: dns-records id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. attributes: type: object properties: status: type: - string enum: - pending - processing - verifying - retrying - failed - success description: Current processing status of the DNS record. x-cli-help: Processing status (pending, processing, verifying, retrying, failed, success) example: success readOnly: true dns_record_type: type: string enum: - A - AAAA - CAA - CNAME - MX - NS - SRV - SSHFP - TLSA - TXT description: The type of DNS record. x-cli-help: DNS record type (A, AAAA, CAA, CNAME, MX, NS, SRV, SSHFP, TLSA, TXT) example: AAAA name: type: string format: hostname maxLength: 255 description: The name/hostname for this DNS record, stored lower-cased. x-cli-help: Hostname or subdomain for this record example: cacholong.nl content: type: string format: dns-content maxLength: 10000 description: The content value for this DNS record, stored exactly as submitted; for a record with `spf_flatten` enabled, the SPF policy to flatten, which flattening never overwrites. x-cli-help: Record content (IP address, hostname, text value, or the SPF policy to flatten) example: 2a00:1bd0:197:1::22 ttl: type: integer format: int32 enum: - 1 - 300 - 900 - 3600 - 86400 - 604800 minimum: 1 maximum: 604800 example: 300 description: Time to live in seconds. x-cli-help: Cache duration in seconds (1, 300, 900, 3600, 86400, 604800) priority: type: - integer - 'null' format: int32 description: Priority value for MX and SRV records. x-cli-help: Priority (required for MX and SRV records only) minimum: 0 maximum: 32767 example: spf_flatten: type: - boolean - 'null' description: Enables SPF flattening, which resolves the SPF policy in `content` to static IP addresses and publishes the result instead. Only allowed on a TXT record belonging to a DNS zone. x-cli-help: Enable SPF flattening of the policy in content (TXT records in a DNS zone only) default: false example: true spf_flattened_content: type: - string - 'null' maxLength: 10000 description: The RFC 7208-resolved, flattened SPF result that is published to the DNS provider instead of `content` while `spf_flatten` is true. x-cli-help: Resolved SPF content published to the DNS provider readOnly: true example: v=spf1 ip4:192.0.2.1 ip4:192.0.2.2 ~all spf_status: type: - string - 'null' enum: - ok - perm_error - resolution_failed description: Outcome of the last SPF resolution attempt. x-cli-help: SPF resolution status (ok, perm_error, resolution_failed) readOnly: true example: ok spf_last_flattened_at: type: - string - 'null' format: date-time maxLength: 27 description: Timestamp when the record was last successfully re-flattened. x-cli-help: When SPF flattening last ran successfully readOnly: true example: '2038-01-19T03:14:07.000000Z' spf_last_changed_at: type: - string - 'null' format: date-time maxLength: 27 description: Timestamp when the flattened SPF content last actually changed. x-cli-help: When the flattened SPF content last changed readOnly: true example: '2038-01-19T03:14:07.000000Z' required: - dns_record_type - name - content meta: type: object properties: sync: type: - boolean - 'null' description: Controls synchronous or asynchronous processing. x-cli-help: Process synchronously (true) or asynchronously (false) default: false DnsRecordCreateWithZone: x-cacholong-public: true x-internal: true title: Create DNS record with DNS zone description: Schema for creating a DNS record within a DNS zone; supports SPF flattening (`spf_flatten`) on TXT records. allOf: - $ref: '#/components/schemas/DnsRecordBase' - type: object properties: relationships: type: object properties: dns-zone: $ref: '#/components/schemas/RelationDnsZone' description: The DNS zone to add this record to. x-cli-help: DNS zone that will own this record required: - dns-zone DnsRecordCreateWithTemplate: x-cacholong-public: true x-internal: true title: Create DNS record with DNS template description: Schema for creating a DNS record within a DNS template; SPF flattening (`spf_flatten`) is not available on template records. allOf: - $ref: '#/components/schemas/DnsRecordBase' - type: object properties: relationships: type: object properties: dns-template: $ref: '#/components/schemas/RelationDnsTemplate' description: The DNS template to add this record to. x-cli-help: DNS template that will own this record required: - dns-template DnsRecordUpdate: x-cacholong-public: true x-internal: true title: Dns record update description: Schema for updating an existing DNS record via PATCH request. The relationships (dns-zone, dns-template) cannot be modified after creation. allOf: - $ref: '#/components/schemas/DnsRecordBase' - type: object properties: relationships: type: object properties: dns-zone: $ref: '#/components/schemas/RelationDnsZone' description: The DNS zone containing this record. x-cli-help: DNS zone that owns this record readOnly: true dns-template: $ref: '#/components/schemas/RelationDnsTemplate' description: The DNS template containing this record. x-cli-help: DNS template that owns this record readOnly: true DnsTemplateShow: x-cacholong-public: true title: Dns template description: Complete DNS template resource returned by GET operations with all attributes and relationships. allOf: - $ref: '#/components/schemas/DnsTemplateBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the DNS template was created. x-cli-help: Creation timestamp in ISO 8601 format readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: Timestamp when the DNS template was last updated. x-cli-help: Last update timestamp in ISO 8601 format readOnly: true relationships: type: object properties: dns-records: $ref: '#/components/schemas/RelationDnsRecords' description: Collection of DNS records in this template. x-cli-help: All DNS records defined in this template readOnly: true DnsTemplateCreate: x-cacholong-public: true x-internal: true title: Dns template create description: Schema for creating a new DNS template via POST request. allOf: - $ref: '#/components/schemas/DnsTemplateBase' DnsTemplateUpdate: x-cacholong-public: true x-internal: true title: Dns template update description: Schema for updating an existing DNS template via PATCH request. allOf: - $ref: '#/components/schemas/DnsTemplateBase' - type: object properties: relationships: type: object properties: account: readOnly: true dns-records: $ref: '#/components/schemas/RelationDnsRecords' description: Collection of DNS records in this template. x-cli-help: All DNS records defined in this template readOnly: true DnsZone: $ref: '#/components/schemas/DnsZoneShow' DnsZoneCreate: x-cacholong-public: true x-internal: true title: Dns zone create description: Schema for creating a new DNS zone via POST request. allOf: - $ref: '#/components/schemas/DnsZoneBase' - type: object properties: relationships: type: object properties: service-bundle: $ref: '#/components/schemas/RelationServiceBundle' description: Service bundle to use for provisioning. Optional when exactly one bundle is applicable; required when two or more are applicable (else 422). Ignored on update. dns-template: $ref: '#/components/schemas/RelationDnsTemplateNullable' description: DNS template whose records are copied into the new zone; must be global or owned by the posted account. Create-only and never returned in responses. writeOnly: true DnsZoneUpdate: x-cacholong-public: true x-internal: true title: Dns zone update description: Schema for updating an existing DNS zone via PATCH request. allOf: - $ref: '#/components/schemas/DnsZoneBase' - type: object properties: attributes: type: object properties: domain: readOnly: true administratively_disabled: type: boolean description: Set to `true` to disable the zone at the DNS provider or `false` to enable it again; superadmins only. x-cli-help: Administratively disable (true) or enable (false) the zone readOnly: true relationships: type: object properties: account: readOnly: true product: readOnly: true service-bundle: readOnly: true required: - type - id InboxMessageBase: x-cacholong-public: true title: Inbox Message Base description: Base schema for inbox message resources. type: object properties: type: type: string format: const const: inbox-messages id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index and show. readOnly: true attributes: type: object properties: subject: type: string format: subject minLength: 1 maxLength: 255 example: Scheduled Maintenance readOnly: true description: Subject of the message. x-cli-help: Subject of the message. message: type: string format: message maxLength: 10000 example: | Quick heads up! We're conducting routine maintenance for system enhancements. # Details - Starts: 2038-01-19 at 03:14:07 UTC - Duration: approximately 1 hour readOnly: true description: Body of the message in Markdown, as written by the sender. x-cli-help: Body of the message in Markdown. from_name: type: string format: name minLength: 1 maxLength: 255 example: CPP readOnly: true description: Name of the sender. x-cli-help: Name of the sender. from_email: type: string format: email minLength: 1 maxLength: 255 example: no-reply@cacholong.nl readOnly: true description: Email address of the sender. x-cli-help: Email address of the sender. InboxMessageShow: x-cacholong-public: true title: Inbox Message description: Represents a message in the inbox of the authenticated user. examples: - type: inbox-messages id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: subject: Scheduled Maintenance message: | Quick heads up! We're conducting routine maintenance for system enhancements. # Details - Starts: 2038-01-19 at 03:14:07 UTC - Duration: approximately 1 hour from_name: CPP from_email: no-reply@cacholong.nl received_at: '2007-09-01T12:00:00.000000Z' read_at: '2038-01-19T03:14:07.000000Z' links: self: /api/v1/inbox-messages/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f allOf: - $ref: '#/components/schemas/InboxMessageBase' - type: object properties: attributes: type: object properties: received_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' readOnly: true description: When the message reached the inbox, i.e. when its mail was sent or when sending finally failed. x-cli-help: When the message reached the inbox. read_at: type: - string - 'null' format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' readOnly: true description: When the user first opened the message through the show endpoint; `null` while unread. x-cli-help: When the message was first opened. JsonApiImplementation: type: object description: Information about implementation. x-examples: example-1: version: '1.0' title: JsonApi Implementation examples: [] x-internal: false x-tags: - Internal properties: jsonapi: type: object description: |- Server implemenation. properties: version: type: string format: version maxLength: 5 description: Highest JSON API version supported. example: '1.0' readOnly: true readOnly: true readOnly: true JsonApiIndex: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - $ref: '#/components/schemas/JsonApiPagination' examples: [] x-internal: false title: JsonApi Index x-tags: - Internal JsonApiPagination: type: object description: Links to traverse paginated data set. x-examples: example-1: links: first: http://ccp.localhost/api/v1/accounts?page%5Bnumber%5D=1&page%5Bsize%5D=1 last: http://ccp.localhost/api/v1/accounts?page%5Bnumber%5D=16&page%5Bsize%5D=1 next: http://ccp.localhost/api/v1/accounts?page%5Bnumber%5D=3&page%5Bsize%5D=1 prev: http://ccp.localhost/api/v1/accounts?page%5Bnumber%5D=1&page%5Bsize%5D=1 title: JsonApi Pagination examples: [] x-internal: false x-tags: - Internal properties: meta: type: object properties: page: type: object description: Meta information about pagination. properties: currentPage: type: integer format: int32 description: Current page number. example: 1 minimum: 1 maximum: 100000 readOnly: true from: type: integer format: int32 description: Shows resources **from** this number. example: 1 minimum: 0 maximum: 100000 readOnly: true lastPage: type: integer format: int32 minimum: 0 maximum: 100000 description: Last page number. example: 1000 readOnly: true perPage: type: integer format: int32 minimum: 1 maximum: 50 description: Total amount of resources per page. example: 15 readOnly: true to: type: integer format: int32 description: Shows resources **to** this number. example: 15 minimum: 0 maximum: 100000 readOnly: true total: type: integer format: int32 description: Total amount of resources. example: 30 minimum: 0 maximum: 100000 readOnly: true readOnly: true readOnly: true links: type: object description: | Pagination links. If a key is missing, it means that particular link is unavailable. properties: first: type: string format: uri maxLength: 255 description: The first page of data. example: https://localhost/api/v1/resource?page%5Bnumber%5D=1&page%5Bsize%5D=15 readOnly: true last: type: string format: uri maxLength: 255 description: The last page of data. example: https://localhost/api/v1/resource?page%5Bnumber%5D=1000&page%5Bsize%5D=15 readOnly: true next: type: - string - 'null' format: uri maxLength: 255 description: The next page of data. example: https://localhost/api/v1/resource?page%5Bnumber%5D=4&page%5Bsize%5D=15 readOnly: true prev: type: - string - 'null' format: uri maxLength: 255 description: The previous page of data. example: https://localhost/api/v1/resource?page%5Bnumber%5D=2&page%5Bsize%5D=15 readOnly: true readOnly: true readOnly: true JsonApiResourceLinkSelf: type: object description: Links with self. title: JsonApi Resource link x-internal: false x-tags: - Internal properties: links: type: object properties: self: type: string format: uri maxLength: 255 example: https://localhost/api/v1/resource/61a7418e-94a1-4088-9577-a8d2b2e9dd7c description: Self link for resource object. readOnly: true readOnly: true readOnly: true JsonApiShow: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - $ref: '#/components/schemas/JsonApiResourceLinkSelf' examples: [] x-internal: false title: JsonApi Show x-tags: - Internal Product: $ref: '#/components/schemas/ProductShow' Purchase: $ref: '#/components/schemas/PurchaseShow' ServiceBundle: $ref: '#/components/schemas/ServiceBundleShow' Tld: $ref: '#/components/schemas/TldShow' RelationAccount: x-tags: - Internal x-cacholong-public: true type: object properties: data: type: object properties: type: type: string format: const const: accounts id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 RelationAddresses: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: addresses id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationCompany: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: companies id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 RelationDnsRecords: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: dns-records id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationDnsTemplate: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: dns-templates id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 RelationDnsZone: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: dns-zones id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 RelationNameServerGroup: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: name-server-groups id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 RelationProduct: x-tags: - Internal x-cacholong-public: true type: object properties: data: type: object properties: type: type: string format: const const: products id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 RelationProducts: x-tags: - Internal x-cacholong-public: true type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: products id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationPurchase: x-tags: - Internal x-cacholong-public: true type: object properties: data: type: object properties: type: type: string format: const const: purchases id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 RelationPurchases: x-tags: - Internal x-cacholong-public: true type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: purchases id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationServiceBundles: x-tags: - Internal x-cacholong-public: true type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: service-bundles id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationServices: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: services id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f x-internal: true RelationTlds: x-tags: - Internal x-cacholong-public: true type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: tlds id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationUser: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: users id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 RelationUsers: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: users id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationVps: x-tags: - Internal x-cacholong-public: true type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: vps id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationWebHostings: x-tags: - Internal x-cacholong-public: true type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: web-hostings id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f AccountBase: x-cacholong-public: true title: Account Base description: Base schema for account with shared properties. type: object properties: type: type: string format: const const: accounts id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object properties: name: type: string format: name minLength: 1 maxLength: 255 example: Cacholong description: The unique account name. x-cli-help: The unique account name description: type: string format: description maxLength: 10000 example: Specialist in managed hosting and WordPress optimization. description: Optional description of the account. x-cli-help: Optional description of the account required: - name RelationUserRoles: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: user-roles id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f AccountShow: x-cacholong-public: true title: Account description: Represents an account. examples: - type: accounts id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: name: Cacholong description: Specialist in managed hosting and WordPress optimization. created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' links: self: /api/v1/accounts/[id] allOf: - $ref: '#/components/schemas/AccountBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the account was created. x-cli-help: Timestamp when the account was created readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: Timestamp when the account was last updated. x-cli-help: Timestamp when the account was last updated readOnly: true relationships: type: object properties: parent: $ref: '#/components/schemas/RelationAccount' description: The parent account this account was created under (if this is a sub-account). x-cli-help: The parent account (if this is a sub-account) company: $ref: '#/components/schemas/RelationCompany' description: The company associated with this account. x-cli-help: The company associated with this account user-roles: $ref: '#/components/schemas/RelationUserRoles' description: The user-roles that provide access to this account. x-cli-help: The user-roles that provide access to this account Error: x-tags: - Internal type: object description: Error object may have the following members. x-examples: example-1: detail: Sort parameter test2 is not allowed. source: parameter: sort status: '400' title: Invalid Query Parameter properties: detail: type: string format: name maxLength: 255 description: Explanation specific to this occurrence of the problem (can be localized). readOnly: true source: type: object description: Reference to the source of the error. properties: pointer: type: string format: json-pointer maxLength: 255 description: JSON Pointer [RFC6901] to the associated entity in the request document. example: /data/attributes/[attribute] readOnly: true parameter: type: string format: json-pointer maxLength: 255 description: Which URI query parameter caused the error. example: /data/parameters/[attribute] readOnly: true readOnly: true status: type: string format: status maxLength: 3 description: HTTP status code applicable to this problem. readOnly: true title: type: string format: title maxLength: 255 description: Short summary of the problem, present on every error object (can be localized). readOnly: true readOnly: true UserRoleBase: title: UserRoleBase description: Base schema for user-role assignment. type: object properties: type: type: string format: const const: user-roles id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: The unique identifier for the user-role assignment. x-cli-help: Unique identifier readOnly: true attributes: type: object properties: {} description: UserRole is a join table with no additional attributes beyond timestamps. x-cli-help: No mutable attributes RelationRole: x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: roles id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 UserRoleShow: title: UserRoleShow description: User-role assignment for GET responses. examples: - type: user-roles id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' relationships: account: data: type: accounts id: ef37f61a-93cd-4e73-9fab-2d002062f190 user: data: type: users id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f role: data: type: roles id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f links: self: /api/v1/user-roles/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f allOf: - $ref: '#/components/schemas/UserRoleBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the user-role assignment was created. x-cli-help: Timestamp when created readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: Timestamp when the user-role assignment was last updated. x-cli-help: Timestamp when last updated readOnly: true relationships: type: object properties: account: $ref: '#/components/schemas/RelationAccount' description: The account this user-role assignment belongs to. x-cli-help: The account user: $ref: '#/components/schemas/RelationUser' description: The user being assigned the role. x-cli-help: The user role: $ref: '#/components/schemas/RelationRole' description: The role being assigned to the user. x-cli-help: The role required: - account - user - role AddressBase: title: Address Base description: Base schema for address with shared properties type: object properties: type: type: string format: const const: addresses id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Unique identifier for the address resource. readOnly: true attributes: type: object properties: street: type: string format: string minLength: 1 maxLength: 255 example: Seerob description: Can contain any letter (combined with accent) from any language, any kind of hyphen or dash, single or alternative quote or space. number: type: string format: string minLength: 1 maxLength: 255 example: '21' description: Can contain any number from any language. suffix: type: string format: string maxLength: 255 example: a description: Can contain any letter or number from any language or space. zipcode: type: string format: string minLength: 1 maxLength: 255 example: 9051 VA description: Must contain valid zipcode from NL,BE,DE,GB or US. city: type: string format: string minLength: 1 maxLength: 255 example: Stiens description: Can contain any letter from any language or space. state: type: string format: string maxLength: 255 example: Friesland description: Can contain any letter (combined with accent) from any language, any kind of hyphen or dash, single or alternative quote or space. country: type: string format: string minLength: 2 maxLength: 2 example: NL description: Must contain two uppercase letters (A-Z). required: - street - number - zipcode - city - country AddressCreateWithUser: title: Address Create With User description: Schema for creating a new address associated with a user. allOf: - $ref: '#/components/schemas/AddressBase' - type: object required: - type - relationships properties: relationships: type: object required: - user properties: user: $ref: '#/components/schemas/RelationUser' description: The user to associate with this address. AddressCreateWithCompany: title: Address Create With Company description: Schema for creating a new address associated with a company. allOf: - $ref: '#/components/schemas/AddressBase' - type: object required: - type - relationships properties: relationships: type: object required: - company properties: company: $ref: '#/components/schemas/RelationCompany' description: The company to associate with this address. AddressUpdate: title: Address Update description: Schema for updating an existing address. Relationships cannot be modified during updates. allOf: - $ref: '#/components/schemas/AddressBase' - type: object required: - type - id CompanyBase: x-cacholong-public: true title: Company Base description: Base schema for company with shared properties. type: object properties: type: type: string format: const const: companies id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object properties: name: type: string format: name minLength: 1 maxLength: 255 example: Cacholong description: Company name (must be unique). x-cli-help: Company name (must be unique) kvknr: type: - string - 'null' format: kvknr minLength: 0 maxLength: 255 example: '01121682' x-cli-help: Chamber of Commerce registration number phone: type: - string - 'null' format: phone minLength: 0 maxLength: 255 example: +31 858 77 18 46 description: Phone number from NL, BE, DE, GB or US. x-cli-help: Phone number from NL, BE, DE, GB or US email: type: - string - 'null' minLength: 0 maxLength: 255 example: info@cacholong.nl format: email description: Company email address (validated with DNS check). x-cli-help: Company email address (validated with DNS check) email_invoice: type: - string - 'null' minLength: 0 maxLength: 255 example: invoice@cacholong.nl format: email description: Email for invoicing (defaults to email if not given). x-cli-help: Email for invoicing (defaults to email if not given) vat_number: type: - string - 'null' format: vat_number minLength: 0 maxLength: 255 example: NL123456789B01 description: VAT number (validated if provided). x-cli-help: VAT number (validated if provided) required: - name CompanyShow: x-cacholong-public: true title: Company description: Represents a company. examples: - type: companies id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: name: Cacholong kvknr: '01121682' phone: +31 858 77 18 46 email: info@cacholong.nl email_invoice: invoice@cacholong.nl vat_number: NL123456789B01 created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' links: self: /api/v1/companies/[id] relationships: account: data: type: accounts id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f allOf: - $ref: '#/components/schemas/CompanyBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' readOnly: true relationships: type: object properties: account: $ref: '#/components/schemas/RelationAccount' description: The account this company belongs to. x-cli-help: The account this company belongs to addresses: $ref: '#/components/schemas/RelationAddresses' description: Addresses associated with this company. x-cli-help: Addresses associated with this company required: - account UserBase: title: User Base description: Base schema for user with shared properties. type: object properties: type: type: string format: const const: users id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object properties: phone: type: - string - 'null' format: phone maxLength: 255 example: +31 858 77 18 46 description: Phone number (NL, BE, DE, GB, or US format). x-cli-help: Phone number email: type: string format: email maxLength: 255 example: linus.torvalds@cacholong.nl description: Unique email address for the user. x-cli-help: Unique email address password: type: - string - 'null' format: password minLength: 10 maxLength: 255 description: Password (must contain lowercase, uppercase, number, and symbol). x-cli-help: User password pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^a-zA-Z0-9]).+$/ writeOnly: true password_confirmation: type: - string - 'null' format: password minLength: 10 maxLength: 255 description: Password confirmation (must match password). x-cli-help: Password confirmation writeOnly: true firstname: type: - string - 'null' format: name maxLength: 255 example: Linus description: First name of the user. x-cli-help: First name lastname: type: - string - 'null' format: name maxLength: 255 example: Torvalds description: Last name of the user. x-cli-help: Last name active: type: - boolean - 'null' description: Whether the user account is active. x-cli-help: Whether the user account is active default: true required: - email - password - password_confirmation UserShow: title: User description: Represents a user. examples: - type: users id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: phone: +31 858 77 18 46 email: linus.torvalds@cacholong.nl firstname: Linus lastname: Torvalds active: true invited_at: '2007-09-01T12:00:00.000000Z' invite_accepted_at: 'null' created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' meta: {} links: self: /api/v1/users/[id] allOf: - $ref: '#/components/schemas/UserBase' - type: object properties: attributes: type: object properties: invited_at: type: - string - 'null' format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the user was invited. x-cli-help: Timestamp when the user was invited readOnly: true invite_accepted_at: type: - string - 'null' format: date-time maxLength: 27 example: description: Timestamp when the user accepted the invitation. x-cli-help: Timestamp when the user accepted the invitation readOnly: true created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the user was created. x-cli-help: Timestamp when the user was created readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: Timestamp when the user was last updated. x-cli-help: Timestamp when the user was last updated readOnly: true relationships: type: object properties: addresses: $ref: '#/components/schemas/RelationAddresses' description: The addresses associated with this user. x-cli-help: The addresses associated with this user readOnly: true user-roles: $ref: '#/components/schemas/RelationUserRoles' description: The user-roles that define this user's access to accounts. x-cli-help: The user-roles that define access to accounts CompanyUpdate: title: Company Update description: Schema for updating an existing company. allOf: - $ref: '#/components/schemas/CompanyBase' - type: object properties: relationships: type: object properties: account: $ref: '#/components/schemas/RelationAccount' description: The account this company belongs to (readonly). x-cli-help: The account this company belongs to (readonly) readOnly: true addresses: $ref: '#/components/schemas/RelationAddresses' description: Addresses associated with this company (readonly). x-cli-help: Addresses associated with this company (readonly) readOnly: true required: - type - id DnsRecordShow: x-cacholong-public: true title: Dns record allOf: - $ref: '#/components/schemas/DnsRecordBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' readOnly: true description: Timestamp when the DNS record was created. x-cli-help: When this record was created updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' readOnly: true description: Timestamp when the DNS record was last updated. x-cli-help: When this record was last updated relationships: type: object properties: dns-zone: $ref: '#/components/schemas/RelationDnsZone' description: The DNS zone containing this record. x-cli-help: DNS zone that owns this record dns-template: $ref: '#/components/schemas/RelationDnsTemplate' description: The DNS template containing this record. x-cli-help: DNS template that owns this record examples: - type: dns-records id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: status: success dns_record_type: TXT name: cacholong.nl content: v=spf1 include:_spf.example.com ~all ttl: 300 priority: 'null' spf_flatten: true spf_flattened_content: v=spf1 ip4:192.0.2.1 ip4:192.0.2.2 ~all spf_status: ok spf_last_flattened_at: '2038-01-19T03:14:07.000000Z' spf_last_changed_at: '2038-01-19T03:14:07.000000Z' created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' relationships: dns-zone: data: type: dns-zones id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f meta: sync: false links: self: /api/v1/dns-records/[id] - type: dns-records id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: status: dns_record_type: AAAA name: cacholong.nl content: 2a00:1bd0:197:1::22 ttl: 300 priority: 'null' spf_flatten: false spf_flattened_content: spf_status: spf_last_flattened_at: spf_last_changed_at: created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' relationships: dns-template: data: type: dns-templates id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f links: self: /api/v1/dns-records/[id] DnsTemplateBase: title: Dns Template Base description: Base schema for DNS templates containing shared properties across all operations. type: object properties: type: type: string format: const const: dns-templates id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object properties: name: type: string format: name minLength: 1 maxLength: 255 example: DNS template server description: Template name. x-cli-help: Unique name for this DNS template required: - name relationships: type: object properties: account: $ref: '#/components/schemas/RelationAccount' description: The account that owns this template. x-cli-help: Account that owns this template (or null for global templates) DnsZoneRestorePointBase: title: Dns Zone Restore Point Base description: Base schema for DNS zone restore points containing shared properties across all operations. type: object properties: type: type: string format: const const: dns-zone-restore-points id: type: string format: uuid maxLength: 36 example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object required: - name properties: name: type: string maxLength: 255 description: Human-readable name for this restore point. Required; maximum 255 characters. x-cli-help: Name of the restore point example: Auto-snapshot 2026-05-01 14:30 relationships: type: object properties: dns-zone: $ref: '#/components/schemas/RelationDnsZone' description: The DNS zone this restore point captures. x-cli-help: The DNS zone that this restore point belongs to required: - dns-zone DnsZoneRestorePointShow: x-cacholong-public: true title: Dns zone restore point description: Complete DNS zone restore point resource returned by GET operations with all attributes and relationships. allOf: - $ref: '#/components/schemas/DnsZoneRestorePointBase' - type: object properties: attributes: type: object properties: is_manual: type: boolean description: Indicates whether this restore point was created manually via the API or automatically before a DNS record mutation. x-cli-help: True if manually created via API, false if auto-generated before a DNS record change readOnly: true example: false created_at: type: string format: date-time maxLength: 27 example: '2026-05-01T14:30:00.000000Z' description: Timestamp when the restore point was created. x-cli-help: Creation timestamp in ISO 8601 format readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2026-05-01T14:30:00.000000Z' description: Timestamp when the restore point was last updated. Used to determine the retention period — a rollback refreshes this value. x-cli-help: Last update timestamp in ISO 8601 format (used for retention) readOnly: true relationships: type: object properties: dns-records: $ref: '#/components/schemas/RelationDnsRecords' description: Collection of DNS records captured in this restore point snapshot. x-cli-help: DNS records captured in this restore point readOnly: true examples: - type: dns-zone-restore-points id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 attributes: name: Auto-snapshot 2026-05-01 14:30 is_manual: false created_at: '2026-05-01T14:30:00.000000Z' updated_at: '2026-05-01T14:30:00.000000Z' relationships: dns-zone: data: type: dns-zones id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f links: self: /api/v1/dns-zone-restore-points/3fa85f64-5717-4562-b3fc-2c963f66afa6 DnsZoneBase: title: Dns Zone Base description: Base schema for DNS zones containing shared properties across all operations. type: object properties: type: type: string format: const const: dns-zones id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object properties: domain: type: string format: hostname maxLength: 255 description: The fully qualified domain name (FQDN) for this DNS zone, stored lower-cased. x-cli-help: The domain name for this DNS zone example: cacholong.nl active: type: boolean description: Controls whether the DNS zone is actively serving DNS records. x-cli-help: Enable or disable active DNS resolution for this zone default: false dnssec: type: boolean description: Enable or disable DNSSEC (Domain Name System Security Extensions) for this zone. x-cli-help: Enable DNSSEC cryptographic signing for this zone default: true example: true readOnly: true required: - domain relationships: type: object properties: account: $ref: '#/components/schemas/RelationAccount' description: The account that owns this DNS zone. x-cli-help: The account that owns this DNS zone product: $ref: '#/components/schemas/RelationProduct' description: The product/service associated with this DNS zone. x-cli-help: The product associated with this DNS zone required: - account - product meta: type: object properties: sync: type: - boolean - 'null' description: Controls whether zone operations are processed synchronously or asynchronously. x-cli-help: Process zone operations synchronously (true) or asynchronously (false) default: false RelationServiceBundle: x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: service-bundles id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f DnsZoneShow: x-cacholong-public: true title: Dns zone description: Complete DNS zone resource returned by GET operations with all attributes and relationships. allOf: - $ref: '#/components/schemas/DnsZoneBase' - type: object properties: attributes: type: object properties: status: type: - string enum: - pending - processing - verifying - retrying - failed - success description: Current processing status of the DNS zone. x-cli-help: Processing status (pending, processing, verifying, retrying, failed, success) example: success readOnly: true administratively_disabled: type: boolean description: Whether a superadmin has disabled the zone, which removes its records at the DNS provider but keeps them here; separate from `active`. x-cli-help: Whether a superadmin has disabled the zone (records removed at the DNS provider) default: false readOnly: true dnssec_status: type: - string - 'null' format: status maxLength: 255 description: Current status of DNSSEC for this zone. x-cli-help: DNSSEC status (active, pending, or null if disabled) example: active readOnly: true dnssec_flags: type: - number - 'null' description: DNSSEC key flags field for the DNSKEY record. x-cli-help: DNSSEC key flags (257 for KSK, 256 for ZSK) example: 257 readOnly: true dnssec_algorithm: type: - number - 'null' description: Cryptographic algorithm used for DNSSEC signing. x-cli-help: DNSSEC algorithm (13=ECDSA P-256, 8=RSA/SHA-256, 14=ECDSA P-384) example: 13 readOnly: true dnssec_public_key: type: - string - 'null' format: public-key maxLength: 10000 description: Base64-encoded public key for the DNSSEC Key-Signing Key (KSK). x-cli-help: DNSSEC public key for creating DS records in parent zone example: some-public-key readOnly: true created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the DNS zone was created. x-cli-help: Creation timestamp in ISO 8601 format readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: Timestamp when the DNS zone was last updated. x-cli-help: Last update timestamp in ISO 8601 format readOnly: true relationships: type: object properties: name-server-group: $ref: '#/components/schemas/RelationNameServerGroup' description: Name server group assigned to this DNS zone. x-cli-help: Authoritative nameservers serving this zone's DNS records readOnly: true dns-records: $ref: '#/components/schemas/RelationDnsRecords' description: Collection of all DNS records in this zone. x-cli-help: All DNS records (A, AAAA, CNAME, MX, TXT, etc.) in this zone readOnly: true service-bundle: $ref: '#/components/schemas/RelationServiceBundle' description: The service bundle used to provision this DNS zone. x-cli-help: The service bundle this DNS zone belongs to readOnly: true examples: - type: dns-zones id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: status: pending domain: cacholong.nl active: false administratively_disabled: false dnssec: true dnssec_status: active dnssec_flags: 257 dnssec_algorithm: 13 dnssec_public_key: some-public-key created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' meta: sync: true relationships: product: data: type: products id: a2920888-518b-4e41-9629-d4e5627341cb account: data: type: accounts id: 09a0e355-78e6-46c7-a05b-4bcb8b497275 links: self: /api/v1/dns-zones/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationDnsTemplateNullable: x-cacholong-public: true x-tags: - Internal type: object properties: data: type: - object - 'null' properties: type: type: string format: const const: dns-templates id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 MailAddressBase: title: Mail address base description: Base schema for mail address with shared properties. type: object properties: type: type: string format: const const: mail-addresses id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. attributes: type: object properties: status: type: - string enum: - pending - processing - verifying - retrying - failed - success description: Current processing status of the mail address. x-cli-help: Current processing status of the mail address. example: success readOnly: true name: type: string minLength: 1 maxLength: 255 example: info description: The local part of the email address. x-cli-help: The local part of the email address. pattern: ^[a-zA-Z0-9!#$%&'*+-/=?^_`{|}~]+ password: type: - string - 'null' format: password minLength: 10 maxLength: 255 description: Password for the mail address. x-cli-help: Password for the mail address. pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^a-zA-Z0-9]).+$/ writeOnly: true password_confirmation: type: - string - 'null' format: password minLength: 10 maxLength: 255 description: Password confirmation must match password. x-cli-help: Password confirmation must match password. writeOnly: true enabled: type: - boolean - 'null' description: Is mail address enabled or not? x-cli-help: Is mail address enabled or not? default: true catchall: type: boolean description: Is mail address a catch-all filter? x-cli-help: Is mail address a catch-all filter? default: false readOnly: true allow_sending: type: boolean description: Is mail address allowed to send email? x-cli-help: Is mail address allowed to send email? default: true allow_receiving: type: boolean description: Is mail address allowed to receive email? x-cli-help: Is mail address allowed to receive email? default: true keep_mail_on_forward: type: boolean description: Will mail address receive email when forward exists? x-cli-help: Will mail address receive email when forward exists? default: true required: - name - password - password_confirmation - allow_sending - allow_receiving - keep_mail_on_forward RelationMailDomain: x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: mail-domains id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 RelationMailAddressAliases: x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: mail-address-aliases id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f MailAddressShow: title: Mail address description: Represents a mail address. examples: - type: mail-addresses id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: status: success name: info enabled: true catchall: false allow_sending: true allow_receiving: true keep_mail_on_forward: true created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' links: self: /api/v1/mail-addresses/[id] relationships: mail-domain: data: type: mail-domains id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f allOf: - $ref: '#/components/schemas/MailAddressBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 description: Timestamp when the mail address was created. x-cli-help: Timestamp when the mail address was created. example: '2007-09-01T12:00:00.000000Z' readOnly: true updated_at: type: string format: date-time maxLength: 27 description: Timestamp when the mail address was last updated. x-cli-help: Timestamp when the mail address was last updated. example: '2038-01-19T03:14:07.000000Z' readOnly: true relationships: type: object properties: mail-domain: $ref: '#/components/schemas/RelationMailDomain' description: The mail domain associated with this mail address. x-cli-help: The mail domain associated with this mail address. aliases: $ref: '#/components/schemas/RelationMailAddressAliases' description: Mail address aliases associated with this mail address. x-cli-help: Mail address aliases associated with this mail address. readOnly: true required: - mail-domain MailAddressCreate: title: Mail address create description: Schema for creating a new mail address. allOf: - $ref: '#/components/schemas/MailAddressBase' - type: object properties: relationships: type: object properties: mail-domain: $ref: '#/components/schemas/RelationMailDomain' description: The mail domain to associate with this mail address. x-cli-help: The mail domain to associate with this mail address. required: - mail-domain required: - type MailAddressUpdate: title: Mail address update description: Schema for updating an existing mail address. allOf: - $ref: '#/components/schemas/MailAddressBase' - type: object properties: relationships: type: object properties: mail-domain: $ref: '#/components/schemas/RelationMailDomain' description: The mail domain associated with this mail address. x-cli-help: The mail domain associated with this mail address. readOnly: true aliases: $ref: '#/components/schemas/RelationMailAddressAliases' description: Mail address aliases associated with this mail address. x-cli-help: Mail address aliases associated with this mail address. readOnly: true required: - mail-domain required: - type - id MailDomainBase: title: Mail domain base description: Base properties shared across all mail domain operations. type: object properties: type: type: string format: const const: mail-domains id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object properties: domain: type: string format: hostname maxLength: 255 description: The domain name for this mail domain, stored and returned in lowercase. x-cli-help: The domain name for this mail domain. example: cacholong.nl quota: type: integer format: int32 description: Storage quota for mail domain in MB. x-cli-help: Storage quota for mail domain in MB. minimum: 1024 maximum: 1024000 example: 10240 hidden: type: - boolean - 'null' description: Is mail domain hidden or not? x-cli-help: Is mail domain hidden or not? default: false enabled: type: - boolean - 'null' description: Is mail domain enabled or not? x-cli-help: Is mail domain enabled or not? default: true required: - quota RelationMailAddresses: x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: mail-addresses id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationServiceMail: x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: service-mails id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 MailDomainShow: title: Mail domain description: Represents a mail domain. examples: - type: mail-domains id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: status: success domain: cacholong.nl quota: 10240 hidden: false enabled: true created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' relationships: account: data: type: accounts id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f service-mail: data: type: service-mails id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f links: self: /api/v1/mail-domains/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f allOf: - $ref: '#/components/schemas/MailDomainBase' - type: object properties: attributes: type: object properties: status: type: - string enum: - pending - processing - verifying - retrying - failed - success description: Current processing status of the mail domain. x-cli-help: Current processing status of the mail domain. example: success readOnly: true created_at: type: string format: date-time maxLength: 27 description: Timestamp when the mail domain was created. x-cli-help: Timestamp when the mail domain was created. example: '2007-09-01T12:00:00.000000Z' readOnly: true updated_at: type: string format: date-time maxLength: 27 description: Timestamp when the mail domain was last updated. x-cli-help: Timestamp when the mail domain was last updated. example: '2038-01-19T03:14:07.000000Z' readOnly: true relationships: type: object properties: account: $ref: '#/components/schemas/RelationAccount' description: The account associated with this mail domain. x-cli-help: The account associated with this mail domain. mail-addresses: $ref: '#/components/schemas/RelationMailAddresses' description: Mail addresses associated with this mail domain. x-cli-help: Mail addresses associated with this mail domain. readOnly: true service-mail: $ref: '#/components/schemas/RelationServiceMail' description: The service mail configuration for this mail domain. x-cli-help: The service mail configuration for this mail domain. required: - account - service-mail MailAddressAliasBase: title: Mail address alias base description: Base schema for mail address alias with shared properties. type: object properties: type: type: string format: const const: mail-address-aliases id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. attributes: type: object properties: status: type: - string enum: - pending - processing - verifying - retrying - failed - success description: Current processing status of the mail address alias. x-cli-help: Current processing status of the mail address alias. example: success readOnly: true alias: type: string format: alias minLength: 1 maxLength: 255 example: info description: The local part of the alias email address. x-cli-help: The local part of the alias email address. enabled: type: boolean description: Is mail address alias enabled or not? x-cli-help: Is mail address alias enabled or not? default: true required: - alias - enabled RelationMailAddress: x-tags: - Internal type: object properties: data: type: object properties: type: type: string format: const const: mail-addresses id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 MailAddressAliasShow: title: Mail address alias description: Represents a mail address alias. examples: - type: mail-address-aliases id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: status: success alias: info enabled: true created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' links: self: /api/v1/mail-address-aliases/[id] relationships: mail-address: data: type: mail-addresses id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f allOf: - $ref: '#/components/schemas/MailAddressAliasBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 description: Timestamp when the mail address alias was created. x-cli-help: Timestamp when the mail address alias was created. example: '2007-09-01T12:00:00.000000Z' readOnly: true updated_at: type: string format: date-time maxLength: 27 description: Timestamp when the mail address alias was last updated. x-cli-help: Timestamp when the mail address alias was last updated. example: '2038-01-19T03:14:07.000000Z' readOnly: true relationships: type: object properties: mail-address: $ref: '#/components/schemas/RelationMailAddress' description: The mail address associated with this alias. x-cli-help: The mail address associated with this alias. required: - mail-address MailAddressAliasCreate: title: Mail address alias create description: Schema for creating a new mail address alias. allOf: - $ref: '#/components/schemas/MailAddressAliasBase' - type: object properties: relationships: type: object properties: mail-address: $ref: '#/components/schemas/RelationMailAddress' description: The mail address to associate with this alias. x-cli-help: The mail address to associate with this alias. required: - mail-address required: - type MailAddressAliasUpdate: title: Mail address alias update description: Schema for updating an existing mail address alias. allOf: - $ref: '#/components/schemas/MailAddressAliasBase' - type: object properties: relationships: type: object properties: mail-address: $ref: '#/components/schemas/RelationMailAddress' description: The mail address associated with this alias. x-cli-help: The mail address associated with this alias. readOnly: true required: - mail-address required: - type - id ServiceMailBase: title: Service Mail Base description: Base schema for service mail with shared properties type: object properties: type: type: string format: const const: service-mails id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object properties: name: type: string format: name minLength: 1 maxLength: 255 description: 'Can contain any letter (combined with accent) from any language, any kind of hyphen or dash, numbers 0 to 9, space or the following symbols: ( )' example: Scheduled maintenance description: type: - string - 'null' format: description maxLength: 10000 example: Scheduled maintenance at 2038-01-19. imap_address: type: - string - 'null' format: hostname maxLength: 255 description: Valid host without protocol (a host can also be an ip address). example: imap.cacholong.nl pop_address: type: - string - 'null' format: hostname maxLength: 255 description: Valid host without protocol (a host can also be an ip address). example: pop.cacholong.nl smtp_address: type: - string - 'null' format: hostname maxLength: 255 description: Valid host without protocol (a host can also be an ip address). example: smtp.cacholong.nl webmail_address: type: - string - 'null' format: hostname maxLength: 255 description: Valid host without protocol (a host can also be an ip address). example: webmail.cacholong.nl required: - name RelationProgramInstances: x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: program-instances id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f x-internal: true ServiceMailShow: title: Service Mail description: Represents a service mail examples: - type: service-mails id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: name: Scheduled maintenance description: Scheduled maintenance at 2038-01-19. created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' imap_address: imap.cacholong.nl pop_address: pop.cacholong.nl smtp_address: smtp.cacholong.nl webmail_address: webmail.cacholong.nl links: self: /api/v1/service-mails/[id] relationships: {} allOf: - $ref: '#/components/schemas/ServiceMailBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' readOnly: true MailForwardBase: title: Mail forward (Base) description: Base schema for mail forward resources containing shared properties. type: object properties: type: type: string format: const const: mail-forwards description: The resource type identifier. id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Unique identifier for the mail forward. x-cli-help: Unique identifier for the mail forward. readOnly: true attributes: type: object properties: src_address: type: string example: info@cacholong.nl description: Source email address mail is forwarded from; must end with the mail domain's name, is unique per mail domain and is stored lower-cased. x-cli-help: Source email address mail is forwarded from. format: email maxLength: 255 minLength: 1 dst_address: type: array description: Destination email addresses mail is forwarded to; distinct, outside the forward's own mail domain and stored lower-cased. x-cli-help: Destination email addresses mail is forwarded to. minItems: 1 maxItems: 100 uniqueItems: true items: type: string format: email maxLength: 255 minLength: 1 example: - frontoffice@cacholong.nl - backoffice@cacholong.nl required: - src_address - dst_address meta: type: object properties: src_address_ignore_dns_check: type: - boolean - 'null' example: true description: Skip DNS validation for source address. x-cli-help: Skip DNS validation for source address. dst_address_ignore_dns_check: type: - boolean - 'null' example: true description: Skip DNS validation for destination addresses. x-cli-help: Skip DNS validation for destination addresses. MailForwardShow: title: Mail forward (Show) description: Schema for retrieving mail forward resources. allOf: - $ref: '#/components/schemas/MailForwardBase' - type: object properties: attributes: type: object properties: status: type: string enum: - pending - processing - verifying - retrying - failed - success description: Current processing status of the mail forward. x-cli-help: Current processing status of the mail forward. example: success readOnly: true created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the mail forward was created. x-cli-help: Timestamp when the mail forward was created. readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: Timestamp when the mail forward was last updated. x-cli-help: Timestamp when the mail forward was last updated. readOnly: true relationships: type: object properties: mail-domain: $ref: '#/components/schemas/RelationMailDomain' description: The mail domain associated with this mail forward. x-cli-help: The mail domain associated with this mail forward. required: - mail-domain links: type: object properties: self: type: string format: uri maxLength: 255 example: https://api.example.com/v1/mail-forwards/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Link to this mail forward resource. examples: - type: mail-forwards id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: status: success src_address: info@cacholong.nl dst_address: - frontoffice@cacholong.nl - backoffice@cacholong.nl created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' links: self: /api/v1/mail-forwards/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f relationships: mail-domain: data: type: mail-domains id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f meta: src_address_ignore_dns_check: true dst_address_ignore_dns_check: true MailForwardCreate: title: Mail forward (Create) description: Schema for creating mail forward resources. allOf: - $ref: '#/components/schemas/MailForwardBase' - type: object properties: relationships: type: object properties: mail-domain: $ref: '#/components/schemas/RelationMailDomain' description: The mail domain to associate with this mail forward. x-cli-help: The mail domain to associate with this mail forward. required: - mail-domain required: - type MailForwardUpdate: title: Mail forward (Update) description: Schema for updating mail forward resources. allOf: - $ref: '#/components/schemas/MailForwardBase' - type: object properties: relationships: type: object properties: mail-domain: $ref: '#/components/schemas/RelationMailDomain' description: The mail domain associated with this mail forward. x-cli-help: The mail domain associated with this mail forward. readOnly: true required: - mail-domain required: - type - id ProductBase: title: Product Base description: Base schema for product resource with shared properties. type: object properties: type: type: string format: const const: products id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: type: object properties: name: type: string format: name minLength: 1 maxLength: 255 example: Enterprise VPS description: Product name. x-cli-help: Product name product_type: type: string enum: - domain - hosting - management - ssl - vps - dns - redirect - option example: management description: Type of product; `option` for child products, any other value for top-level products. x-cli-help: Type of product (option for child products, any other value for top-level products) price: type: - number - 'null' minimum: 0 example: 999.99 description: Product price. x-cli-help: Product price default_bill_sequence: type: - string - 'null' maxLength: 5 enum: - 1M - 3M - 1Y - 2Y - 3Y - example: 1M description: Default billing sequence (only for management products). x-cli-help: Default billing sequence (only for management products) invoice_description: type: - string - 'null' format: description maxLength: 255 example: Descripton of the invoice. description: Default description for the invoice item. x-cli-help: Default description for the invoice item options: type: - object - 'null' description: Product options in JSON format. x-cli-help: Product options in JSON format properties: ssl_wildcard: description: Whether SSL certificate is a wildcard certificate. x-cli-help: Whether SSL certificate is a wildcard certificate type: boolean example: true ssl_multidomain: description: Whether SSL certificate is a multidomain certificate. x-cli-help: Whether SSL certificate is a multidomain certificate type: boolean example: false ssl_extended_validated: description: Whether SSL certificate is an extended validated certificate. x-cli-help: Whether SSL certificate is an extended validated certificate type: boolean example: false publish_start: type: - string - 'null' format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Start of the publication window. x-cli-help: Start of the publication window publish_end: type: - string - 'null' format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: End of the publication window. x-cli-help: End of the publication window required: - name - product_type RelationAccountNullable: x-tags: - Internal type: object properties: data: type: - object - 'null' properties: type: type: string format: const const: accounts id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 x-internal: true RelationProductNullable: x-tags: - Internal type: object properties: data: type: - object - 'null' properties: type: type: string format: const const: products id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 x-internal: true RelationProductLocationNullable: x-tags: - Internal type: object properties: data: type: - object - 'null' properties: type: type: string format: const const: product-locations id: type: string example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f format: uuid maxLength: 36 x-internal: true RelationModelContracts: x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: model-contracts id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f RelationEspProducts: x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: esp-products id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f ProductShow: x-cacholong-public: true title: Product description: Represents a product. examples: - type: products id: ef37f61a-93cd-4e73-9fab-2d002062f190 attributes: name: Enterprise VPS product_type: management price: 999.99 default_bill_sequence: 1M invoice_description: Descripton of the invoice. options: ssl_wildcard: true ssl_multidomain: false ssl_extended_validated: false publish_start: '2007-09-01T12:00:00.000000Z' publish_end: '2038-01-19T03:14:07.000000Z' prepaid: false created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' links: self: /api/v1/products/[id] - type: products id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: name: 1 TB extra (NVMe SSD) product_type: option price: 111,11 default_bill_sequence: 1M invoice_description: Descripton of the invoice. publish_start: '2007-09-01T12:00:00.000000Z' publish_end: '2038-01-19T03:14:07.000000Z' prepaid: false created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' links: self: /api/v1/products/[id] relationships: parent: data: type: products id: ef37f61a-93cd-4e73-9fab-2d002062f190 allOf: - $ref: '#/components/schemas/ProductBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' readOnly: true prepaid: type: boolean example: false readOnly: true description: Whether this is a €0 product generated by a purchase for a component that is already paid for, which has no service bundles to choose from. x-cli-help: Whether this is a prepaid product generated by a purchase (no service bundle choice) relationships: type: object properties: account: $ref: '#/components/schemas/RelationAccountNullable' description: The account that owns this product; `null` for a global product. x-cli-help: The account that owns this product (null for a global product) parent: $ref: '#/components/schemas/RelationProductNullable' description: The parent product (if this is a child product). x-cli-help: The parent product (if this is a child product) children: $ref: '#/components/schemas/RelationProducts' description: Child products of this product; only products visible to the user are returned. x-cli-help: Child products of this product readOnly: true service-bundles: $ref: '#/components/schemas/RelationServiceBundles' description: Service bundles offered with this product. x-cli-help: Service bundles offered with this product product-location: $ref: '#/components/schemas/RelationProductLocationNullable' description: The location where this product is delivered. x-cli-help: The location where this product is delivered readOnly: true tlds: $ref: '#/components/schemas/RelationTlds' description: TLDs associated with this product (if product is a domain). x-cli-help: TLDs associated with this product (if product is a domain) model-contracts: $ref: '#/components/schemas/RelationModelContracts' description: Model contracts associated with this product. x-cli-help: Model contracts associated with this product PurchaseBase: title: Purchase Base description: Base schema for purchase resource with shared properties. type: object properties: type: type: string format: const const: purchases id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: type: object properties: description: type: string format: description maxLength: 10000 example: Domain cacholong.nl x-cli-help: Description of the purchase units: type: integer format: int32 minimum: 1 maximum: 500 example: 1 x-cli-help: Number of units purchased date_activation: type: - string - 'null' format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Activation date (stored as UTC). x-cli-help: Activation date (stored as UTC) bill_sequence: type: - string - 'null' format: sequence maxLength: 5 example: 1M description: Billing sequence (e.g. 1M = monthly, 1Y = yearly). x-cli-help: Billing sequence (e.g. 1M = monthly, 1Y = yearly) required: - description - units PurchaseShow: x-cacholong-public: true title: Purchase description: Represents a purchase. examples: - type: purchases id: ef37f61a-93cd-4e73-9fab-2d002062f190 attributes: description: Domain cacholong.nl units: 1 date_purchase: '2007-09-01T12:00:00.000000Z' date_activation: '2007-09-01T12:00:00.000000Z' date_deactivation: '2038-01-19T03:14:07.000000Z' date_next_bill: '2007-10-01T12:00:00.000000Z' bill_sequence: 1M created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' product_type: domain links: self: /api/v1/purchases/[id] relationships: account: data: type: accounts id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f product: data: type: products id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f - type: purchases id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: description: SSL certificate (Sectigo) units: 1 date_purchase: '2007-09-01T12:00:00.000000Z' date_activation: '2007-09-01T12:00:00.000000Z' date_deactivation: '2038-01-19T03:14:07.000000Z' date_next_bill: '2007-10-01T12:00:00.000000Z' bill_sequence: 1M created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' product_type: option links: self: /api/v1/purchases/[id] relationships: account: data: type: accounts id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f product: data: type: products id: d15c5c54-cdc9-4b40-8bd8-4bfac91600d1 parent: data: type: purchases id: ef37f61a-93cd-4e73-9fab-2d002062f19 allOf: - $ref: '#/components/schemas/PurchaseBase' - type: object properties: attributes: type: object properties: product_type: type: string enum: - domain - hosting - management - ssl - vps - dns - redirect - option description: The `product_type` of the purchased product, with the same values as `products.product_type`. x-cli-help: Product type of the purchased product readOnly: true date_purchase: type: string format: date-time maxLength: 27 readOnly: true example: '2007-09-01T12:00:00.000000Z' date_deactivation: type: - string - 'null' format: date-time maxLength: 27 readOnly: true example: '2038-01-19T03:14:07.000000Z' date_next_bill: type: - string - 'null' format: date-time maxLength: 27 readOnly: true example: '2007-10-01T12:00:00.000000Z' created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' readOnly: true relationships: type: object properties: account: $ref: '#/components/schemas/RelationAccount' description: The account this purchase belongs to. x-cli-help: The account this purchase belongs to children: $ref: '#/components/schemas/RelationPurchases' description: Child purchases associated with this purchase. x-cli-help: Child purchases associated with this purchase parent: $ref: '#/components/schemas/RelationPurchase' description: The parent purchase (if this is a child purchase). x-cli-help: The parent purchase (if this is a child purchase) product: $ref: '#/components/schemas/RelationProduct' description: The product being purchased. x-cli-help: The product being purchased required: - account - product ServiceBundleBase: title: Service Bundle Base description: Base schema for service bundle with shared properties type: object properties: type: type: string format: const const: service-bundles id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object properties: name: type: string minLength: 1 maxLength: 255 example: Webcluster (VPS example.com) description: The unique identifier name for this service bundle within the account. Should be descriptive and meaningful for managing multiple bundles, typically indicating the purpose and context (e.g., 'Webcluster (VPS example.com)', 'Production Database Stack', 'Development Environment'). x-cli-help: Service bundle name (must be unique within account) description: type: - string - 'null' maxLength: 65535 description: Optional free-text description providing additional context or notes for this service bundle. x-cli-help: Optional description for this service bundle required: - name RelationServiceGroups: x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: service-groups id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f x-internal: true ServiceBundleShow: x-cacholong-public: true title: Service Bundle description: Represents a service bundle, a named set of services that together deliver a product and so decide on which servers or at which provider it ends up. examples: - type: service-bundles id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: name: Webcluster (VPS example.com) description: Web cluster for the hosting products of example.com. created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' relationships: account: data: type: accounts id: 42d97d0a-536f-3967-9062-92570f4bf57c services: data: - type: services id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f products: data: - type: products id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f links: self: /api/v1/service-bundles/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f allOf: - $ref: '#/components/schemas/ServiceBundleBase' - $ref: '#/components/schemas/JsonApiResourceLinkSelf' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the service bundle was created. x-cli-help: Creation timestamp in ISO 8601 format readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: Timestamp when the service bundle was last updated. x-cli-help: Last update timestamp in ISO 8601 format readOnly: true relationships: type: object properties: account: $ref: '#/components/schemas/RelationAccountNullable' description: The account that owns this service bundle, or null for a global bundle available to every account; cannot be changed after creation. x-cli-help: Account owner (null for a global bundle) services: $ref: '#/components/schemas/RelationServices' description: Services in this bundle, at most one per service category except PHP, which may appear several times. x-cli-help: Services in the bundle products: $ref: '#/components/schemas/RelationProducts' description: Products offered with this bundle. x-cli-help: Products offered with this bundle required: - services ServiceBase: title: Service Base description: Base schema for service with shared properties x-internal: true type: object properties: type: type: string format: const const: services id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Visible on index, show and after post. Required with patch. readOnly: true attributes: type: object properties: category: type: string enum: - apache - cron - dns - domain - firewall - mysql - nginx - osuser - php - postgresql - shell - ssl - vps maxLength: 255 description: The service category that determines the service's function and type. Valid categories include web servers (apache, nginx), databases (mysql, postgresql), scripting languages (php), scheduled tasks (cron), security services (firewall, ssl), DNS services, domain management, operating system users (osuser), shell access, and virtual private servers (vps). x-cli-help: Service category (apache, cron, dns, domain, firewall, mysql, nginx, osuser, php, postgresql, shell, ssl, vps) example: php name: type: string description: The unique identifier name for this service. Should be descriptive and meaningful for managing multiple services of the same category (e.g., different PHP versions or database instances). x-cli-help: Service name (descriptive identifier) minLength: 1 maxLength: 255 example: service_php74 description: type: - string - 'null' maxLength: 255 description: Optional description of the service; null when not set. x-cli-help: Detailed description of the service example: PHP version 7.4 version: type: string minLength: 1 maxLength: 255 description: The version identifier for this service. Format depends on the service category (e.g., '7.4' for PHP, '14.2' for PostgreSQL, '2.4' for Apache). Use semantic versioning where applicable. x-cli-help: Service version number example: '7.4' deprecated_at: type: - string - 'null' format: date-time maxLength: 27 example: '2022-11-28T00:00:00.000000Z' description: The date and time when this service will be deprecated, typically when its security support ends; null if no deprecation is scheduled. x-cli-help: Planned deprecation date in ISO 8601 format (null if not scheduled) required: - category - name - version RelationExternalServiceProviders: x-tags: - Internal type: object properties: data: type: array maxItems: 25 items: type: object properties: type: type: string format: const const: external-service-providers id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f ServiceShow: title: Service description: Represents a service, one building block the platform can deliver (such as PHP 8.3 or nginx) as it runs on specific servers or at a specific provider. x-internal: true examples: - type: services id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: category: php name: service_php74 version: '7.4' description: PHP version 7.4 created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' deprecated_at: '2022-11-28T00:00:00.000000Z' links: self: /api/v1/services/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f relationships: {} - type: services id: 96f991c6-9348-4754-a912-849c896b05c0 attributes: category: nginx name: service_nginx_latest version: 1.25.3 description: Nginx web server latest stable version created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' deprecated_at: links: self: /api/v1/services/96f991c6-9348-4754-a912-849c896b05c0 relationships: {} - type: services id: 3e5c7a2d-9b4f-4e8a-a1c6-8d2f5b9e3a7c attributes: category: mysql name: service_mysql_8 version: 8.0.35 description: MySQL database server version 8.0 created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' deprecated_at: links: self: /api/v1/services/3e5c7a2d-9b4f-4e8a-a1c6-8d2f5b9e3a7c relationships: service-bundles: data: - type: service-bundles id: 5d9c3e7a-2b4f-4a8e-9d1c-6f7b2a8e4c9d allOf: - $ref: '#/components/schemas/ServiceBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the service was created. x-cli-help: Creation timestamp in ISO 8601 format readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: Timestamp when the service was last updated. x-cli-help: Last update timestamp in ISO 8601 format readOnly: true relationships: type: object properties: service-bundles: $ref: '#/components/schemas/RelationServiceBundles' description: Service bundles that include this service; visible to everyone who can view the service. x-cli-help: Service bundles containing this service readOnly: true TldBase: title: Tld description: Represents a top-level domain (TLD). type: object properties: type: type: string format: const const: tlds id: type: string format: uuid maxLength: 36 example: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f description: Unique identifier of the TLD. readOnly: true attributes: type: object properties: name: type: string format: name minLength: 2 maxLength: 63 example: com description: The TLD name without leading dot, e.g. **com** or **nl**. readOnly: true description: type: string format: description minLength: 0 maxLength: 255 example: The .com top-level domain (TLD) is one of the original domains established in 1985. description: Description of the TLD and its purpose. readOnly: true url: type: string format: url minLength: 0 maxLength: 255 example: https://www.example.com description: URL with more information about the TLD. readOnly: true dnssec_algorithms: type: string format: dnssec_algorithms minLength: 0 maxLength: 255 example: '13' description: DNSSEC algorithms supported for this TLD. readOnly: true dnssec_allowed: type: boolean example: true description: Whether DNSSEC is allowed for domains under this TLD. readOnly: true dnssec_digests_allowed: type: boolean example: true description: Whether DNSSEC digests are allowed for domains under this TLD. readOnly: true dnssec_keys_allowed: type: boolean example: true description: Whether DNSSEC keys are allowed for domains under this TLD. readOnly: true restrictions: type: string format: restrictions minLength: 0 maxLength: 255 example: No restrictions description: Restrictions or requirements for registering domains under this TLD. readOnly: true is_auth_code_requested: type: - boolean - 'null' example: true description: Whether the registry requests an auth code for domains under this TLD; `null` while not yet known. readOnly: true is_auth_code_available: type: - boolean - 'null' example: true description: Whether an auth code is available for domains under this TLD; `null` while not yet known. readOnly: true is_auth_code_changeable: type: - boolean - 'null' example: true description: Whether the auth code can be reset, which an authorization code request for a domain under this TLD requires; `null` while not yet known. readOnly: true is_trade_auth_code_required: type: - boolean - 'null' example: false description: Whether an auth code is required to change the owner (trade) of a domain under this TLD; `null` while not yet known. readOnly: true is_transfer_auth_code_required: type: - boolean - 'null' example: true description: Whether an auth code is required to transfer a domain under this TLD; `null` while not yet known. readOnly: true status: type: string format: status minLength: 0 maxLength: 20 example: success description: Status of the TLD; currently always **success**. readOnly: true TldShow: x-cacholong-public: true title: Tld description: Represents a top-level domain (TLD) - Show response examples: - type: tlds id: 16aeda2f-f1e5-4407-b7dd-e2862a9fb85f attributes: name: com description: The .com top-level domain (TLD) is one of the original domains established in 1985. url: https://www.example.com dnssec_algorithms: '13' dnssec_allowed: true dnssec_digests_allowed: true dnssec_keys_allowed: true restrictions: No restrictions is_auth_code_requested: true is_auth_code_available: true is_auth_code_changeable: true is_trade_auth_code_required: false is_transfer_auth_code_required: true status: success created_at: '2007-09-01T12:00:00.000000Z' updated_at: '2038-01-19T03:14:07.000000Z' links: self: /api/v1/tlds/16aeda2f-f1e5-4407-b7dd-e2862a9fb85f allOf: - $ref: '#/components/schemas/TldBase' - type: object properties: attributes: type: object properties: created_at: type: string format: date-time maxLength: 27 example: '2007-09-01T12:00:00.000000Z' description: Timestamp when the TLD was created readOnly: true updated_at: type: string format: date-time maxLength: 27 example: '2038-01-19T03:14:07.000000Z' description: Timestamp when the TLD was last updated readOnly: true securitySchemes: API-token: type: http scheme: bearer description: | Please create an API token using our panel at https://cp.cacholong.eu/#/user/settings/api. You can create an api token within your profile under API. examples: {} parameters: Accept: name: Accept in: header required: true schema: type: string format: const const: application/vnd.api+json description: JSON:API requires use of the JSON:API media type (application/vnd.api+json) for exchanging data. page_number_: name: page[number] in: query required: false schema: type: integer format: int32 example: 1 pattern: ^[1-9][0-9]*$ minimum: 1 maximum: 1000 description: Page number. [How to use page numbers](/#/#pagination). page_size_: name: page[size] in: query required: false schema: type: integer format: int32 pattern: ^[1-9][0-9]*$ example: 15 minimum: 1 maximum: 50 description: Amount of results on a single page. [How to use page size](/#/#pagination). sort: name: sort in: query required: false schema: type: string format: fieldname maxLength: 2097152 example: '-created-at' description: Sort ascending or descending with '-'. [How to use sort](/#/#sorting). fields: name: fields[resource] in: query required: false schema: type: string format: sparse-field maxLength: 2097152 example: fields[resource]=name,description&fields[another-resource]=name description: Sparse fields per-resource type. [How to use fields](/#/#fields). Content-Type: name: Content-Type in: header required: true schema: type: string format: const const: application/vnd.api+json description: JSON:API requires use of the JSON:API media type (application/vnd.api+json) for exchanging data. headers: X-Frame-Options: required: false schema: type: string format: const const: deny description: Prevent clickjacking attacks X-Content-Type-Options: required: false schema: type: string format: const const: nosniff description: Respect the Content-Type header and do not change it. X-XSS-Protection: required: false schema: type: string format: const const: 1; mode=block description: Try to prevent cross site scripting attacks Referrer-Policy: required: false schema: type: string format: const const: no-referrer description: Don't send any referer information. Content-Security-Policy: required: false schema: type: string format: const const: default-src 'none'; report-uri https://api.cacholong.eu/cspreport description: The Content-Security-Policy applied to the API. Access-Control-Allow-Origin: required: false schema: type: string format: const const: https://cp.cacholong.eu description: A security mechanism to allow certain origins. X-RateLimit-Limit: required: false schema: type: integer format: int32 minimum: 0 maximum: 60 description: Max attempts per minute. X-RateLimit-Remaining: required: false schema: type: integer format: int32 minimum: 0 maximum: 60 description: Attempts remaining. Retry-After: required: false schema: type: integer format: int32 minimum: 0 maximum: 60 description: Indicates how many seconds the user agent should wait before making a follow-up request. X-RateLimit-Reset: required: false schema: type: integer format: timestamp minimum: 1737846000 maximum: 4294967295 description: Timestamp indicating when rateLimit will reset. responses: 400-BadRequest: description: Bad request response content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' readOnly: true examples: Sparse field set not allowed: value: jsonapi: version: '1.0' errors: - detail: Sparse field set [resource].[field1], [resource].[field2] are not allowed. source: parameter: /data/parameters/fields status: '400' title: Invalid Query Parameter Sort parameter not allowed: value: jsonapi: version: '1.0' errors: - detail: Sort parameter wrong-parameter is not allowed. source: parameter: /data/parameters/wrong-parameter status: '400' title: Invalid Query Parameter Bad Request: value: jsonapi: version: '1.0' errors: - detail: Contact the administrator. status: '400' title: Bad Request headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 401-Unauthorized: description: Unauthorized response content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' readOnly: true examples: Unauthorized: value: jsonapi: version: '1.0' errors: - detail: Unauthenticated. status: '401' title: Unauthorized headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 403-Forbidden: description: Forbidden response content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' readOnly: true examples: Forbidden: value: jsonapi: version: '1.0' errors: - detail: This action is unauthorized. status: '403' title: Forbidden Not Supported: value: jsonapi: version: '1.0' errors: - detail: Resource type [resource] does not support client-generated IDs. source: pointer: /data/id status: '403' title: Not Supported headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 404-NotFound: description: Not found response content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' readOnly: true examples: Not Found: value: jsonapi: version: '1.0' errors: - status: '404' title: Not Found headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 406-NotAcceptable: description: Not Acceptable content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' examples: Not Acceptable: value: jsonapi: version: '1.0' errors: - detail: This endpoint requires the Accept header to be set to application/vnd.api+json. status: '406' title: Not Acceptable headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 429-TooManyAttempts: description: Too Many Attempts content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' readOnly: true examples: Too Many Attempts: value: jsonapi: version: '1.0' errors: - detail: Too Many Attempts. status: '429' title: Too Many Requests headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 500-InternalServerError: description: Internal Server Error response content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' readOnly: true examples: Internal Server Error: value: jsonapi: version: '1.0' errors: - detail: Internal Server Error status: '500' title: Internal Server Error headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 503-ServiceUnavailable: description: Service Unavailable response. The server is temporarily unavailable for maintenance. content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' readOnly: true examples: Service Unavailable: value: jsonapi: version: '1.0' errors: - detail: The server is temporarily unavailable for maintenance. Please try again later. status: '503' title: Service Unavailable headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 409-Conflict: description: Conflict response content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' examples: Resource type not supported: value: jsonapi: version: '1.0' errors: - detail: Resource type [resource] is not supported by this endpoint. source: pointer: /data/type status: '409' title: Not Supported Resource id not supported: value: jsonapi: version: '1.0' errors: - detail: Resource id [id] is not supported by this endpoint. source: pointer: /data/id status: '409' title: Not Supported headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 415-UnsupportedMediaType: description: Not Supported content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' examples: Unsupported Media Type: value: jsonapi: version: '1.0' errors: - detail: The request entity has a media type which the server or resource does not support. status: '415' title: Unsupported Media Type headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 422-UnprocessableEntity: description: Unprocessable entity response content: application/vnd.api+json: schema: allOf: - $ref: '#/components/schemas/JsonApiImplementation' - type: object readOnly: true properties: errors: type: array maxItems: 25 items: $ref: '#/components/schemas/Error' readOnly: true examples: Unprocessable Entity: value: jsonapi: version: '1.0' errors: - detail: The [attribute] field is required. source: pointer: /data/attributes/[attribute] status: '422' title: Unprocessable Entity Unprocessable Entity without source: value: jsonapi: version: '1.0' errors: - detail: Invalid Token status: '422' title: Unprocessable Entity headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 204-NoContent: description: No content response headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' 202-NoContent: description: No content response (Accepted) headers: X-Frame-Options: $ref: '#/components/headers/X-Frame-Options' X-Content-Type-Options: $ref: '#/components/headers/X-Content-Type-Options' X-XSS-Protection: $ref: '#/components/headers/X-XSS-Protection' Referrer-Policy: $ref: '#/components/headers/Referrer-Policy' Content-Security-Policy: $ref: '#/components/headers/Content-Security-Policy' Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset'