API, SDKs & AI assistants

API reference

Billing

API endpoint reference

Find each public endpoint's parameters, required permissions and responses.

OpenAPI 3.1.0

Version v1

BlazingFast Customer API

Automate account billing, VPS and dedicated servers, DNS and Website Protection, TCP Proxy, domains, SSH keys, firewall policies and storage. Use an official SDK for HMAC-signed requests, or a bearer-mode API key. Generic OpenAPI-generated clients do not implement BlazingFast HMAC signing automatically. Pagination is endpoint-specific: follow the documented page/limit, cursor/next_cursor or offset/next_offset model. limit is the canonical page-size parameter; page_size and pageSize are deprecated compatibility aliases only where documented. Begin by reading the resource, confirm changes, and inspect the result or returned task. Draft order creation does not charge the account. Atomic deployment is the documented exception: order + full final order amount paid from account balance + queued provisioning. Payment is not successful provisioning; accepted is not completed. Access depends on key scopes and account permissions.

Base URL: https://api.blazingfast.io

Download schema Endpoint examples Integration guide and SDK workflows Error codes API workflow Pagination

Category summary

Billing

11 endpoints

Browse products and valid order options, check prices, create unpaid orders, and view invoices, transactions and account balance. Paying an invoice from balance is a separate action.

Authentication

apiKey

SignedAuth

SignedAuth is represented by x-api-key for discovery only. Generic OpenAPI-generated clients do not automatically implement BlazingFast HMAC signing. Use BearerAuth with a bearer-mode credential or an official SDK, unless you implement the signing algorithm manually. Signed-key mode requires all five headers. SDKs send x-api-key, x-ts (Unix seconds), x-nonce, x-content-sha256 (Base64 SHA-256 of the exact body), and x-signature (Base64 HMAC-SHA256). Custom signing is explained in the API authentication guide. Every HTTP attempt needs a fresh timestamp and nonce; an action retry retains its original idempotency key and payload. Key expiry, IP restrictions, account permissions and scopes still apply.

http

bearer

api-key-secret

BearerAuth

Alternative mode for integrations that prefer Authorization: Bearer <prefix.secret>. Key status, expiry, scope checks, IP policy, and rate limits still apply.

Endpoints

POST

/v1/billing/invoices/{id}/pay

Pay invoice from wallet

Operation ID: payInvoice

Attempts to settle the target invoice using account balance. This is the customer API path for balance-driven payment automation.

SignedAuth (billing.invoice.pay)

BearerAuth (billing.invoice.pay)

Parameter	Location	Type	Required	Description
id	path	string	Yes	Invoice UUID.
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

No request body

Responses

200

application/json

Invoice payment result.

default

application/json

Canonical nested error envelope: use error.code, error.message, error.request_id and error.field_errors. Deprecated flat fields may be included for legacy clients. Generic server failures use service_unavailable without internal details. An interrupted connection may leave a write outcome unknown.

Request example

bash

curl --disable -sS --globoff --max-time 30 -X POST "https://api.blazingfast.io/v1/billing/invoices/${BF_PATH_ID}/pay" -H "Authorization: Bearer $BF_API_BEARER" -H "Idempotency-Key: $BF_REQUEST_KEY"

Setup and request inputs

Create a bearer-mode key in Settings → API with the scopes shown above. Set BF_API_BEARER privately to its full prefix.secret value. These are request snippets, not complete applications. This page does not send requests.

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

BF_PATH_ID — path parameter id (required). Invoice UUID.

BF_HEADER_X_CLIENT_REQUEST_ID — header parameter x-client-request-id (optional). Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.

BF_REQUEST_KEY — header parameter Idempotency-Key (required). Reuse the same key and payload for retries of one intended operation.

Review the target and payload before running. For a payment, check the invoice and outstanding amount first. Reuse BF_REQUEST_KEY for retries of the same operation; check status after an interrupted request.

Check the HTTP status and handle errors in your application. Examples validate TLS, have a 30-second request limit, and never automatically retry or follow redirects. Run cURL on a private workstation: expanded tokens appear in process arguments, so disable shell tracing and command logging. Do not log passwords or share credential responses.

Example response · HTTP 200

json

{
  "ok": true,
  "paidNow": "100",
  "partial": false,
  "fullyPaid": true,
  "invoiceId": "00000000-0000-4000-8000-000000000001",
  "orderId": null,
  "status": "paid",
  "meta": {
    "createdServices": 0,
    "renewedServices": 1,
    "createdServiceIds": [],
    "provisioning": null
  }
}

Illustrative values, not a live result.

POST

/v1/billing/orders/draft

Start draft order

Operation ID: billingOrderDraft

Creates a draft order from one or more items so you can continue into invoice creation and payment.

SignedAuth (billing.order.create)

BearerAuth (billing.order.create)

Parameter	Location	Type	Required	Description
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

Required

application/json

application/json schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD",
        "EUR",
        "UAH",
        "GBP",
        "PLN",
        "BRL",
        "INR",
        "IDR",
        "CNY"
      ]
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string",
            "format": "uuid"
          },
          "variant_id": {
            "type": "string",
            "format": "uuid"
          },
          "qty": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "user_config": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "array",
                "items": {
                  "description": "JSON value; product-specific fields are discovered through order-options."
                }
              },
              {
                "type": "object",
                "additionalProperties": {
                  "description": "JSON value; product-specific fields are discovered through order-options."
                }
              }
            ]
          },
          "attributes": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              },
              {
                "type": "array",
                "items": {
                  "description": "JSON value; product-specific fields are discovered through order-options."
                }
              },
              {
                "type": "object",
                "additionalProperties": {
                  "description": "JSON value; product-specific fields are discovered through order-options."
                }
              }
            ]
          },
          "billing": {
            "type": "object",
            "properties": {
              "unit": {
                "type": "string",
                "enum": [
                  "ONCE",
                  "HOUR",
                  "DAY",
                  "WEEK",
                  "MONTH",
                  "QUARTAL",
                  "SEMIANNUAL",
                  "YEAR"
                ]
              },
              "count": {
                "type": "integer",
                "minimum": 1,
                "maximum": 120
              }
            },
            "required": [
              "unit",
              "count"
            ],
            "additionalProperties": false
          },
          "addons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120,
                  "pattern": "^[A-Za-z0-9_.:-]+$"
                },
                "qty": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 100
                }
              },
              "required": [
                "key",
                "qty"
              ],
              "additionalProperties": false
            },
            "maxItems": 50
          }
        },
        "required": [
          "product_id",
          "variant_id",
          "qty",
          "billing"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 50
    }
  },
  "required": [
    "currency",
    "items"
  ],
  "additionalProperties": false,
  "example": {
    "currency": "EUR",
    "items": [
      {
        "product_id": "00000000-0000-4000-8000-000000000001",
        "variant_id": "00000000-0000-4000-8000-000000000002",
        "qty": 1,
        "billing": {
          "unit": "MONTH",
          "count": 1
        },
        "user_config": {
          "hostname": "example",
          "location": "NL",
          "os": {
            "code": "debian-13"
          }
        },
        "addons": []
      }
    ]
  },
  "description": "Illustrative VPS cart. Replace IDs, required user_config fields, billing period and add-ons with the selected public plan’s order-options. The server validates ownership, eligibility and prices; caller-supplied hardware/price cannot change the plan. Quotes require complete billing details and use account currency."
}

Responses

200

application/json

Created draft order and related billing payload.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X POST "https://api.blazingfast.io/v1/billing/orders/draft" -H "Authorization: Bearer $BF_API_BEARER" -H "Idempotency-Key: $BF_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"currency":"EUR","items":[{"product_id":"00000000-0000-4000-8000-000000000001","variant_id":"00000000-0000-4000-8000-000000000002","qty":1,"billing":{"unit":"MONTH","count":1},"user_config":{"hostname":"example","location":"NL","os":{"code":"debian-13"}},"addons":[]}]}'

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

BF_REQUEST_KEY — header parameter Idempotency-Key (required). Reuse the same key and payload for retries of one intended operation.

Replace example body values with your configuration. Discover compatible profile IDs and account-owned key IDs before use.

Example response · HTTP 200

json

{
  "ok": true,
  "orderId": "00000000-0000-4000-8000-000000000001",
  "invoiceId": "00000000-0000-4000-8000-000000000002",
  "invoiceNumber": "INV-EXAMPLE-000001",
  "total": "100.00",
  "currency": "EUR",
  "status": "unpaid"
}

Illustrative values, not a live result.

POST

/v1/billing/orders/preview

Preview order total

Operation ID: billingOrderPreview

Submit the same complete cart as order creation, including userConfig and public add-on key/qty selections. Uses checkout validation and pricing, equivalent billing periods, account currency and tax. Requires complete billing details. Returns reserved=false: no reservation, order, invoice or payment is created. A quote does not guarantee later stock or prices. The older single-item preview body is accepted and normalized to the same cart.

SignedAuth (billing.products.read)

BearerAuth (billing.products.read)

Parameter	Location	Type	Required	Description
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

Required

application/json

application/json schema

{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "idempotency_key": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "currency": {
          "type": "string",
          "enum": [
            "USD",
            "EUR",
            "UAH",
            "GBP",
            "PLN",
            "BRL",
            "INR",
            "IDR",
            "CNY"
          ]
        },
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "product_id": {
                "type": "string",
                "format": "uuid"
              },
              "variant_id": {
                "type": "string",
                "format": "uuid"
              },
              "qty": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              },
              "user_config": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "null"
                  },
                  {
                    "type": "array",
                    "items": {
                      "description": "JSON value; product-specific fields are discovered through order-options."
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": {
                      "description": "JSON value; product-specific fields are discovered through order-options."
                    }
                  }
                ]
              },
              "attributes": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "null"
                  },
                  {
                    "type": "array",
                    "items": {
                      "description": "JSON value; product-specific fields are discovered through order-options."
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": {
                      "description": "JSON value; product-specific fields are discovered through order-options."
                    }
                  }
                ]
              },
              "billing": {
                "type": "object",
                "properties": {
                  "unit": {
                    "type": "string",
                    "enum": [
                      "ONCE",
                      "HOUR",
                      "DAY",
                      "WEEK",
                      "MONTH",
                      "QUARTAL",
                      "SEMIANNUAL",
                      "YEAR"
                    ]
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 120
                  }
                },
                "required": [
                  "unit",
                  "count"
                ],
                "additionalProperties": false
              },
              "addons": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 120,
                      "pattern": "^[A-Za-z0-9_.:-]+$"
                    },
                    "qty": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "key",
                    "qty"
                  ],
                  "additionalProperties": false
                },
                "maxItems": 50
              }
            },
            "required": [
              "product_id",
              "variant_id",
              "qty",
              "billing"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "maxItems": 50
        }
      },
      "required": [
        "currency",
        "items"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "product_id": {
          "type": "string",
          "format": "uuid"
        },
        "variant_id": {
          "type": "string",
          "format": "uuid"
        },
        "currency": {
          "type": "string",
          "maxLength": 3,
          "minLength": 3
        },
        "unit": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20
        },
        "count": {
          "type": "integer",
          "minimum": 1,
          "maximum": 120
        },
        "quantity": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 1
        },
        "user_config": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            },
            {
              "type": "array",
              "items": {
                "description": "JSON value; product-specific fields are discovered through order-options."
              }
            },
            {
              "type": "object",
              "additionalProperties": {
                "description": "JSON value; product-specific fields are discovered through order-options."
              }
            }
          ]
        },
        "addons": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[A-Za-z0-9_.:-]+$"
              },
              "qty": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              }
            },
            "required": [
              "key",
              "qty"
            ],
            "additionalProperties": false
          },
          "maxItems": 50
        }
      },
      "required": [
        "product_id",
        "variant_id",
        "currency",
        "unit",
        "count"
      ],
      "additionalProperties": false
    }
  ],
  "example": {
    "currency": "EUR",
    "items": [
      {
        "product_id": "00000000-0000-4000-8000-000000000001",
        "variant_id": "00000000-0000-4000-8000-000000000002",
        "qty": 1,
        "billing": {
          "unit": "MONTH",
          "count": 1
        },
        "user_config": {
          "hostname": "example",
          "location": "NL",
          "os": {
            "code": "debian-13"
          }
        },
        "addons": []
      }
    ]
  },
  "description": "Illustrative VPS cart. Replace IDs, required user_config fields, billing period and add-ons with the selected public plan’s order-options. The server validates ownership, eligibility and prices; caller-supplied hardware/price cannot change the plan. Quotes require complete billing details and use account currency."
}

Responses

200

application/json

Order preview with calculated totals.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X POST "https://api.blazingfast.io/v1/billing/orders/preview" -H "Authorization: Bearer $BF_API_BEARER" -H 'Content-Type: application/json' --data '{"currency":"EUR","items":[{"product_id":"00000000-0000-4000-8000-000000000001","variant_id":"00000000-0000-4000-8000-000000000002","qty":1,"billing":{"unit":"MONTH","count":1},"user_config":{"hostname":"example","location":"NL","os":{"code":"debian-13"}},"addons":[]}]}'

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

Replace example body values with your configuration. Discover compatible profile IDs and account-owned key IDs before use.

Example response · HTTP 200

json

{
  "ok": true,
  "currency": "EUR",
  "subtotal": "100.00",
  "tax": "0.00",
  "total": "100.00",
  "reserved": false,
  "breakdown": {
    "base_price": "100.00",
    "addons": "0.00",
    "setup_fee": "0.00",
    "tax": "0.00",
    "total": "100.00"
  },
  "items": [
    {
      "productId": "00000000-0000-4000-8000-000000000001",
      "variantId": "00000000-0000-4000-8000-000000000002",
      "productName": "Example VPS",
      "sku": "4G",
      "quantity": 1,
      "billing": {
        "unit": "MONTH",
        "count": 1
      },
      "unitPrice": "100",
      "setupFee": "0",
      "subtotal": "100",
      "addons": []
    }
  ]
}

Illustrative values, not a live result.

GET

/v1/billing/balance

Check wallet balance

Operation ID: billingBalance

Returns current account credit and currency so billing dashboards or automation can decide whether balance payment is available.

SignedAuth (billing.balance.read)

BearerAuth (billing.balance.read)

Parameter	Location	Type	Required	Description
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

No request body

Responses

200

application/json

Current balance details.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X GET "https://api.blazingfast.io/v1/billing/balance" -H "Authorization: Bearer $BF_API_BEARER"

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

Example response · HTTP 200

json

{
  "ok": true,
  "exists": true,
  "currency": "EUR",
  "credit": "100",
  "vcredit": "0"
}

Illustrative values, not a live result.

GET

/v1/billing/invoices

Browse invoices

Operation ID: listInvoices

Returns paginated customer invoices. Use this to build invoice history views, overdue checks, or reconciliation jobs.

SignedAuth (billing.invoices.read)

BearerAuth (billing.invoices.read)

Parameter	Location	Type	Required	Description
page	query	integer	No	Page number for pagination.
limit	query	integer	No	Maximum items to return (default 50; range 1–100). Canonical page-size parameter. Deprecated page_size and pageSize aliases remain accepted; supplied size values must match.
page_size Deprecated	query	integer	No	Deprecated compatibility alias for limit; values must match when supplied together.
pageSize Deprecated	query	integer	No	Deprecated compatibility alias for limit; range 1–100, default 50.
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

No request body

Responses

200

application/json

Paginated invoice list.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X GET "https://api.blazingfast.io/v1/billing/invoices" -H "Authorization: Bearer $BF_API_BEARER"

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

BF_QUERY_PAGE — query parameter page (optional). Page number for pagination. Supply the unencoded value; only required query parameters are included in the snippet.

BF_QUERY_LIMIT — query parameter limit (optional). Maximum items to return (default 50; range 1–100). Canonical page-size parameter. Deprecated page_size and pageSize aliases remain accepted; supplied size values must match. Supply the unencoded value; only required query parameters are included in the snippet.

Example response · HTTP 200

json

{
  "ok": true,
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "pages": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "number": "INV-EXAMPLE-000001",
      "status": "unpaid",
      "total": "100.00",
      "paidTotal": "0.00",
      "currency": "EUR",
      "type": "purchase",
      "refundedTotal": "0.00",
      "createdAt": "2026-10-01T00:00:00.000Z",
      "dueDate": "2026-11-01T00:00:00.000Z",
      "payDate": null,
      "order": null
    }
  ]
}

Illustrative values, not a live result.

GET

/v1/billing/invoices/unpaid-total

Check unpaid total

Operation ID: billingUnpaidTotal

Returns the current unpaid amount across customer invoices. This is useful for dashboard badges and automation that should pause when debt exists.

SignedAuth (billing.unpaid_total.read)

BearerAuth (billing.unpaid_total.read)

Parameter	Location	Type	Required	Description
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

No request body

Responses

200

application/json

Current unpaid invoice summary.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X GET "https://api.blazingfast.io/v1/billing/invoices/unpaid-total" -H "Authorization: Bearer $BF_API_BEARER"

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

Example response · HTTP 200

json

{
  "ok": true,
  "data": {
    "unpaidTotal": 0,
    "currency": "EUR"
  }
}

Illustrative values, not a live result.

GET

/v1/billing/orders

Browse orders

Operation ID: billingOrders

Returns paginated customer orders and supports filtering by order or payment status for reporting and customer portals.

SignedAuth (billing.orders.read)

BearerAuth (billing.orders.read)

Parameter	Location	Type	Required	Description
page	query	integer	No	Page number for pagination.
limit	query	integer	No	Maximum items to return (default 50; range 1–100). Canonical page-size parameter. Deprecated page_size and pageSize aliases remain accepted; supplied size values must match.
page_size Deprecated	query	integer	No	Deprecated compatibility alias for limit; values must match when supplied together.
pageSize Deprecated	query	integer	No	Deprecated compatibility alias for limit; range 1–100, default 50.
status	query	string	No	Optional order status filter.
paymentStatus	query	string	No	Optional payment status filter.
external_id	query	string	No	Exact customer reference on an owned order item; applied before pagination.
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

No request body

Responses

200

application/json

Paginated order list.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X GET "https://api.blazingfast.io/v1/billing/orders" -H "Authorization: Bearer $BF_API_BEARER"

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

BF_QUERY_PAGE — query parameter page (optional). Page number for pagination. Supply the unencoded value; only required query parameters are included in the snippet.

BF_QUERY_STATUS — query parameter status (optional). Optional order status filter. Supply the unencoded value; only required query parameters are included in the snippet.

BF_QUERY_PAYMENT_STATUS — query parameter paymentStatus (optional). Optional payment status filter. Supply the unencoded value; only required query parameters are included in the snippet.

BF_QUERY_EXTERNAL_ID — query parameter external_id (optional). Exact customer reference on an owned order item; applied before pagination. Supply the unencoded value; only required query parameters are included in the snippet.

Example response · HTTP 200

json

{
  "ok": true,
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "pages": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "status": "pending",
      "currency": "EUR",
      "total": "100.00",
      "paymentStatus": "unpaid",
      "paymentMethod": null,
      "createdAt": "2026-10-01T00:00:00.000Z",
      "invoice": {
        "id": "00000000-0000-4000-8000-000000000001",
        "number": "INV-EXAMPLE-000001",
        "status": "unpaid",
        "total": "100.00",
        "paidTotal": "0.00",
        "currency": "EUR"
      }
    }
  ]
}

Illustrative values, not a live result.

GET

/v1/billing/products

Browse product catalog

Operation ID: billingProducts

Returns product catalog entries that can be used for storefront search, quoting, and pre-checkout selection flows.

SignedAuth (billing.products.read)

BearerAuth (billing.products.read)

Parameter	Location	Type	Required	Description
page	query	integer	No	Page number for pagination.
limit	query	integer	No	Maximum items to return (default 50; range 1–100). Canonical page-size parameter. Deprecated page_size and pageSize aliases remain accepted; supplied size values must match.
page_size Deprecated	query	integer	No	Deprecated compatibility alias for limit; values must match when supplied together.
pageSize Deprecated	query	integer	No	Deprecated compatibility alias for limit; range 1–100, default 50.
category	query	string	No	Optional category filter.
q	query	string	No	Optional free-text search query.
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

No request body

Responses

200

application/json

Paginated product list.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X GET "https://api.blazingfast.io/v1/billing/products" -H "Authorization: Bearer $BF_API_BEARER"

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

BF_QUERY_PAGE — query parameter page (optional). Page number for pagination. Supply the unencoded value; only required query parameters are included in the snippet.

BF_QUERY_CATEGORY — query parameter category (optional). Optional category filter. Supply the unencoded value; only required query parameters are included in the snippet.

BF_QUERY_Q — query parameter q (optional). Optional free-text search query. Supply the unencoded value; only required query parameters are included in the snippet.

Example response · HTTP 200

json

{
  "ok": true,
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "pages": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "name": "Example VPS",
      "category": "vps",
      "variants": [
        {
          "id": "00000000-0000-4000-8000-000000000002",
          "productId": "00000000-0000-4000-8000-000000000001",
          "sku": "4G",
          "serviceType": "vps",
          "attributes": {
            "compute": {
              "CPU": 2,
              "RAM": 4
            },
            "storage": {
              "DISK_SPACE": 40
            }
          },
          "addons": [],
          "billingOptions": [
            {
              "unit": "MONTH",
              "count": 1,
              "currency": "EUR",
              "price": "100.00",
              "setupFee": "0.00"
            }
          ]
        }
      ]
    }
  ]
}

Illustrative values, not a live result.

GET

/v1/billing/products/{productId}/variants/{variantId}/order-options

Discover product order options

Operation ID: billingProductOrderOptions

Read-only complete configuration discovery for a public, active product and variant. Returns required and optional fields, conditional requirements, priced add-ons, billing options and eligible OS/regions. VPS uses userConfig.location and userConfig.os.code. Managed dedicated uses userConfig.dedicated.configurationCode, regionCode, osProfileId and hostname; optional sshKeyId must belong to your account. Includes physical/default connectivity, purchasable bandwidth add-ons, IPv4 limits and reservation TTL. supported=false means dashboard-only. No capacity is reserved; compatible catalog stock is not a reservation. Domain pricingMode=domain_quote requires a domain-specific quote. No infrastructure secrets are returned.

SignedAuth (billing.products.read)

BearerAuth (billing.products.read)

Parameter	Location	Type	Required	Description
productId	path	string	Yes	Product UUID from the catalog.
variantId	path	string	Yes	Variant UUID belonging to this product.
region	query	string	No	Region code from GET /v1/regions, for example nl or pt. Case-insensitive.
currency	query	string	No	Pricing currency, default EUR.
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

No request body

Responses

200

application/json

Product-specific location and OS options. A catalog outage returns an error, never fallback options.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X GET "https://api.blazingfast.io/v1/billing/products/${BF_PATH_PRODUCT_ID}/variants/${BF_PATH_VARIANT_ID}/order-options" -H "Authorization: Bearer $BF_API_BEARER"

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

BF_PATH_PRODUCT_ID — path parameter productId (required). Product UUID from the catalog.

BF_PATH_VARIANT_ID — path parameter variantId (required). Variant UUID belonging to this product.

BF_QUERY_REGION — query parameter region (optional). Region code from GET /v1/regions, for example nl or pt. Case-insensitive. Supply the unencoded value; only required query parameters are included in the snippet.

BF_QUERY_CURRENCY — query parameter currency (optional). Pricing currency, default EUR. Supply the unencoded value; only required query parameters are included in the snippet.

Example response · HTTP 200

json

{
  "ok": true,
  "productId": "00000000-0000-4000-8000-000000000001",
  "variantId": "00000000-0000-4000-8000-000000000002",
  "supported": true,
  "capacityVerified": false,
  "requiredFields": [
    {
      "field": "hostname",
      "label": "Hostname",
      "description": "Server hostname.",
      "format": "hostname"
    },
    {
      "field": "location",
      "label": "Location",
      "description": "Location code."
    },
    {
      "field": "os.code",
      "label": "Operating system",
      "description": "Operating system code."
    }
  ],
  "locations": [
    {
      "code": "NL",
      "name": "Netherlands",
      "operatingSystems": [
        {
          "code": "debian-13",
          "name": "Debian",
          "family": "debian",
          "version": "13",
          "arch": "amd64",
          "isDefault": true
        }
      ]
    }
  ]
}

Illustrative values, not a live result.

GET

/v1/billing/services

Browse billable services

Operation ID: billingServices

Returns the billing-facing service list. Use this endpoint when the main goal is commercial visibility rather than grouped customer dashboards.

SignedAuth (billing.services.read)

BearerAuth (billing.services.read)

Parameter	Location	Type	Required	Description
page	query	integer	No	Page number for pagination.
limit	query	integer	No	Maximum items to return (default 50; range 1–100). Canonical page-size parameter. Deprecated page_size and pageSize aliases remain accepted; supplied size values must match.
page_size Deprecated	query	integer	No	Deprecated compatibility alias for limit; values must match when supplied together.
pageSize Deprecated	query	integer	No	Deprecated compatibility alias for limit; range 1–100, default 50.
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

No request body

Responses

200

application/json

Paginated billing service list.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X GET "https://api.blazingfast.io/v1/billing/services" -H "Authorization: Bearer $BF_API_BEARER"

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

BF_QUERY_PAGE — query parameter page (optional). Page number for pagination. Supply the unencoded value; only required query parameters are included in the snippet.

Example response · HTTP 200

json

{
  "ok": true,
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "pages": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "status": "active",
      "displayName": "Example VPS",
      "hostname": "server.example.com",
      "type": "vps",
      "createdAt": "2026-10-01T00:00:00.000Z",
      "dueDate": "2026-11-01T00:00:00.000Z",
      "billingUnit": "MONTH",
      "billingCount": 1,
      "sku": "4G",
      "ipv4": "192.0.2.10",
      "ipv6": null,
      "meta": {
        "serviceType": "vps"
      }
    }
  ]
}

Illustrative values, not a live result.

GET

/v1/billing/transactions

Browse transactions

Operation ID: billingTransactions

Returns paginated financial transaction records for account history and payment auditing.

SignedAuth (billing.transactions.read)

BearerAuth (billing.transactions.read)

Parameter	Location	Type	Required	Description
page	query	integer	No	Page number for pagination.
limit	query	integer	No	Maximum items to return (default 50; range 1–100). Canonical page-size parameter. Deprecated page_size and pageSize aliases remain accepted; supplied size values must match.
page_size Deprecated	query	integer	No	Deprecated compatibility alias for limit; values must match when supplied together.
pageSize Deprecated	query	integer	No	Deprecated compatibility alias for limit; range 1–100, default 50.
x-client-request-id	header	string	No	Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.
x-ts	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Unix timestamp in seconds; refresh it for every HTTP attempt. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-nonce	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Fresh nonce for every HTTP attempt; never reuse it when retrying. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-content-sha256	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 SHA-256 of the exact transmitted body bytes; hash the empty body for bodyless requests. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.
x-signature	header	string	For SignedAuth	Required when using SignedAuth with x-api-key; omitted for BearerAuth. Base64 HMAC-SHA256 signature produced by the documented signing algorithm. Generic OpenAPI clients do not compute HMAC signatures; use an official SDK or implement signing manually.

Request body

No request body

Responses

200

application/json

Paginated transaction list.

default

application/json

Request example

bash

curl --disable -sS --globoff --max-time 30 -X GET "https://api.blazingfast.io/v1/billing/transactions" -H "Authorization: Bearer $BF_API_BEARER"

Setup and request inputs

Bash · cURL 7.87+. Supply URL-encoded path values; query values are encoded by cURL.

BF_QUERY_PAGE — query parameter page (optional). Page number for pagination. Supply the unencoded value; only required query parameters are included in the snippet.

Example response · HTTP 200

json

{
  "ok": true,
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "pages": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "createdAt": "2026-10-01T00:00:00.000Z",
      "status": "completed",
      "type": "payment",
      "currency": "EUR",
      "amountIn": "100.00",
      "amountOut": "0.00",
      "fee": "0.00",
      "gateway": null,
      "invoiceId": "00000000-0000-4000-8000-000000000002",
      "meta": null
    }
  ]
}

Illustrative values, not a live result.

Errors and safe retries

Use HTTP status and error.code for decisions. The canonical envelope contains error.message, error.request_id and error.field_errors. Flat code, message, request_id, field_errors, details and status fields are legacy compatibility fields and may still appear; new integrations should read the nested error.

json

{
  "ok": false,
  "error": {
    "code": "scope_denied",
    "message": "Required scope is missing",
    "request_id": "00000000-0000-4000-8000-000000000001",
    "field_errors": []
  }
}

Error code reference

HTTP	Code	Meaning	What to do
409	`service_not_renewable`	The service lifecycle or billing mode does not allow fixed-cycle renewal.	Only active/suspended recurring services support renew-and-pay. One-time and wallet-metered services use their own billing flow.
409	`renewal_invoice_requires_review`	The open invoice is not a same-cycle, single-service renewal.	Review the invoice separately. Do not automatically pay an upgrade, purchase, changed-cycle or mixed-service invoice as renewal.
409	`renewal_price_limit_exceeded`	The outstanding renewal amount exceeds max_total.	No debit or new invoice was committed. Review the amount before raising the ceiling.
409	`service_changed_retry`	The service changed while its renewal was being prepared.	Reload service/invoice details and retry the same renewal key and body. Do not replace the key after an ambiguous outcome.
400	`unsupported_region`	This discovery region is not supported.	Select a region returned by /v1/regions. Use the same region for product, configuration and image discovery.
400	`billing_cycle_not_available`	The requested plan has no public price for this billing period and currency.	Read /prices without a billing_cycle filter and select one of the returned unit/count options.
409	`catalog_variant_ambiguous`	More than one eligible public plan has the same family and SKU.	Use the existing UUID-based catalog workflow or ask support to correct the duplicate SKU. Do not guess which plan to deploy.
503	`catalog_unavailable`	The catalog could not be read safely.	Retry with backoff. Never infer stock from an outage; a partial catalog marks unavailable service types explicitly.
503	`order_options_unavailable`	Configuration choices or an owned SSH key could not be checked.	Retry configuration discovery; do not create an order with guessed configuration.
503	`dedicated_catalog_unavailable`	Dedicated stock could not be checked.	Wait and refresh dedicated discovery. VPS discovery remains usable independently.
400	`order_config_invalid`	The selected product’s required configuration is missing or invalid.	Read its order-options and correct the fields reported in the response.
400	`price_not_found`	The selected currency or billing period is unavailable.	Use a current billing option and quote the same complete cart you intend to order.
400	`validation_error`	A field or request body is invalid.	Correct the fields identified in details. Do not retry an unchanged invalid request.
400	`idempotency_key_required`	This action needs a valid Idempotency-Key header.	Use 8–128 letters, digits, dots, underscores, colons or hyphens. Save the key for this intended operation.
400	`invalid_idempotency_key`	The supplied request key has an invalid format.	Correct its format before sending the request.
401 / 403	`unauthorized`	Credentials are missing, invalid, expired or revoked, or the authentication mode is wrong.	Check the key, mode and environment in Settings → API. Do not retry with unchanged credentials.
401	`invalid_signature`	The signature, body hash, timestamp or nonce could not be verified.	Use the SDK, synchronize the clock and sign each attempt with a fresh nonce. Keep the same operation request key when retrying a write.
403	`scope_denied`	The key lacks the permission required by this endpoint.	Grant only the required scope in Settings → API. A different service ID will not bypass ownership checks.
403	`ip_blocked`	The source IP is blocked or outside the key’s allowlist.	Check your actual outbound IP and the API key allowlist. Do not try to bypass restrictions with forwarded headers.
403	`service_disabled`	API access is disabled for the account.	Review the account’s API access settings or contact support.
404	`not_found`	The resource is unavailable to this account or does not exist.	Use an owned name or ID from your own discovery/list response and check the environment.
400	`invalid_domain_identifier`	The selector is not a valid domain name or service UUID.	Use a domain name, not a URL, IP, wildcard or hostname with a port.
409	`domain_identifier_ambiguous`	More than one eligible domain service matches that name in your account.	Select the intended service UUID from your own domain list.
409	`template_identifier_ambiguous`	Multiple DNS templates in your account (or the system fallback scope) match that name.	Use the exact UUID returned by the DNS template list. Other customers are never included.
400	`domain_identifier_mismatch`	The path domain differs from the domain in the query/body.	Use one consistent owned domain, or omit the redundant domain field for name-based Website Protection reads.
409	`idempotency_conflict`	A request key was reused for a different request.	Do not change the body or target of an existing operation. Use a new key only for a genuinely new intended operation.
409	`idempotency_in_progress`	The matching request is still processing.	Wait as directed by Retry-After, check resource/task status, and keep the same key and exact request.
429	`rate_limited`	The key has reached its request limit.	Honor Retry-After; back off with jitter and reduce polling. Do not parallelize retries.
409	`dedicated_configuration_unavailable`	The selected dedicated configuration, region or OS option is unavailable.	Refresh the dedicated catalog and choose a currently available option before preparing another order.
409	`dedicated_os_ssh_keys_not_supported`	The selected OS profile does not support SSH key installation.	Choose a compatible OS or omit the SSH key; never submit a private key.
404	`ssh_key_not_found`	The public SSH key is not available to this account.	List your SSH keys and use one of the returned IDs.
409	`ssh_key_not_available`	The selected SSH key has no usable public key.	Check or replace the public key before deployment/reinstallation.
502	`protection_update_unconfirmed`	A Website Protection write may have persisted, but its result is uncertain.	Check the protection state and change history before making another change. Preserve the request ID and changeId, if returned.
502	`country_policy_sync_incomplete`	The country policy was saved but is not enforced everywhere yet.	Read the saved rule and retry the same update. Do not treat saved=true as proof of full enforcement.
502	`proxy_policy_unavailable`	The country policy could not be confirmed.	Read the saved rule before retrying. State may be unknown.
502	`proxy_policy_response_invalid`	The country policy response could not be validated.	Read the saved rule before retrying and provide the request ID to support if it persists.

Server failures and interrupted connections

Generic API server failures intentionally omit internal error codes and provider details and use the same nested envelope with service_unavailable. An edge/network failure can also return non-JSON or no response at all.

json

{
  "ok": false,
  "error": {
    "code": "service_unavailable",
    "message": "The service is temporarily unavailable.",
    "request_id": "00000000-0000-4000-8000-000000000001",
    "field_errors": []
  }
}

Read-only GET requests can be retried with bounded backoff and jitter. SDKs perform limited retries for selected transient read failures; they do not automatically retry writes. A timeout or 5xx on a write does not prove it failed: check the resource, invoice or task before retrying. Where supported, reuse the same Idempotency-Key and identical request. Do not create a new operation key just because the response was lost.

For 429, honor the HTTP Retry-After header. SDK timeout, network_error and response_too_large codes describe client-side failures, not API error responses. For persistent errors, send support the request ID, HTTP status, method, endpoint and UTC time—never API secrets or passwords.

See error handling in PHP, Node.js, Python and Go

This reference is generated from the current OpenAPI schema and documents 182 public operations. Each operation has a stable operationId and shows its method, path, parameters, required permissions and response models. cURL is selected by default; switch to Node.js, PHP, Python or Go for native HTTP examples. Download the OpenAPI JSON for client generation.

Use the integration guide for SDK/CLI 0.1.17 installation, authentication, pagination, retries, idempotency, webhooks and workflows. Generic OpenAPI clients do not automatically implement HMAC signing; use Bearer authentication or an official SDK unless you implement signing yourself.

Current purchase and operation workflows

SDK/CLI 0.1.17 supports contract 2026-10-07.1. Read GET /v1/version and GET /v1/capabilities, then discover product purchase policies and requirements before configuring a purchase. A quote is optional: discovery can lead directly to an authorized deployment. Quotes do not reserve stock or lock prices; send an authorized max_total ceiling for the full final order amount.

Draft order creation does not charge the account. Atomic deployment is the documented exception: it combines order creation, payment of the full final order amount from account balance and queued provisioning. Paid is not ready; accepted is not completed. Service lifecycle status is separate from runtime power state.

Supported tracked deployment, VPS and dedicated writes can return a canonical operation receipt and be recovered using their original idempotency key. This does not extend recovery to every write or historical request. See HTTP, SDK, CLI and MCP examples. DNSSEC uses its separate endpoint and state contract.

Pagination is endpoint-specific. Follow each endpoint's page/limit, cursor/next_cursor or offset/next_offset contract. limit is the canonical page-size request parameter; page_size and pageSize are deprecated compatibility aliases only where documented.

For service lists, ownership and filters are applied server-side before pagination. GET /v1/services defaults to active and suspended. group_by=type groups only the current page; GET /v1/services/grouped returns the complete inventory under its documented status/type filters, with its legacy active-only default. Pass status explicitly for this compatibility endpoint; prefer /v1/services?statuses=active,suspended&group_by=type for new automation.

API errors use the canonical nested error.code, error.message, error.request_id and error.field_errors structure. Flat error fields remain legacy compatibility fields. Most CLI lifecycle --request-key flags are optional; DNSSEC enable/disable require an explicit key. Preserve generated keys for retries. Examples describe requests and responses; this page does not send API requests.