{"openapi":"3.1.0","info":{"title":"BlazingFast Customer API","version":"v1","description":"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."},"servers":[{"url":"https://api.blazingfast.io","description":"Production"}],"tags":[{"name":"Integrations","description":"Version and capability discovery, credentials, OAuth connections, account audit and integration metadata."},{"name":"Deployments","description":"Configure and quote a regional deployment, then authorize the full final order amount from account balance and queue provisioning. A quote is read-only; deployment is a financial write."},{"name":"Catalog","description":"Simple read-only discovery of regions, flat products and eligible operating-system images. Requires an authenticated API key."},{"name":"TCP Proxy","description":"Customer TCP Proxy port mappings, traffic analytics, source/country policies and per-port limits."},{"name":"Billing","description":"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."},{"name":"Services","description":"List services, inspect billing details, and manage supported renewals, upgrades, billing settings, autopay and termination."},{"name":"Service DNS/WAF","description":"Manage website proxying, protection, origins and SSL settings for a hosting service. For protection on an owned DNS record without a hosting service ID, use the DNS record-protection endpoints instead."},{"name":"VPS","description":"Read VPS status and usage, control power, reinstall an operating system, update SSH keys, and manage snapshots and backups. Reinstallation and restoration can overwrite data; inspect the target first."},{"name":"Dedicated Servers","description":"Browse dedicated server options, create unpaid deployments, inspect progress and tasks, and manage power, reinstall, rescue or password reset. Reinstall erases disks. Credential reads require separate permissions and must not be logged."},{"name":"DNS","description":"Create an empty zone or use a template, JSON records or a zone file. Preview imports, manage DNS records, and inspect record protection and country policies. A DNS zone is not a domain registration."},{"name":"Domains","description":"Check domain availability and manage registrations, contacts, nameservers, transfer settings, locks and privacy."},{"name":"SSH","description":"Manage saved SSH keys for server access. Use public-key names and fingerprints for routine automation; do not share private keys with an AI assistant."},{"name":"Firewall","description":"Read and manage firewall policies and rules, then apply them to eligible VPS services. Check that changes preserve SSH and management access."},{"name":"Storage","description":"List storage volumes, check eligible servers, and attach, detach or rename supported volumes. Volumes provide storage capacity; backups provide recovery."}],"components":{"securitySchemes":{"SignedAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"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."},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"api-key-secret","description":"Alternative mode for integrations that prefer Authorization: Bearer <prefix.secret>. Key status, expiry, scope checks, IP policy, and rate limits still apply."}}},"paths":{"/v1/api-credentials":{"get":{"tags":["Integrations"],"summary":"List your API credentials","description":"Owner-only, secret-free inventory. Cursor pagination defaults to 50. Managed MCP credentials are read-only here.","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum items, default 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Next UUID cursor.","schema":{"type":"string"}},{"name":"include_revoked","in":"query","required":false,"description":"Include revoked keys.","schema":{"type":"string","enum":["true","false"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Credential inventory.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"prefix":{"type":"string","maxLength":32},"mode":{"type":"string","enum":["signed","bearer"]},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_ip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"scopes":{"type":"array","items":{"type":"string","maxLength":80}},"allowed_cidrs":{"type":"array","items":{"type":"string","maxLength":64}}},"required":["id","name","prefix","mode","enabled","created_at","expires_at","revoked_at","last_used_at","last_used_ip","scopes","allowed_cidrs"],"additionalProperties":false},"maxItems":100},"next_cursor":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["ok","items","next_cursor"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":"00000000-0000-4000-8000-000000000001","name":"Example integration","prefix":"ak_EXAMPLE","mode":"signed","enabled":true,"created_at":"2026-10-01T00:00:00.000Z","expires_at":"2026-11-01T00:00:00.000Z","revoked_at":null,"last_used_at":null,"last_used_ip":null,"scopes":["billing.services.read"],"allowed_cidrs":[]}],"next_cursor":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["api_credentials.read"]},{"BearerAuth":["api_credentials.read"]}],"operationId":"apiCredentials"},"post":{"tags":["Integrations"],"summary":"Create a restricted API credential","description":"Requires a stable Idempotency-Key. Requested scopes and allowed CIDRs cannot exceed the issuer; expiry is capped by the issuer. The secret is returned only on issuance or same-key retry within 24 hours. Managed MCP/support keys cannot delegate.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"type":"array","items":{"type":"string","enum":["audit.read","api_credentials.read","api_credentials.write","oauth.connections.read","oauth.connections.write","billing.balance.read","billing.invoices.read","billing.orders.read","billing.products.read","billing.services.read","billing.services.write","billing.transactions.read","billing.unpaid_total.read","billing.order.create","billing.invoice.pay","vps.read","vps.credentials.read","vps.write","dedicated.read","dedicated.credentials.read","dedicated.write","dns.read","dns.write","domains.read","domains.write","ssh.read","ssh.write","firewall.read","firewall.write","storage.read","storage.write","tcp_proxy.read","tcp_proxy.write","webhooks.read","webhooks.write"]},"minItems":1,"maxItems":35},"mode":{"type":"string","enum":["signed","bearer"],"default":"signed"},"ttl_days":{"type":"integer","minimum":1,"maximum":365,"default":30},"allowed_cidrs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":50}},"required":["name","scopes"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created credential and signing secret.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"prefix":{"type":"string","maxLength":32},"mode":{"type":"string","enum":["signed","bearer"]},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_ip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"scopes":{"type":"array","items":{"type":"string","maxLength":80}},"allowed_cidrs":{"type":"array","items":{"type":"string","maxLength":64}}},"required":["id","name","prefix","mode","enabled","created_at","expires_at","revoked_at","last_used_at","last_used_ip","scopes","allowed_cidrs"],"additionalProperties":false},"secret":{"type":"string","pattern":"^sk_[A-Za-z0-9_-]{43}$"}},"required":["ok","item","secret"],"additionalProperties":false},"example":{"ok":true,"item":{"id":"00000000-0000-4000-8000-000000000001","name":"Example integration","prefix":"ak_EXAMPLE","mode":"signed","enabled":true,"created_at":"2026-10-01T00:00:00.000Z","expires_at":"2026-11-01T00:00:00.000Z","revoked_at":null,"last_used_at":null,"last_used_ip":null,"scopes":["billing.services.read"],"allowed_cidrs":[]},"secret":"sk_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEX"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["api_credentials.write"]},{"BearerAuth":["api_credentials.write"]}],"parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"operationId":"apiCredentialCreate"}},"/v1/api-credentials/{id}":{"get":{"tags":["Integrations"],"summary":"Read your credential metadata","description":"Never returns signing secrets.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned credential UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Credential metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"prefix":{"type":"string","maxLength":32},"mode":{"type":"string","enum":["signed","bearer"]},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_ip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"scopes":{"type":"array","items":{"type":"string","maxLength":80}},"allowed_cidrs":{"type":"array","items":{"type":"string","maxLength":64}}},"required":["id","name","prefix","mode","enabled","created_at","expires_at","revoked_at","last_used_at","last_used_ip","scopes","allowed_cidrs"],"additionalProperties":false}},"required":["ok","item"],"additionalProperties":false},"example":{"ok":true,"item":{"id":"00000000-0000-4000-8000-000000000001","name":"Example integration","prefix":"ak_EXAMPLE","mode":"signed","enabled":true,"created_at":"2026-10-01T00:00:00.000Z","expires_at":"2026-11-01T00:00:00.000Z","revoked_at":null,"last_used_at":null,"last_used_ip":null,"scopes":["billing.services.read"],"allowed_cidrs":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["api_credentials.read"]},{"BearerAuth":["api_credentials.read"]}],"operationId":"apiCredential"},"patch":{"tags":["Integrations"],"summary":"Update a restricted API credential","description":"Change name, scopes, expiry, enabled state or allowed CIDRs without exceeding the current issuer. Revoked or managed credentials cannot be reactivated.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned credential UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"type":"array","items":{"type":"string","enum":["audit.read","api_credentials.read","api_credentials.write","oauth.connections.read","oauth.connections.write","billing.balance.read","billing.invoices.read","billing.orders.read","billing.products.read","billing.services.read","billing.services.write","billing.transactions.read","billing.unpaid_total.read","billing.order.create","billing.invoice.pay","vps.read","vps.credentials.read","vps.write","dedicated.read","dedicated.credentials.read","dedicated.write","dns.read","dns.write","domains.read","domains.write","ssh.read","ssh.write","firewall.read","firewall.write","storage.read","storage.write","tcp_proxy.read","tcp_proxy.write","webhooks.read","webhooks.write"]},"minItems":1,"maxItems":35},"allowed_cidrs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":50},"enabled":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated credential metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"prefix":{"type":"string","maxLength":32},"mode":{"type":"string","enum":["signed","bearer"]},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_ip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"scopes":{"type":"array","items":{"type":"string","maxLength":80}},"allowed_cidrs":{"type":"array","items":{"type":"string","maxLength":64}}},"required":["id","name","prefix","mode","enabled","created_at","expires_at","revoked_at","last_used_at","last_used_ip","scopes","allowed_cidrs"],"additionalProperties":false}},"required":["ok","item"],"additionalProperties":false},"example":{"ok":true,"item":{"id":"00000000-0000-4000-8000-000000000001","name":"Example integration","prefix":"ak_EXAMPLE","mode":"signed","enabled":true,"created_at":"2026-10-01T00:00:00.000Z","expires_at":"2026-11-01T00:00:00.000Z","revoked_at":null,"last_used_at":null,"last_used_ip":null,"scopes":["billing.services.read"],"allowed_cidrs":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["api_credentials.write"]},{"BearerAuth":["api_credentials.write"]}],"operationId":"apiCredentialUpdate"},"delete":{"tags":["Integrations"],"summary":"Revoke an API credential","description":"Disables an owned ordinary credential; does not delete history. Managed MCP grants use connection revocation instead.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned credential UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Credential revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["api_credentials.write"]},{"BearerAuth":["api_credentials.write"]}],"operationId":"apiCredentialRevoke"}},"/v1/api-credentials/{id}/rotate":{"post":{"tags":["Integrations"],"summary":"Rotate an API credential","description":"Requires Idempotency-Key. Replaces prefix and secret immediately; old authentication stops working. Use a different management key, or the dashboard, to rotate the key used by an integration. Self-rotation is rejected to avoid losing access after an interrupted response. Superseded receipts never reveal obsolete secrets.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned ordinary credential UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Rotated credential and secret.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"prefix":{"type":"string","maxLength":32},"mode":{"type":"string","enum":["signed","bearer"]},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_used_ip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"scopes":{"type":"array","items":{"type":"string","maxLength":80}},"allowed_cidrs":{"type":"array","items":{"type":"string","maxLength":64}}},"required":["id","name","prefix","mode","enabled","created_at","expires_at","revoked_at","last_used_at","last_used_ip","scopes","allowed_cidrs"],"additionalProperties":false},"secret":{"type":"string","pattern":"^sk_[A-Za-z0-9_-]{43}$"}},"required":["ok","item","secret"],"additionalProperties":false},"example":{"ok":true,"item":{"id":"00000000-0000-4000-8000-000000000001","name":"Example integration","prefix":"ak_EXAMPLE","mode":"signed","enabled":true,"created_at":"2026-10-01T00:00:00.000Z","expires_at":"2026-11-01T00:00:00.000Z","revoked_at":null,"last_used_at":null,"last_used_ip":null,"scopes":["billing.services.read"],"allowed_cidrs":[]},"secret":"sk_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEX"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["api_credentials.write"]},{"BearerAuth":["api_credentials.write"]}],"operationId":"apiCredentialRotate"}},"/v1/oauth/connections":{"get":{"tags":["Integrations"],"summary":"List connected applications","description":"Owner-only hosted MCP OAuth connection inventory. Does not expose access tokens, refresh tokens or internal client credentials. Connection-management transport must be configured.","responses":{"200":{"description":"Connected applications.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"application":{"type":"string","maxLength":200},"scopes":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":100},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"policy":{"type":"string","enum":["read_only","approval","full","legacy"]},"revoked":{"type":"boolean"},"enabled":{"type":"boolean"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"access_policy":{"type":"string","enum":["read_only","approval","full_access","legacy"]}},"required":["id","application","scopes","created_at","expires_at","policy","revoked","enabled","last_used_at","access_policy"],"additionalProperties":false},"maxItems":100}},"required":["ok","items"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":"00000000-0000-4000-8000-000000000001","application":"Example application","scopes":["billing.services.read"],"created_at":"2026-10-01T00:00:00.000Z","expires_at":"2026-11-01T00:00:00.000Z","policy":"read_only","access_policy":"read_only","enabled":true,"last_used_at":null,"revoked":false}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["oauth.connections.read"]},{"BearerAuth":["oauth.connections.read"]}],"parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"operationId":"oauthConnections"}},"/v1/oauth/connections/{id}":{"delete":{"tags":["Integrations"],"summary":"Revoke a connected application","description":"Revokes only this account’s grant using the existing fenced revocation flow. Repeating revocation is safe. Does not grant or expand permissions.","parameters":[{"name":"id","in":"path","required":true,"description":"Connection UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Connection revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["oauth.connections.write"]},{"BearerAuth":["oauth.connections.write"]}],"operationId":"oauthConnectionRevoke"}},"/v1/audit/actions":{"get":{"tags":["Integrations"],"summary":"List durable customer API action events","description":"Requested intent is saved before entering a write handler; accepted is not completion. Terminal operation results are recorded separately. Covers customer API and hosted MCP writes. Broader Billing dashboard/admin/committed state observations are available through audit/business. Updates are blocked; privileged retention deletes after the configured period.","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum items, default 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Next event cursor.","schema":{"type":"string"}},{"name":"resource_id","in":"query","required":false,"description":"Resource ID or zone name.","schema":{"type":"string"}},{"name":"phase","in":"query","required":false,"description":"Action phase.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Account-owned action history.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["api_key","hosted_mcp","oauth_app","user","system","local_mcp","support","unknown"]},"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["type","id"],"additionalProperties":false},"action":{"type":"string","maxLength":300},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"phase":{"type":"string","enum":["requested","accepted","rejected","unknown","succeeded","failed","cancelled"]},"operation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","request_id","actor","action","resource_id","phase","operation_id","created_at"],"additionalProperties":false},"maxItems":100}},"required":["ok","next_cursor","items"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":"1","request_id":"00000000-0000-4000-8000-000000000002","actor":{"type":"api_key","id":"00000000-0000-4000-8000-000000000001"},"action":"POST /v1/vps/:serviceId/reboot","resource_id":"00000000-0000-4000-8000-000000000001","phase":"accepted","operation_id":null,"created_at":"2026-10-01T00:00:00.000Z"}],"next_cursor":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["audit.read"]},{"BearerAuth":["audit.read"]}],"operationId":"auditActions"}},"/v1/audit/business":{"get":{"tags":["Integrations"],"summary":"List account-owned business audit events","description":"Durable Billing dashboard/admin request acceptance and committed service/invoice/order/lifecycle observations. A committed lifecycle log row is not proof of task completion. Database transitions without a verified human identity use system; identities are never inferred from metadata. Admin identity is withheld from customer responses. No payloads, credentials, provider errors or financial customer details are logged. This does not cover every action of other services or constitute a WORM export.","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum items, default 50 (1–100).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Exclusive cursor returned as next_cursor.","schema":{"type":"string"}},{"name":"actor_type","in":"query","required":false,"description":"Verified actor category.","schema":{"type":"string"}},{"name":"resource_type","in":"query","required":false,"description":"service, invoice, order or account.","schema":{"type":"string"}},{"name":"resource_id","in":"query","required":false,"description":"Owned resource UUID.","schema":{"type":"string"}},{"name":"request_id","in":"query","required":false,"description":"Correlation UUID.","schema":{"type":"string"}},{"name":"action","in":"query","required":false,"description":"Exact action.","schema":{"type":"string"}},{"name":"phase","in":"query","required":false,"description":"requested, accepted, rejected, unknown or committed.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Inclusive ISO timestamp.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Inclusive ISO timestamp.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Owner-filtered business observations, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"request_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["user","admin","api","api_key","hosted_mcp","system","unknown"]},"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["type","id"],"additionalProperties":false},"source":{"type":"string","enum":["dashboard","admin","api","database","lifecycle"]},"action":{"type":"string","maxLength":300},"canonical_action":{"type":"string","maxLength":300},"resource_type":{"type":"string","enum":["service","invoice","order","account"]},"resource_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"phase":{"type":"string","enum":["requested","accepted","rejected","unknown","committed"]},"changes":{"type":"object","properties":{"before":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"after":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"additionalProperties":false},"created_at":{"type":"string","format":"date-time"}},"required":["id","request_id","actor","source","action","resource_type","resource_id","phase","changes","created_at"],"additionalProperties":false},"maxItems":100}},"required":["ok","next_cursor","items"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":"1","request_id":null,"actor":{"type":"system","id":null},"source":"database","action":"service.changed","resource_type":"service","resource_id":"00000000-0000-4000-8000-000000000001","phase":"committed","changes":{"before":{"status":"active"},"after":{"status":"suspended"}},"created_at":"2026-10-01T00:00:00.000Z"}],"next_cursor":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["audit.read"]},{"BearerAuth":["audit.read"]}],"operationId":"auditBusiness"}},"/v1/domains/{serviceId}/dnssec":{"get":{"tags":["Domains"],"summary":"Read DNSSEC status","description":"Returns the locally saved DNSSEC state for your registered domain. Use action refresh to check current registration state. Zone signing and parent propagation are separate from enabled registration status.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Saved DNSSEC status.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"domain":{"type":"string","maxLength":253},"tld":{"type":"string","maxLength":253},"service_id":{"type":"string","format":"uuid"},"domain_name":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}]},"support":{"type":"string","enum":["supported","unsupported","unknown"]},"nameservers":{"type":"array","items":{"type":"string","maxLength":253},"maxItems":13},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"type":"number","const":257,"enum":[257]},"protocol":{"type":"number","const":3,"enum":[3]},"alg":{"type":"integer"},"pub_key":{"type":"string","minLength":40,"maxLength":4096,"pattern":"^[A-Za-z0-9+/]+={0,2}$"}},"required":["flags","protocol","alg","pub_key"],"additionalProperties":false},"maxItems":32},"status":{"type":"string","enum":["registrar_configured","not_configured"]},"delegationStatus":{"type":"string","const":"not_verified","enum":["not_verified"]},"dnsProvider":{"type":"string","enum":["managed","external"]},"canEnable":{"type":"boolean"},"canDisable":{"type":"boolean"},"enabled":{"type":"boolean"},"checkedAt":{"type":"string","format":"date-time"},"operation":{"type":"string","enum":["idle","pending","queued","running","unconfirmed","failed"]},"operationId":{"type":"string","format":"uuid"},"requestedAction":{"type":"string","enum":["enable","disable"]},"operationUpdatedAt":{"type":"string","format":"date-time"},"errorCode":{"type":"string","maxLength":80},"source":{"type":"string","const":"local","enum":["local"]}},"required":["ok","domain","tld","support","nameservers","keys","status","delegationStatus","dnsProvider","canEnable","canDisable","enabled","checkedAt","operation","source"],"additionalProperties":false},"example":{"ok":true,"domain":"example.com","tld":"com","support":"supported","nameservers":["dns1.blazingfast.io","dns2.blazingfast.io"],"keys":[],"status":"not_configured","delegationStatus":"not_verified","dnsProvider":"managed","canEnable":true,"canDisable":false,"enabled":false,"checkedAt":"2026-10-01T00:00:00.000Z","operation":"idle","source":"local"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"domainDnssec"},"post":{"tags":["Domains"],"summary":"Update or check DNSSEC","description":"Enable managed signing or submit external public DNSKEY records, disable delegation without deleting signing keys, or refresh status. Enable/disable require acknowledgement and an Idempotency-Key. Refresh requires domains.read; changes require domains.write. HTTP 200 returns refresh state; HTTP 202 means enable/disable accepted, not completed: poll the same DNSSEC GET for operation and errorCode. operationId is a DNSSEC operation UUID, not a generic /v1/operations handle. queued/pending/running are ongoing; unconfirmed requires reconciliation; failed is not success. idle with the intended registrar status confirms registrar configuration only. delegationStatus=not_verified never proves parent-zone propagation. Do not repeat an unconfirmed change.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Required for enable/disable: 8–128 letters, digits, dot, underscore, colon or hyphen. Reuse identical payloads; not required for refresh.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"action":{"type":"string","const":"enable","enum":["enable"]},"mode":{"type":"string","const":"managed","enum":["managed"]},"acknowledge":{"type":"boolean","const":true,"enum":[true]}},"required":["action","mode","acknowledge"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"enable","enum":["enable"]},"mode":{"type":"string","const":"external","enum":["external"]},"acknowledge":{"type":"boolean","const":true,"enum":[true]},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"type":"number","const":257,"enum":[257]},"protocol":{"type":"number","const":3,"enum":[3]},"alg":{"type":"integer"},"pub_key":{"type":"string","minLength":40,"maxLength":4096,"pattern":"^[A-Za-z0-9+/]+={0,2}$"}},"required":["flags","protocol","alg","pub_key"],"additionalProperties":false},"minItems":1,"maxItems":4}},"required":["action","mode","acknowledge","keys"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"disable","enum":["disable"]},"acknowledge":{"type":"boolean","const":true,"enum":[true]}},"required":["action","acknowledge"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"refresh","enum":["refresh"]}},"required":["action"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Current DNSSEC state after refresh (domains.read).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"domain":{"type":"string","maxLength":253},"tld":{"type":"string","maxLength":253},"service_id":{"type":"string","format":"uuid"},"domain_name":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}]},"support":{"type":"string","enum":["supported","unsupported","unknown"]},"nameservers":{"type":"array","items":{"type":"string","maxLength":253},"maxItems":13},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"type":"number","const":257,"enum":[257]},"protocol":{"type":"number","const":3,"enum":[3]},"alg":{"type":"integer"},"pub_key":{"type":"string","minLength":40,"maxLength":4096,"pattern":"^[A-Za-z0-9+/]+={0,2}$"}},"required":["flags","protocol","alg","pub_key"],"additionalProperties":false},"maxItems":32},"status":{"type":"string","enum":["registrar_configured","not_configured"]},"delegationStatus":{"type":"string","const":"not_verified","enum":["not_verified"]},"dnsProvider":{"type":"string","enum":["managed","external"]},"canEnable":{"type":"boolean"},"canDisable":{"type":"boolean"},"enabled":{"type":"boolean"},"checkedAt":{"type":"string","format":"date-time"},"operation":{"type":"string","enum":["idle","pending","queued","running","unconfirmed","failed"]},"operationId":{"type":"string","format":"uuid"},"requestedAction":{"type":"string","enum":["enable","disable"]},"operationUpdatedAt":{"type":"string","format":"date-time"},"errorCode":{"type":"string","maxLength":80},"source":{"type":"string","const":"local","enum":["local"]}},"required":["ok","domain","tld","support","nameservers","keys","status","delegationStatus","dnsProvider","canEnable","canDisable","enabled","checkedAt","operation","source"],"additionalProperties":false}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"202":{"description":"Enable/disable accepted with domains.write; poll this domain’s DNSSEC GET, not the generic operation endpoint.","content":{"application/json":{"example":{"ok":true,"domain":"example.com","tld":"com","support":"supported","nameservers":["dns1.blazingfast.io","dns2.blazingfast.io"],"keys":[],"status":"not_configured","delegationStatus":"not_verified","dnsProvider":"managed","canEnable":false,"canDisable":false,"enabled":false,"checkedAt":"2026-10-01T00:00:00.000Z","operation":"queued","operationId":"00000000-0000-4000-8000-000000000002","requestedAction":"enable","source":"local"},"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"domain":{"type":"string","maxLength":253},"tld":{"type":"string","maxLength":253},"service_id":{"type":"string","format":"uuid"},"domain_name":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}]},"support":{"type":"string","enum":["supported","unsupported","unknown"]},"nameservers":{"type":"array","items":{"type":"string","maxLength":253},"maxItems":13},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"type":"number","const":257,"enum":[257]},"protocol":{"type":"number","const":3,"enum":[3]},"alg":{"type":"integer"},"pub_key":{"type":"string","minLength":40,"maxLength":4096,"pattern":"^[A-Za-z0-9+/]+={0,2}$"}},"required":["flags","protocol","alg","pub_key"],"additionalProperties":false},"maxItems":32},"status":{"type":"string","enum":["registrar_configured","not_configured"]},"delegationStatus":{"type":"string","const":"not_verified","enum":["not_verified"]},"dnsProvider":{"type":"string","enum":["managed","external"]},"canEnable":{"type":"boolean"},"canDisable":{"type":"boolean"},"enabled":{"type":"boolean"},"checkedAt":{"type":"string","format":"date-time"},"operation":{"type":"string","enum":["idle","pending","queued","running","unconfirmed","failed"]},"operationId":{"type":"string","format":"uuid"},"requestedAction":{"type":"string","enum":["enable","disable"]},"operationUpdatedAt":{"type":"string","format":"date-time"},"errorCode":{"type":"string","maxLength":80},"source":{"type":"string","const":"local","enum":["local"]}},"required":["ok","domain","tld","support","nameservers","keys","status","delegationStatus","dnsProvider","canEnable","canDisable","enabled","checkedAt","operation","source"],"additionalProperties":false}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]},{"SignedAuth":["domains.write"]},{"BearerAuth":["domains.write"]}],"operationId":"domainDnssecUpdate"}},"/v1/dns/zones/{name}/history":{"get":{"tags":["DNS"],"summary":"List DNS change history","description":"Owned-zone changes with DNS values and protection state. Stable cursor continuation; only this owner’s history is returned.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum changes (default 10; 1–50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"cursor","in":"query","required":false,"description":"nextCursor returned by the preceding response; scoped to this owner and zone.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"DNS change history with nextCursor.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"nextCursor":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string","maxLength":100},"status":{"type":"string","maxLength":30},"actorType":{"type":"string","maxLength":30},"restoredFromId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"changes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":253},"type":{"type":"string","maxLength":16},"changetype":{"type":"string","maxLength":16},"beforeTtl":{"anyOf":[{"type":"integer"},{"type":"null"}]},"afterTtl":{"anyOf":[{"type":"integer"},{"type":"null"}]},"beforeValues":{"type":"array","items":{"type":"string","maxLength":65535},"maxItems":1000},"afterValues":{"type":"array","items":{"type":"string","maxLength":65535},"maxItems":1000}},"required":["name","type","changetype","beforeTtl","afterTtl","beforeValues","afterValues"],"additionalProperties":false},"maxItems":1000},"protectionChanges":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":253},"before":{"anyOf":[{"type":"object","properties":{"proxied":{"type":"boolean"},"protection":{"type":"boolean"},"values":{"type":"array","items":{"type":"string","maxLength":253},"maxItems":1000}},"required":["proxied","protection","values"],"additionalProperties":false},{"type":"null"}]},"after":{"anyOf":[{"type":"object","properties":{"proxied":{"type":"boolean"},"protection":{"type":"boolean"},"values":{"type":"array","items":{"type":"string","maxLength":253},"maxItems":1000}},"required":["proxied","protection","values"],"additionalProperties":false},{"type":"null"}]}},"required":["name","before","after"],"additionalProperties":false},"maxItems":1000},"beforeRecordCount":{"type":"integer","minimum":0},"afterRecordCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"}},"required":["id","action","status","actorType","restoredFromId","changes","protectionChanges","beforeRecordCount","afterRecordCount","createdAt"],"additionalProperties":false},"maxItems":50}},"required":["ok","nextCursor","items"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":"00000000-0000-4000-8000-000000000002","action":"records.update","status":"applied","actorType":"userapi","restoredFromId":null,"changes":[{"name":"example.com.","type":"A","changetype":"REPLACE","beforeTtl":300,"afterTtl":300,"beforeValues":["192.0.2.9"],"afterValues":["192.0.2.10"]}],"protectionChanges":[],"beforeRecordCount":3,"afterRecordCount":3,"createdAt":"2026-10-01T00:00:00.000Z"}],"nextCursor":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"dnsHistory"}},"/v1/dns/zones/{name}/history/{changeId}/restore":{"post":{"tags":["DNS"],"summary":"Restore DNS change","description":"Restores the state before the selected applied change, including protection and origin addresses. Requires acknowledgement, a stable retry key and current entitlements. A locked or ambiguous zone is not modified.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"name":"changeId","in":"path","required":true,"description":"Owned DNS change UUID.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable retry key.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"acknowledge":{"type":"boolean","const":true,"enum":[true]}},"required":["acknowledge"],"additionalProperties":false}}}},"responses":{"200":{"description":"Restored DNS/protection state or already-current result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"already":{"type":"boolean","const":true,"enum":[true]}},"required":["ok","already"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"appliedTo":{"type":"string","enum":["snapshot","live_dns"]},"changeId":{"type":"string","format":"uuid"},"restoredFromId":{"type":"string","format":"uuid"}},"required":["ok","appliedTo","changeId","restoredFromId"],"additionalProperties":false}]},"example":{"ok":true,"appliedTo":"live_dns","changeId":"00000000-0000-4000-8000-000000000001","restoredFromId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsHistoryRestore"}},"/v1/dns/zones/{name}/stats":{"get":{"tags":["Service DNS/WAF"],"summary":"Read Website Protection statistics","description":"Website Protection (WAF) traffic aggregates for your owned zone and subdomains, bounded to current ownership. This compatibility route does not report authoritative DNS query statistics. Requests, bytes, latency, cache-hit percentage, decisions, countries and automation categories. No individual visitor identities or raw logs. Missing collection is an error, not zero traffic.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"name":"range","in":"query","required":false,"description":"Window; defaults to 24h.","schema":{"type":"string","enum":["1h","24h","7d"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Owned-domain network aggregates. Requests are counts; bytes are bytes; latency is milliseconds.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"domain":{"type":"string","maxLength":253},"range":{"type":"string","enum":["1h","24h","7d"]},"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastEventAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"coverage":{"type":"string","const":"proxy_network","enum":["proxy_network"]},"coverageNote":{"type":"string","maxLength":300},"summary":{"type":"object","properties":{"requests":{"type":"number","minimum":0},"bytes":{"type":"number","minimum":0},"averageResponseMs":{"type":"number","minimum":0},"cacheHitPercent":{"type":"number","minimum":0,"maximum":100},"serverErrors":{"type":"number","minimum":0},"blocked":{"type":"number","minimum":0}},"required":["requests","bytes","averageResponseMs","cacheHitPercent","serverErrors","blocked"],"additionalProperties":false},"traffic":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"requests":{"type":"number","minimum":0},"bytes":{"type":"number","minimum":0}},"required":["at","requests","bytes"],"additionalProperties":false},"maxItems":300},"countries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128},"requests":{"type":"number","minimum":0}},"required":["name","requests"],"additionalProperties":false},"maxItems":250},"automation":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128},"requests":{"type":"number","minimum":0}},"required":["name","requests"],"additionalProperties":false},"maxItems":250},"statuses":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128},"requests":{"type":"number","minimum":0}},"required":["name","requests"],"additionalProperties":false},"maxItems":250},"decisions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":128},"requests":{"type":"number","minimum":0}},"required":["name","requests"],"additionalProperties":false},"maxItems":250}},"required":["ok","domain","range","since","until","updatedAt","lastEventAt","coverage","coverageNote","summary","traffic","countries","automation","statuses","decisions"],"additionalProperties":false},"example":{"ok":true,"domain":"example.com","range":"24h","since":"2026-10-01T00:00:00.000Z","until":"2026-11-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z","lastEventAt":null,"coverage":"proxy_network","coverageNote":"Proxy traffic only.","summary":{"requests":0,"bytes":0,"averageResponseMs":0,"cacheHitPercent":0,"serverErrors":0,"blocked":0},"traffic":[],"countries":[],"automation":[],"statuses":[],"decisions":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"dnsStats"}},"/v1/regions":{"get":{"tags":["Catalog"],"summary":"List regions","description":"Lists regions with VPS image choices or public orderable dedicated stock. Codes are lowercase; this does not reserve capacity.","parameters":[{"name":"limit","in":"query","description":"Maximum items, default 50 (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Start offset, default 0. Use next_offset from the response; null means finished. This contract has no page or pageSize fields.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Region list with next_offset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"name":{"type":"string","maxLength":200}},"required":["id","name"],"additionalProperties":false}},"next_offset":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["ok","items","next_offset"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":"nl","name":"Netherlands"},{"id":"pt","name":"Portugal"}],"next_offset":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"regions"}},"/v1/products":{"get":{"tags":["Catalog"],"summary":"List products","description":"Flat public, active product variants with public, active parent products. type is the high-level normalized service family; product_code is the more specific purchasable product family. tcp-proxy maps to type=other, waf to type=dns, and license to type=other. Do not substitute product_code values into a type filter. id is the readable SKU; product_id and variant_id are order identifiers. Region and type eligibility are applied before pagination. CPU is vCPUs for VPS or sockets for dedicated; ram is MiB and disk is GiB. billing_cycles contains server-configured or converted period prices in the requested currency, exact decimal strings, unit/count and setup_fee. price prefers the monthly option. Account currency governs quotes and orders. configuration_url discovers required fields, defaults, compatible OS choices, connectivity and IP add-ons. Add-ons and tax are excluded from catalog prices: quote the complete cart before ordering. Domain pricing requires a live domain quote. available is not a reservation; capacity_verified=false for VPS. Dedicated available_stock is known compatible stock. A backend outage returns partial=true, unavailable_types and availability=unknown where possible; unknown stock is null, not zero. Image/stock snapshots are cached internally up to 15 seconds; checkout revalidates.","parameters":[{"name":"limit","in":"query","description":"Maximum items, default 50 (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Start offset, default 0. Use next_offset from the response; null means finished. This contract has no page or pageSize fields.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"product_code","in":"query","required":false,"description":"More specific purchasable product family; distinct from type. tcp-proxy maps to other, waf to dns, license to other.","schema":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]}},{"name":"region","in":"query","required":false,"description":"Region code from GET /v1/regions, for example nl or pt. Case-insensitive.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"High-level normalized type filter; tcp-proxy/license use other and waf uses dns. Distinct from product_code; applied before pagination.","schema":{"type":"string","enum":["vps","dedicated","webhosting","storage","dns","domain","other"]}},{"name":"currency","in":"query","required":false,"description":"Configured pricing currency: EUR or USD, default EUR.","schema":{"type":"string","enum":["EUR","USD"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Flat product list with next_offset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":200},"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":"string","format":"uuid"},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"type":{"type":"string","enum":["vps","dedicated","webhosting","storage","dns","domain","other"]},"purchase":{"type":"object","properties":{"draft_order":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false},"atomic_deploy":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false}},"required":["draft_order","atomic_deploy"],"additionalProperties":false},"requirements_url":{"type":"string","pattern":"^\\/v1\\/"},"product_code":{"anyOf":[{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]},{"type":"null"}]},"variant_code":{"type":"string","maxLength":200},"region":{"anyOf":[{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},{"type":"null"}]},"regions":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"maxItems":100},"cpu":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"cpu_unit":{"anyOf":[{"type":"string","enum":["vcpus","sockets"]},{"type":"null"}]},"ram":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"ram_unit":{"type":"string","const":"MiB","enum":["MiB"]},"disk":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"disk_unit":{"type":"string","const":"GiB","enum":["GiB"]},"price":{"anyOf":[{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},{"type":"null"}]},"billing_cycle":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"billing_cycles":{"type":"array","items":{"type":"object","properties":{"billing_cycle":{"type":"string","maxLength":200},"unit":{"type":"string","maxLength":200},"count":{"type":"integer","exclusiveMinimum":0},"period_months":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"price":{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},"setup_fee":{"anyOf":[{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},{"type":"null"}]},"currency":{"type":"string","enum":["EUR","USD"]}},"required":["billing_cycle","unit","count","period_months","price","setup_fee","currency"],"additionalProperties":false},"maxItems":100},"currency":{"type":"string","enum":["EUR","USD"]},"available":{"type":"boolean"},"capacity_verified":{"type":"boolean"},"configuration_code":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"available_stock":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"pricing_mode":{"type":"string","enum":["domain_quote","configured"]},"availability":{"type":"string","enum":["available","unavailable","unknown"]},"configuration_url":{"type":"string","pattern":"^\\/v1\\/billing\\/products\\/[0-9a-f-]+\\/variants\\/[0-9a-f-]+\\/order-options$"}},"required":["id","product_id","variant_id","name","type","region","regions","cpu","cpu_unit","ram","ram_unit","disk","disk_unit","price","billing_cycle","billing_cycles","currency","available","capacity_verified","configuration_code","available_stock"],"additionalProperties":false},"maxItems":100},"next_offset":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"partial":{"type":"boolean"},"unavailable_types":{"type":"array","items":{"type":"string","enum":["vps","dedicated"]}}},"required":["ok","items","next_offset"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":"8G","product_id":"00000000-0000-4000-8000-000000000001","variant_id":"00000000-0000-4000-8000-000000000002","name":"Example VPS","type":"vps","product_code":"vps","variant_code":"8G","region":"nl","regions":["nl"],"cpu":4,"cpu_unit":"vcpus","ram":8192,"ram_unit":"MiB","disk":100,"disk_unit":"GiB","price":"12.00","billing_cycle":"monthly","billing_cycles":[{"billing_cycle":"monthly","unit":"MONTH","count":1,"period_months":1,"price":"12.00","setup_fee":"0","currency":"EUR"},{"billing_cycle":"quarterly","unit":"QUARTAL","count":1,"period_months":3,"price":"30.00","setup_fee":"0","currency":"EUR"}],"currency":"EUR","available":true,"capacity_verified":false,"configuration_code":null,"available_stock":null}],"next_offset":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"products"}},"/v1/products/{region}":{"get":{"tags":["Catalog"],"summary":"List products in a region","description":"Flat public, active product variants with public, active parent products. type is the high-level normalized service family; product_code is the more specific purchasable product family. tcp-proxy maps to type=other, waf to type=dns, and license to type=other. Do not substitute product_code values into a type filter. id is the readable SKU; product_id and variant_id are order identifiers. Region and type eligibility are applied before pagination. CPU is vCPUs for VPS or sockets for dedicated; ram is MiB and disk is GiB. billing_cycles contains server-configured or converted period prices in the requested currency, exact decimal strings, unit/count and setup_fee. price prefers the monthly option. Account currency governs quotes and orders. configuration_url discovers required fields, defaults, compatible OS choices, connectivity and IP add-ons. Add-ons and tax are excluded from catalog prices: quote the complete cart before ordering. Domain pricing requires a live domain quote. available is not a reservation; capacity_verified=false for VPS. Dedicated available_stock is known compatible stock. A backend outage returns partial=true, unavailable_types and availability=unknown where possible; unknown stock is null, not zero. Image/stock snapshots are cached internally up to 15 seconds; checkout revalidates. Applies region restrictions on the server before pagination. A conflicting region query parameter is rejected.","parameters":[{"name":"region","in":"path","required":true,"description":"Region code, for example nl or pt; all includes every eligible region.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum items, default 50 (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Start offset, default 0. Use next_offset from the response; null means finished. This contract has no page or pageSize fields.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"product_code","in":"query","required":false,"description":"More specific purchasable product family; distinct from type. tcp-proxy maps to other, waf to dns, license to other.","schema":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]}},{"name":"type","in":"query","required":false,"description":"High-level normalized type filter; tcp-proxy/license use other and waf uses dns. Distinct from product_code.","schema":{"type":"string","enum":["vps","dedicated","webhosting","storage","dns","domain","other"]}},{"name":"currency","in":"query","required":false,"description":"Configured pricing currency: EUR or USD, default EUR.","schema":{"type":"string","enum":["EUR","USD"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Region-filtered flat product list with next_offset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":200},"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":"string","format":"uuid"},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"type":{"type":"string","enum":["vps","dedicated","webhosting","storage","dns","domain","other"]},"purchase":{"type":"object","properties":{"draft_order":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false},"atomic_deploy":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false}},"required":["draft_order","atomic_deploy"],"additionalProperties":false},"requirements_url":{"type":"string","pattern":"^\\/v1\\/"},"product_code":{"anyOf":[{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]},{"type":"null"}]},"variant_code":{"type":"string","maxLength":200},"region":{"anyOf":[{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},{"type":"null"}]},"regions":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"maxItems":100},"cpu":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"cpu_unit":{"anyOf":[{"type":"string","enum":["vcpus","sockets"]},{"type":"null"}]},"ram":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"ram_unit":{"type":"string","const":"MiB","enum":["MiB"]},"disk":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"disk_unit":{"type":"string","const":"GiB","enum":["GiB"]},"price":{"anyOf":[{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},{"type":"null"}]},"billing_cycle":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"billing_cycles":{"type":"array","items":{"type":"object","properties":{"billing_cycle":{"type":"string","maxLength":200},"unit":{"type":"string","maxLength":200},"count":{"type":"integer","exclusiveMinimum":0},"period_months":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"price":{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},"setup_fee":{"anyOf":[{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},{"type":"null"}]},"currency":{"type":"string","enum":["EUR","USD"]}},"required":["billing_cycle","unit","count","period_months","price","setup_fee","currency"],"additionalProperties":false},"maxItems":100},"currency":{"type":"string","enum":["EUR","USD"]},"available":{"type":"boolean"},"capacity_verified":{"type":"boolean"},"configuration_code":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"available_stock":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"pricing_mode":{"type":"string","enum":["domain_quote","configured"]},"availability":{"type":"string","enum":["available","unavailable","unknown"]},"configuration_url":{"type":"string","pattern":"^\\/v1\\/billing\\/products\\/[0-9a-f-]+\\/variants\\/[0-9a-f-]+\\/order-options$"}},"required":["id","product_id","variant_id","name","type","region","regions","cpu","cpu_unit","ram","ram_unit","disk","disk_unit","price","billing_cycle","billing_cycles","currency","available","capacity_verified","configuration_code","available_stock"],"additionalProperties":false},"maxItems":100},"next_offset":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"partial":{"type":"boolean"},"unavailable_types":{"type":"array","items":{"type":"string","enum":["vps","dedicated"]}}},"required":["ok","items","next_offset"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":"8G","product_id":"00000000-0000-4000-8000-000000000001","variant_id":"00000000-0000-4000-8000-000000000002","name":"Example VPS","type":"vps","product_code":"vps","variant_code":"8G","region":"nl","regions":["nl"],"cpu":4,"cpu_unit":"vcpus","ram":8192,"ram_unit":"MiB","disk":100,"disk_unit":"GiB","price":"12.00","billing_cycle":"monthly","billing_cycles":[{"billing_cycle":"monthly","unit":"MONTH","count":1,"period_months":1,"price":"12.00","setup_fee":"0","currency":"EUR"},{"billing_cycle":"quarterly","unit":"QUARTAL","count":1,"period_months":3,"price":"30.00","setup_fee":"0","currency":"EUR"}],"currency":"EUR","available":true,"capacity_verified":false,"configuration_code":null,"available_stock":null}],"next_offset":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"getProductsByRegion"}},"/v1/products/{region}/list":{"get":{"tags":["Catalog"],"summary":"List product codes by region","description":"Compact grouped public variant codes: products maps each family to an array of exact SKUs. Region eligibility is applied before pagination. limit counts variants across all families, not families; default 50. Follow next_offset until null and merge groups. Codes do not prove available stock; read the variant details and options. all includes all eligible regions; use a specific region for details and deployment. partial=true means collection is incomplete, not known zero stock. Existing flat catalog endpoints remain unchanged.","parameters":[{"name":"region","in":"path","required":true,"description":"Region code or all.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum items, default 50 (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Start offset, default 0. Use next_offset from the response; null means finished. This contract has no page or pageSize fields.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"currency","in":"query","required":false,"description":"Pricing currency: EUR or USD; defaults to EUR. Quotes and orders use account currency.","schema":{"type":"string","enum":["EUR","USD"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Grouped family/SKU discovery with continuation.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"region":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"products":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$"},"maxItems":100}},"next_offset":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"partial":{"type":"boolean"},"unavailable_types":{"type":"array","items":{"type":"string","enum":["vps","dedicated"]}}},"required":["ok","region","products","next_offset"],"additionalProperties":false},"example":{"ok":true,"region":"nl","products":{"vps":["8G"]},"next_offset":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"productCodes"}},"/v1/products/{region}/list/{productCode}":{"get":{"tags":["Catalog"],"summary":"List variant codes for a family","description":"Same compact grouped response, restricted to the selected product family before pagination. An empty family array means no matching public plans on this page. Read detail availability separately; this does not reserve stock.","parameters":[{"name":"region","in":"path","required":true,"description":"Eligible region, for example nl or pt. A single region is required.","schema":{"type":"string"}},{"name":"productCode","in":"path","required":true,"description":"Product family.","schema":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]}},{"name":"limit","in":"query","description":"Maximum items, default 50 (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Start offset, default 0. Use next_offset from the response; null means finished. This contract has no page or pageSize fields.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"currency","in":"query","required":false,"description":"Pricing currency: EUR or USD; defaults to EUR. Quotes and orders use account currency.","schema":{"type":"string","enum":["EUR","USD"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Selected family and exact SKUs with continuation.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"region":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"products":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$"},"maxItems":100}},"next_offset":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"partial":{"type":"boolean"},"unavailable_types":{"type":"array","items":{"type":"string","enum":["vps","dedicated"]}}},"required":["ok","region","products","next_offset"],"additionalProperties":false},"example":{"ok":true,"region":"nl","products":{"vps":["8G"]},"next_offset":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"getProductsByRegionListByProductCode"}},"/v1/products/{region}/{productCode}/{variantCode}":{"get":{"tags":["Catalog"],"summary":"Read a product by public code","description":"Exact eligible region/family/SKU lookup. Returns safe hardware, public billing prices, availability, order UUIDs and links to prices/options/quote/deployment. Duplicate public SKUs in the family/region return catalog_variant_ambiguous (409); no plan is silently selected. Missing or hidden plans return 404. Provider outages may return unknown availability; they are never represented as known zero stock. This read is not a reservation.","parameters":[{"name":"region","in":"path","required":true,"description":"Eligible region, for example nl or pt. A single region is required.","schema":{"type":"string"}},{"name":"productCode","in":"path","required":true,"description":"Product family.","schema":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]}},{"name":"variantCode","in":"path","required":true,"description":"Exact case-sensitive public SKU, for example 2G or PTV4-1. Never an internal inventory ID.","schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"Pricing currency: EUR or USD; defaults to EUR. Quotes and orders use account currency.","schema":{"type":"string","enum":["EUR","USD"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Exact public plan and discovery links.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string","maxLength":200},"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":"string","format":"uuid"},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"type":{"type":"string","enum":["vps","dedicated","webhosting","storage","dns","domain","other"]},"purchase":{"type":"object","properties":{"draft_order":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false},"atomic_deploy":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false}},"required":["draft_order","atomic_deploy"],"additionalProperties":false},"requirements_url":{"type":"string","pattern":"^\\/v1\\/"},"product_code":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]},"variant_code":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$"},"region":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"regions":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"maxItems":100},"cpu":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"cpu_unit":{"anyOf":[{"type":"string","enum":["vcpus","sockets"]},{"type":"null"}]},"ram":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"ram_unit":{"type":"string","const":"MiB","enum":["MiB"]},"disk":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"disk_unit":{"type":"string","const":"GiB","enum":["GiB"]},"price":{"anyOf":[{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},{"type":"null"}]},"billing_cycle":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"billing_cycles":{"type":"array","items":{"type":"object","properties":{"billing_cycle":{"type":"string","maxLength":200},"unit":{"type":"string","maxLength":200},"count":{"type":"integer","exclusiveMinimum":0},"period_months":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"price":{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},"setup_fee":{"anyOf":[{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},{"type":"null"}]},"currency":{"type":"string","enum":["EUR","USD"]}},"required":["billing_cycle","unit","count","period_months","price","setup_fee","currency"],"additionalProperties":false},"maxItems":100},"currency":{"type":"string","enum":["EUR","USD"]},"available":{"type":"boolean"},"capacity_verified":{"type":"boolean"},"configuration_code":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"available_stock":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"pricing_mode":{"type":"string","enum":["domain_quote","configured"]},"availability":{"type":"string","enum":["available","unavailable","unknown"]},"configuration_url":{"type":"string","pattern":"^\\/v1\\/billing\\/products\\/[0-9a-f-]+\\/variants\\/[0-9a-f-]+\\/order-options$"},"prices_url":{"type":"string","maxLength":512,"pattern":"^\\/v1\\/products\\/"},"options_url":{"type":"string","maxLength":512,"pattern":"^\\/v1\\/products\\/"},"quote_url":{"type":"string","const":"/v1/billing/orders/preview","enum":["/v1/billing/orders/preview"]},"deploy_url":{"type":"string","maxLength":512,"pattern":"^\\/v1\\/deploy\\/"}},"required":["id","product_id","variant_id","name","type","product_code","variant_code","region","regions","cpu","cpu_unit","ram","ram_unit","disk","disk_unit","price","billing_cycle","billing_cycles","currency","available","capacity_verified","configuration_code","available_stock","prices_url","options_url","quote_url"],"additionalProperties":false},"partial":{"type":"boolean"},"unavailable_types":{"type":"array","items":{"type":"string","enum":["vps","dedicated"]}}},"required":["ok","item"],"additionalProperties":false},"example":{"ok":true,"item":{"id":"8G","product_id":"00000000-0000-4000-8000-000000000001","variant_id":"00000000-0000-4000-8000-000000000002","name":"Example VPS","type":"vps","product_code":"vps","variant_code":"8G","region":"nl","regions":["nl"],"cpu":4,"cpu_unit":"vcpus","ram":8192,"ram_unit":"MiB","disk":100,"disk_unit":"GiB","price":"12.00","billing_cycle":"monthly","billing_cycles":[{"billing_cycle":"monthly","unit":"MONTH","count":1,"period_months":1,"price":"12.00","setup_fee":"0","currency":"EUR"},{"billing_cycle":"quarterly","unit":"QUARTAL","count":1,"period_months":3,"price":"30.00","setup_fee":"0","currency":"EUR"}],"currency":"EUR","available":true,"capacity_verified":false,"configuration_code":null,"available_stock":null,"prices_url":"/v1/products/nl/vps/8G/prices","options_url":"/v1/products/nl/vps/8G/options","quote_url":"/v1/billing/orders/preview","deploy_url":"/v1/deploy/nl/vps/8G"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"getProduct"}},"/v1/products/{region}/{productCode}/{variantCode}/prices":{"get":{"tags":["Catalog"],"summary":"Read billing prices by public code","description":"Base-plan prices only, as exact decimal strings with unit/count, setup_fee and currency. Optional billing_cycle filters configured periods; an unavailable period returns billing_cycle_not_available (400). An omitted period returns all public prices in the requested currency. Add-ons and tax require POST /v1/billing/orders/preview using the returned order UUIDs. Domain prices require a domain quote. price_scope=base_plan is not a final payable amount.","parameters":[{"name":"region","in":"path","required":true,"description":"Eligible region, for example nl or pt. A single region is required.","schema":{"type":"string"}},{"name":"productCode","in":"path","required":true,"description":"Product family.","schema":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]}},{"name":"variantCode","in":"path","required":true,"description":"Exact case-sensitive public SKU, for example 2G or PTV4-1. Never an internal inventory ID.","schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"Pricing currency: EUR or USD; defaults to EUR. Quotes and orders use account currency.","schema":{"type":"string","enum":["EUR","USD"]}},{"name":"billing_cycle","in":"query","required":false,"description":"Optional billing period from the returned values.","schema":{"type":"string","enum":["monthly","quarterly","semi_annually","annually","biennially","triennially","hourly","daily","weekly","one_time","custom"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Configured billing prices; never a fabricated price for a missing period.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"region":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"product_code":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]},"variant_code":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$"},"currency":{"type":"string","enum":["EUR","USD"]},"prices":{"type":"array","items":{"type":"object","properties":{"billing_cycle":{"type":"string","maxLength":200},"unit":{"type":"string","maxLength":200},"count":{"type":"integer","exclusiveMinimum":0},"period_months":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"price":{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},"setup_fee":{"anyOf":[{"type":"string","pattern":"^(?:0|[1-9]\\d{0,13})(?:\\.\\d{1,4})?$"},{"type":"null"}]},"currency":{"type":"string","enum":["EUR","USD"]}},"required":["billing_cycle","unit","count","period_months","price","setup_fee","currency"],"additionalProperties":false},"maxItems":100},"pricing_mode":{"type":"string","enum":["domain_quote","configured"]},"price_scope":{"type":"string","const":"base_plan","enum":["base_plan"]},"quote_url":{"type":"string","const":"/v1/billing/orders/preview","enum":["/v1/billing/orders/preview"]}},"required":["ok","region","product_code","variant_code","currency","prices","pricing_mode","price_scope","quote_url"],"additionalProperties":false},"example":{"ok":true,"region":"nl","product_code":"vps","variant_code":"8G","currency":"EUR","prices":[{"billing_cycle":"monthly","unit":"MONTH","count":1,"period_months":1,"price":"12.00","setup_fee":"0","currency":"EUR"},{"billing_cycle":"quarterly","unit":"QUARTAL","count":1,"period_months":3,"price":"30.00","setup_fee":"0","currency":"EUR"}],"price_scope":"base_plan","pricing_mode":"configured","quote_url":"/v1/billing/orders/preview"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"productPrices"}},"/v1/products/{region}/{productCode}/{variantCode}/options":{"get":{"tags":["Catalog"],"summary":"Read configuration options by public code","description":"Same authoritative configuration discovery as the UUID order-options endpoint, resolved by eligible region, family and exact SKU. Returns required inputs, defaults, compatible OS choices, owned SSH-key selection fields, connectivity options and IP/add-on limits. No private provider settings, inventory identities or credentials. Discovery does not reserve stock or pay.","parameters":[{"name":"region","in":"path","required":true,"description":"Eligible region, for example nl or pt. A single region is required.","schema":{"type":"string"}},{"name":"productCode","in":"path","required":true,"description":"Product family.","schema":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]}},{"name":"variantCode","in":"path","required":true,"description":"Exact case-sensitive public SKU, for example 2G or PTV4-1. Never an internal inventory ID.","schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"Pricing currency: EUR or USD; defaults to EUR. Quotes and orders use account currency.","schema":{"type":"string","enum":["EUR","USD"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Validated public order options with exact order UUIDs.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"productId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"supported":{"type":"boolean"},"capacityVerified":{"type":"boolean"},"purchase":{"type":"object","properties":{"draft_order":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false},"atomic_deploy":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false}},"required":["draft_order","atomic_deploy"],"additionalProperties":false},"requirements":{"type":"object","properties":{"atomic_deploy":{"type":"object","additionalProperties":{"type":"object","properties":{"required":{"type":"boolean"},"type":{"type":"string","enum":["string","integer","number","array"]},"format":{"type":"string","enum":["hostname","domain","uuid","ipv4"]},"source":{"type":"string","pattern":"^\\/v1\\/"},"min_items":{"type":"integer","exclusiveMinimum":0},"max_items":{"type":"integer","exclusiveMinimum":0},"allowed_values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]},"maxItems":100}},"required":["required","type"],"additionalProperties":false}}},"required":["atomic_deploy"],"additionalProperties":false},"reason":{"type":"string","enum":["unsupported_product_type","unsupported_location"]},"serviceType":{"anyOf":[{"type":"string"},{"type":"null"}]},"requiredFields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"format":{"type":"string","enum":["hostname","domain","uuid"]},"minLength":{"type":"number"}},"required":["field","label","description"],"additionalProperties":false}},"conditionalRequiredFields":{"type":"array","items":{"type":"object","properties":{"whenField":{"type":"string"},"whenEquals":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"format":{"type":"string","enum":["hostname","domain","uuid"]},"minLength":{"type":"number"}},"required":["field","label","description"],"additionalProperties":false}}},"required":["whenField","whenEquals","fields"],"additionalProperties":false}},"optionalFields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"description":{"type":"string"},"format":{"type":"string"}},"required":["field","description","format"],"additionalProperties":false}},"defaults":{"type":"object","properties":{"location":{"type":"string"}},"additionalProperties":false},"addons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"chargeType":{"type":"string"},"maxQty":{"anyOf":[{"type":"number"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"speedGbps":{"anyOf":[{"type":"number"},{"type":"null"}]},"billingOptions":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"currency":{"type":"string"},"price":{"anyOf":[{"type":"string"},{"type":"number"}]},"setupFee":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}},"required":["unit","count","currency","price"],"additionalProperties":false}}},"required":["key","name","chargeType","maxQty","kind","speedGbps","billingOptions"],"additionalProperties":false}},"billingOptions":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"currency":{"type":"string"},"price":{"anyOf":[{"type":"string"},{"type":"number"}]},"setupFee":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}},"required":["unit","count","currency","price"],"additionalProperties":false}},"currency":{"type":"string","enum":["EUR","USD"]},"quoteUrl":{"type":"string","const":"/v1/billing/orders/preview","enum":["/v1/billing/orders/preview"]},"orderUrl":{"type":"string","const":"/v1/billing/orders/draft","enum":["/v1/billing/orders/draft"]},"checkoutEnabled":{"type":"boolean"},"pricingMode":{"type":"string","enum":["configured","domain_quote"]},"connectivity":{"type":"object","properties":{"physicalCapacityGbps":{"anyOf":[{"type":"number"},{"type":"null"}]},"defaultGbps":{"anyOf":[{"type":"number"},{"type":"null"}]},"options":{"type":"array","items":{"type":"object","properties":{"speedGbps":{"type":"number","exclusiveMinimum":0}},"required":["speedGbps"],"additionalProperties":false}}},"required":["physicalCapacityGbps","defaultGbps","options"],"additionalProperties":false},"ipv4":{"type":"object","properties":{"included":{"type":"integer","minimum":0},"maxAdditional":{"type":"integer","minimum":0}},"required":["included","maxAdditional"],"additionalProperties":false},"orderExpirationMinutes":{"type":"number","exclusiveMinimum":0},"tcpProxy":{"type":"object","properties":{"includedPorts":{"type":"integer","exclusiveMinimum":0},"maxPorts":{"type":"integer","exclusiveMinimum":0}},"required":["includedPorts","maxPorts"],"additionalProperties":false},"locations":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"configurationCode":{"type":"string"},"availableStock":{"type":"integer","minimum":0},"operatingSystems":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"id":{"type":"number","exclusiveMinimum":0},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"arch":{"anyOf":[{"type":"string"},{"type":"null"}]},"isDefault":{"type":"boolean"},"sshKeysSupported":{"type":"boolean"}},"required":["code","name","family","version","arch","isDefault"],"additionalProperties":false}}},"required":["code","name","operatingSystems"],"additionalProperties":false}},"region":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"product_code":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]},"variant_code":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$"}},"required":["ok","productId","variantId","supported","capacityVerified","requiredFields","locations","region","product_code","variant_code"],"additionalProperties":false},"example":{"ok":true,"region":"nl","product_code":"vps","variant_code":"8G","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}]}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"productOptions"}},"/v1/my/services":{"get":{"tags":["Services"],"summary":"List my purchased services","description":"Read-only alias of GET /v1/services with identical ownership, scope, filters and response contract. Defaults to active+suspended; terminated services require an explicit filter. Lifecycle status is separate from runtime power. Hostname and region are included when known; passwords are available only from separately scoped credential endpoints.","parameters":[{"name":"status","in":"query","required":false,"description":"Service lifecycle status; defaults to active and suspended when no status filter is supplied. Power state is separate.","schema":{"type":"string","enum":["active","suspended","terminated","provisioning","error","maintenance","all"]}},{"name":"type","in":"query","required":false,"description":"High-level normalized service family: vps, dedicated, webhosting, storage, dns, domain or other (comma-separated). Distinct from catalog product_code: tcp-proxy and license map to other; waf maps to dns. Applied before pagination; use discovered product_code for purchasing.","schema":{"type":"string"}},{"name":"statuses","in":"query","required":false,"description":"Comma-separated lifecycle statuses, for example active,suspended. Use this or status, not both. Filtering and counts use service status, never runtime power state.","schema":{"type":"string"}},{"name":"types","in":"query","required":false,"description":"Comma-separated service types. Alias for type; do not supply both.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Search hostname, customer IPv4/IPv6, display name, product name, SKU or full service UUID; maximum 200 characters. Applied before pagination.","schema":{"type":"string"}},{"name":"external_id","in":"query","required":false,"description":"Exact customer integration reference; applied before pagination.","schema":{"type":"string"}},{"name":"label","in":"query","required":false,"description":"Exact metadata label match: key=value. Applied before pagination.","schema":{"type":"string"}},{"name":"include_counts","in":"query","required":false,"description":"Request counts only for selected statuses, with the same ownership, type and search filters. Omitted by default.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","required":false,"description":"Group the current page by type, retaining items and pagination.","schema":{"type":"string","enum":["type"]}},{"name":"page","in":"query","required":false,"description":"Page number for pagination.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"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.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page_size","in":"query","required":false,"description":"Deprecated compatibility alias for limit; values must match when supplied together.","schema":{"type":"integer"},"deprecated":true},{"name":"pageSize","in":"query","required":false,"description":"Deprecated compatibility alias for limit; range 1–100, default 50.","schema":{"type":"integer"},"deprecated":true},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Filtered purchased service instances.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"page":{"type":"integer","exclusiveMinimum":0},"pageSize":{"type":"integer","exclusiveMinimum":0},"total":{"type":"integer","minimum":0},"pages":{"type":"integer","exclusiveMinimum":0},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"activationAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingUnit":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingCount":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"object","additionalProperties":{"type":"string"}},"provisioning_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"meta":{"anyOf":[{"type":"object","properties":{"serviceType":{"type":"string"},"includedByDefault":{"type":"boolean"},"instanceIndex":{"type":"number"}},"additionalProperties":false},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"counts":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"group_by":{"type":"string","const":"type","enum":["type"]},"groups":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"activationAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingUnit":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingCount":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"object","additionalProperties":{"type":"string"}},"provisioning_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"meta":{"anyOf":[{"type":"object","properties":{"serviceType":{"type":"string"},"includedByDefault":{"type":"boolean"},"instanceIndex":{"type":"number"}},"additionalProperties":false},{"type":"null"}]}},"required":["id"],"additionalProperties":true}}}},"required":["ok","items"],"additionalProperties":true},"example":{"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"}}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]}],"deprecated":true,"operationId":"listMyServices"}},"/v1/vps/images":{"get":{"tags":["Catalog"],"summary":"List VPS images","description":"Returns VM-template OS codes and their region, family, version, architecture and default flag, without internal template references. Optional product_id and variant_id must be supplied together to restrict to a public VPS plan and its region. For full plan-specific configuration use the existing order-options endpoint. compatibility_verified=false means this is catalog discovery, not a physical capacity or placement guarantee. New VPS order configuration uses userConfig.os.code and uppercase userConfig.location.","parameters":[{"name":"limit","in":"query","description":"Maximum items, default 50 (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Start offset, default 0. Use next_offset from the response; null means finished. This contract has no page or pageSize fields.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"region","in":"query","required":false,"description":"Region code from GET /v1/regions, for example nl or pt. Case-insensitive.","schema":{"type":"string"}},{"name":"product_id","in":"query","required":false,"description":"Public product UUID; supply with variant_id.","schema":{"type":"string"}},{"name":"variant_id","in":"query","required":false,"description":"Public VPS variant UUID; supply with product_id.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"VPS OS images with next_offset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":200},"name":{"type":"string","maxLength":200},"family":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"version":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"arch":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"is_default":{"type":"boolean"},"region":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"}},"required":["id","name","family","version","arch","is_default","region"],"additionalProperties":false}},"next_offset":{"anyOf":[{"type":"number"},{"type":"null"}]},"compatibility_verified":{"type":"boolean"}},"required":["ok","items","next_offset"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":"debian-13","name":"Debian","family":"debian","version":"13","arch":"amd64","is_default":true,"region":"nl"}],"next_offset":null,"compatibility_verified":false}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"vpsImages"}},"/v1/dedicated/images":{"get":{"tags":["Catalog"],"summary":"List dedicated images","description":"Returns compatible OS profile IDs for public dedicated configurations with available stock. Filter by region and configuration_code from the product catalog. An image ID can occur in several configurations; preserve its region/configuration context. Supply the numeric id as osProfileId when creating a dedicated deployment.","parameters":[{"name":"limit","in":"query","description":"Maximum items, default 50 (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Start offset, default 0. Use next_offset from the response; null means finished. This contract has no page or pageSize fields.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"region","in":"query","required":false,"description":"Region code from GET /v1/regions, for example nl or pt. Case-insensitive.","schema":{"type":"string"}},{"name":"configuration_code","in":"query","required":false,"description":"Dedicated configuration code from GET /v1/products.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Compatible dedicated OS profiles with next_offset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0},"name":{"type":"string","maxLength":200},"region":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,15}$"},"configuration_code":{"type":"string","maxLength":200},"ssh_keys_supported":{"type":"boolean"}},"required":["id","name","region","configuration_code","ssh_keys_supported"],"additionalProperties":false}},"next_offset":{"anyOf":[{"type":"number"},{"type":"null"}]},"compatibility_verified":{"type":"boolean"}},"required":["ok","items","next_offset"],"additionalProperties":false},"example":{"ok":true,"items":[{"id":1,"name":"Debian 13","region":"pt","configuration_code":"EXAMPLE-PT","ssh_keys_supported":true}],"next_offset":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedImages"}},"/v1/ssh-keys":{"get":{"tags":["SSH"],"summary":"List my SSH keys","description":"Read-only alias of GET /v1/ssh/keys. Returns only keys owned by the authenticated account with names, fingerprints and public-key metadata; no private keys. Keeps the existing keys response contract (not a paginated catalog collection). Retrieve a selected public key through /v1/ssh/keys/{id}/public when required for provisioning.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Owned SSH key metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"fingerprint":{"type":"string"},"isPrimary":{"type":"boolean"},"hasPrivateKey":{"type":"boolean"},"type":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true}}},"required":["ok","keys"],"additionalProperties":true},"example":{"ok":true,"keys":[{"id":"00000000-0000-4000-8000-000000000001","name":"Example key","algorithm":"ed25519","fingerprint":"SHA256:example-fingerprint","isPrimary":false,"hasPrivateKey":false,"createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.read"]},{"BearerAuth":["ssh.read"]}],"operationId":"getSshKeys"}},"/v1/tcp-proxy/{serviceId}":{"get":{"tags":["TCP Proxy"],"summary":"Read TCP Proxy configuration","description":"Returns only customer configuration. Requires ownership or project service.view permission. tcpProxy is null for non-TCP services.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"TCP Proxy configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"tcpProxy":{"type":"object","properties":{"proxyIp":{"anyOf":[{"type":"string"},{"type":"null"}]},"backendIp":{"anyOf":[{"type":"string"},{"type":"null"}]},"ports":{"type":"array","items":{"type":"object","properties":{"listen":{"type":"number"},"backend":{"type":"number"},"protocol":{"type":"string"}},"required":["listen","backend"],"additionalProperties":true}},"includedPorts":{"type":"number"},"additionalPorts":{"type":"number"},"status":{"type":"string"},"allowedSourceCidrs":{"type":"array","items":{"type":"string"}},"blockedSourceCidrs":{"type":"array","items":{"type":"string"}},"countryPolicy":{"type":"object","properties":{"mode":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}}},"required":["mode","countries"],"additionalProperties":true},"defaults":{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}},"additionalProperties":true}},"required":["tcpProxy"],"additionalProperties":true,"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"tcpProxy":{"proxyIp":"192.0.2.20","backendIp":"192.0.2.10","ports":[{"listen":443,"backend":443}],"includedPorts":1,"additionalPorts":0,"defaults":{},"allowedSourceCidrs":[],"blockedSourceCidrs":[],"countryPolicy":{"mode":"disabled","countries":[]},"status":"active"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["tcp_proxy.read"]},{"BearerAuth":["tcp_proxy.read"]}],"operationId":"getTcpProxy"},"patch":{"tags":["TCP Proxy"],"summary":"Update TCP Proxy configuration","description":"Requires service.tcp-proxy.manage permission. Supply backendIp, ports, allowedSourceCidrs, blockedSourceCidrs or countryPolicy. Supplied arrays replace complete existing arrays; omitted fields remain unchanged. TCP country modes: disabled/allow/block. IPv4 only. Paid port entitlement is enforced. Send the same Idempotency-Key and body on retries; never retry an uncertain outcome with a new key.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"backend_ip":{"type":"string"},"ports":{"type":"array","items":{"anyOf":[{"type":"integer","minimum":1,"maximum":65535},{"type":"object","properties":{"listen":{"type":"integer","minimum":1,"maximum":65535},"backend":{"type":"integer","minimum":1,"maximum":65535},"backend_ip":{"type":"string"},"proxy_protocol_v2":{"type":"boolean"},"max_connections_per_ip":{"type":"integer","minimum":1,"maximum":1000000},"max_new_connections_per_second_per_ip":{"type":"integer","minimum":1,"maximum":1000000},"connection_burst":{"type":"integer","minimum":0,"maximum":1000000},"max_packets_per_second_per_ip":{"type":"integer","minimum":1,"maximum":10000000},"packet_burst":{"type":"integer","minimum":0,"maximum":10000000}},"required":["listen"],"additionalProperties":false}]},"minItems":1,"maxItems":512},"allowed_source_cidrs":{"type":"array","items":{"type":"string"},"maxItems":256},"blocked_source_cidrs":{"type":"array","items":{"type":"string"},"maxItems":256},"country_policy":{"type":"object","properties":{"mode":{"type":"string","enum":["disabled","allow","block"]},"countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"maxItems":256}},"required":["mode","countries"],"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated configuration; does not purchase extra ports.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"tcpProxy":{"type":"object","properties":{"proxyIp":{"anyOf":[{"type":"string"},{"type":"null"}]},"backendIp":{"anyOf":[{"type":"string"},{"type":"null"}]},"ports":{"type":"array","items":{"type":"object","properties":{"listen":{"type":"number"},"backend":{"type":"number"},"protocol":{"type":"string"}},"required":["listen","backend"],"additionalProperties":true}},"includedPorts":{"type":"number"},"additionalPorts":{"type":"number"},"status":{"type":"string"},"allowedSourceCidrs":{"type":"array","items":{"type":"string"}},"blockedSourceCidrs":{"type":"array","items":{"type":"string"}},"countryPolicy":{"type":"object","properties":{"mode":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}}},"required":["mode","countries"],"additionalProperties":true},"defaults":{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}},"additionalProperties":true}},"required":["ok","tcpProxy"],"additionalProperties":true,"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"ok":true,"tcpProxy":{"proxyIp":"192.0.2.20","backendIp":"192.0.2.10","ports":[{"listen":443,"backend":443}],"includedPorts":1,"additionalPorts":0,"defaults":{},"allowedSourceCidrs":[],"blockedSourceCidrs":[],"countryPolicy":{"mode":"disabled","countries":[]},"status":"active"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["tcp_proxy.write"]},{"BearerAuth":["tcp_proxy.write"]}],"operationId":"tcpProxyUpdate"}},"/v1/tcp-proxy/{serviceId}/stats":{"get":{"tags":["TCP Proxy"],"summary":"Read TCP Proxy analytics","description":"Window/bucket byte totals, observed connection events and blocked packet counts. Not instantaneous throughput or open sockets.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"range","in":"query","required":false,"description":"Time window (default 24h).","schema":{"type":"string","enum":["1h","24h","7d"]}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Time-window summary and bucketed analytics.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"proxyIp":{"type":"string"},"range":{"type":"string"},"since":{"type":"string"},"until":{"type":"string"},"updatedAt":{"type":"string"},"lastEventAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"retentionDays":{"type":"number"},"summary":{"type":"object","properties":{"connections":{"type":"number"},"bytesIn":{"type":"number"},"bytesOut":{"type":"number"},"limited":{"type":"number"},"errors":{"type":"number"},"averageDurationMs":{"type":"number"},"blockedPackets":{"type":"number"}},"required":["connections","bytesIn","bytesOut","limited","errors","averageDurationMs","blockedPackets"],"additionalProperties":true},"traffic":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"timestamp":{"anyOf":[{"type":"string"},{"type":"number"}]},"bytesIn":{"type":"number"},"bytesOut":{"type":"number"},"rx":{"type":"number"},"tx":{"type":"number"},"watts":{"anyOf":[{"type":"number"},{"type":"null"}]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"connections":{"type":"number"},"errors":{"type":"number"},"blockedPackets":{"type":"number"}},"additionalProperties":true}},"blockedTraffic":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"timestamp":{"anyOf":[{"type":"string"},{"type":"number"}]},"bytesIn":{"type":"number"},"bytesOut":{"type":"number"},"rx":{"type":"number"},"tx":{"type":"number"},"watts":{"anyOf":[{"type":"number"},{"type":"null"}]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"connections":{"type":"number"},"errors":{"type":"number"},"blockedPackets":{"type":"number"}},"additionalProperties":true}},"ports":{"type":"array","items":{"type":"object","properties":{"port":{"type":"number"},"connections":{"type":"number"},"bytesIn":{"type":"number"},"bytesOut":{"type":"number"}},"additionalProperties":true}},"statuses":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"count":{"type":"number"}},"additionalProperties":true}},"blockedPorts":{"type":"array","items":{"type":"object","properties":{"port":{"type":"number"},"count":{"type":"number"}},"additionalProperties":true}}},"required":["ok","proxyIp","range","since","until","updatedAt","lastEventAt","retentionDays","summary","traffic","blockedTraffic","ports","statuses","blockedPorts"],"additionalProperties":true},"example":{"ok":true,"proxyIp":"192.0.2.20","range":"24h","since":"2026-10-01T00:00:00.000Z","until":"2026-10-02T00:00:00.000Z","updatedAt":"2026-10-02T00:00:00.000Z","lastEventAt":null,"retentionDays":7,"summary":{"connections":0,"bytesIn":0,"bytesOut":0,"limited":0,"errors":0,"averageDurationMs":0,"blockedPackets":0},"traffic":[],"blockedTraffic":[],"ports":[],"statuses":[],"blockedPorts":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["tcp_proxy.read"]},{"BearerAuth":["tcp_proxy.read"]}],"operationId":"tcpProxyStats"}},"/v1/services/{serviceId}/dns/waf/record/config":{"get":{"tags":["Services"],"summary":"Read Website Protection settings","description":"Read-only HTTPS/origin and custom-loader flags. Unknown settings are null; no raw provider configuration, private keys or scripts.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your DNS zone name (example.com) or an owned service UUID. A name selects the owned zone directly; a UUID also requires domain in the query/body.","schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"description":"Owned DNS zone; required only with a UUID selector. Must match a domain-name selector when supplied.","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"A record name, e.g. @ or www.; default @.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Safe settings.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"settings":{"type":"object","properties":{"ssl_schema":{"anyOf":[{"type":"string"},{"type":"null"}]},"force_ssl":{"anyOf":[{"type":"string"},{"type":"null"}]},"ssl":{"anyOf":[{"type":"string"},{"type":"null"}]},"custom_loader":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ssl_schema","force_ssl","ssl","custom_loader"],"additionalProperties":true},"domain":{"type":"string"},"name":{"type":"string"}},"required":["ok","settings"],"additionalProperties":true},"example":{"ok":true,"settings":{"ssl_schema":null,"force_ssl":null,"ssl":null,"custom_loader":null}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"getServiceDnsWafConfig"}},"/v1/dns/zones/{name}/records/config":{"get":{"tags":["DNS"],"summary":"Read Website Protection record settings","description":"Read-only safe HTTPS/origin and custom-loader flags for an active, owned, proxied A record. No service UUID or domain registration is needed. Unknown flags are null; no raw provider configuration, scripts or keys are exposed.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Record name, e.g. @ or www.; default @.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Safe Website Protection settings.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"settings":{"type":"object","properties":{"ssl_schema":{"anyOf":[{"type":"string"},{"type":"null"}]},"force_ssl":{"anyOf":[{"type":"string"},{"type":"null"}]},"ssl":{"anyOf":[{"type":"string"},{"type":"null"}]},"custom_loader":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ssl_schema","force_ssl","ssl","custom_loader"],"additionalProperties":true},"domain":{"type":"string"},"name":{"type":"string"}},"required":["ok","settings"],"additionalProperties":true},"example":{"ok":true,"domain":"example.com","name":"www","settings":{"ssl_schema":"https","force_ssl":"1","ssl":"ecc","custom_loader":"0"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"dnsRecordConfig"}},"/v1/dns/zones/{name}/country-policy":{"get":{"tags":["DNS"],"summary":"Read website country policy","description":"For an owned, active, proxied A record.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"name":"record","in":"query","required":false,"description":"Record name; default @.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Saved policy.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"hostname":{"type":"string"},"policy":{"type":"object","properties":{"mode":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}},"unknown":{"type":"string"},"whitelist_bypass":{"type":"boolean"}},"required":["mode","countries","unknown","whitelist_bypass"],"additionalProperties":true},"saved":{"type":"boolean"},"synchronized":{"type":"boolean"}},"required":["ok","hostname","policy"],"additionalProperties":true},"example":{"ok":true,"hostname":"example.com","policy":{"mode":"off","countries":[],"unknown":"allow","whitelist_bypass":true}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"getDnsCountryPolicy"},"put":{"tags":["DNS"],"summary":"Replace website country policy","description":"Body: record and policy containing mode (off/allow/deny), countries (ISO alpha-2), optional unknown (allow/deny) and whitelist_bypass. Replacement can block visitors. Send an Idempotency-Key. Check saved and synchronized independently.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"record":{"type":"string","minLength":1,"maxLength":253},"policy":{"type":"object","properties":{"mode":{"type":"string","enum":["off","allow","deny"]},"countries":{"type":"array","items":{"type":"string"},"maxItems":249,"default":[]},"unknown":{"type":"string","enum":["allow","deny"]},"whitelist_bypass":{"type":"boolean","default":false}},"required":["mode"],"additionalProperties":false}},"required":["record","policy"],"additionalProperties":false,"description":"Use valid ISO alpha-2 country codes. allow/deny requires at least one country; off disables the policy."}}}},"responses":{"200":{"description":"Saved and synchronized policy.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"hostname":{"type":"string"},"policy":{"type":"object","properties":{"mode":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}},"unknown":{"type":"string"},"whitelist_bypass":{"type":"boolean"}},"required":["mode","countries","unknown","whitelist_bypass"],"additionalProperties":true},"saved":{"type":"boolean"},"synchronized":{"type":"boolean"}},"required":["ok","hostname","policy"],"additionalProperties":true},"example":{"ok":true,"hostname":"example.com","policy":{"mode":"off","countries":[],"unknown":"allow","whitelist_bypass":true},"saved":true,"synchronized":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsCountryPolicySet"}},"/v1/dns/zones/{name}/records/protection":{"get":{"tags":["DNS"],"summary":"Read DNS record protection","description":"Read saved mitigation state for an owned, active, proxied A record, including external origins. No hosting service ID required. Null protection/stateUnknown must not be interpreted as disabled.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"A record name; default @.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Mitigation state, proxy state, origin IPs and synchronization status. No internal provider configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"fqdn":{"type":"string","description":"Lowercase hostname without a trailing root dot, for example example.com. Inputs accept either form. DNS RRset names and record values retain DNS notation."},"type":{"type":"string"},"proxied":{"type":"boolean"},"protection":{"type":"boolean"},"originValues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ttl":{"type":"number"},"stateUnknown":{"type":"boolean"},"pending":{"type":"boolean"},"lastSyncedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"changeId":{"type":"string"}},"required":["ok","fqdn","type","proxied","protection"],"additionalProperties":true},"example":{"ok":true,"fqdn":"example.com","type":"A","proxied":true,"protection":true,"originValues":["192.0.2.10"],"ttl":300,"stateUnknown":false,"pending":false,"lastSyncedAt":"2026-10-01T00:00:00.000Z"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"getDnsRecordProtection"},"post":{"tags":["DNS"],"summary":"Change DNS record protection","description":"Toggle mitigation only; preserves proxy routing, origin addresses, DNS values and TTL. Enabling requires an active entitlement or eligible origin IPs. Send an Idempotency-Key. MCP requests require dashboard approval. A failed/unconfirmed response may have changed provider state; never assume it did not execute.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253},"enabled":{"type":"boolean"}},"required":["name","enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Confirmed mitigation state and audit change ID, or stateUnknown on an unconfirmed update.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"fqdn":{"type":"string","description":"Lowercase hostname without a trailing root dot, for example example.com. Inputs accept either form. DNS RRset names and record values retain DNS notation."},"type":{"type":"string"},"proxied":{"type":"boolean"},"protection":{"type":"boolean"},"originValues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ttl":{"type":"number"},"stateUnknown":{"type":"boolean"},"pending":{"type":"boolean"},"lastSyncedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"changeId":{"type":"string"}},"required":["ok","fqdn","type","proxied","protection"],"additionalProperties":true},"example":{"ok":true,"fqdn":"example.com","type":"A","proxied":true,"protection":true,"stateUnknown":false,"changeId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsRecordProtectionSet"}},"/v1/billing/balance":{"get":{"tags":["Billing"],"summary":"Check wallet balance","description":"Returns current account credit and currency so billing dashboards or automation can decide whether balance payment is available.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Current balance details.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"exists":{"type":"boolean"},"currency":{"type":"string"},"credit":{"type":"string"},"vcredit":{"type":"string"}},"required":["ok","exists","currency","credit","vcredit"],"additionalProperties":true},"example":{"ok":true,"exists":true,"currency":"EUR","credit":"100","vcredit":"0"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.balance.read"]},{"BearerAuth":["billing.balance.read"]}],"operationId":"billingBalance"}},"/v1/billing/invoices":{"get":{"tags":["Billing"],"summary":"Browse invoices","description":"Returns paginated customer invoices. Use this to build invoice history views, overdue checks, or reconciliation jobs.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"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.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page_size","in":"query","required":false,"description":"Deprecated compatibility alias for limit; values must match when supplied together.","schema":{"type":"integer"},"deprecated":true},{"name":"pageSize","in":"query","required":false,"description":"Deprecated compatibility alias for limit; range 1–100, default 50.","schema":{"type":"integer"},"deprecated":true},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Paginated invoice list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"page":{"type":"integer","exclusiveMinimum":0},"pageSize":{"type":"integer","exclusiveMinimum":0},"total":{"type":"integer","minimum":0},"pages":{"type":"integer","exclusiveMinimum":0},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"},"paidTotal":{"type":"string"},"refundedTotal":{"type":"string"},"currency":{"type":"string"},"type":{"type":"string"},"createdAt":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"payDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"order":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":true},{"type":"null"}]}},"required":["id","number","status","total","paidTotal","currency"],"additionalProperties":true}}},"required":["ok","items"],"additionalProperties":true},"example":{"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}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.invoices.read"]},{"BearerAuth":["billing.invoices.read"]}],"operationId":"listInvoices"}},"/v1/billing/invoices/unpaid-total":{"get":{"tags":["Billing"],"summary":"Check unpaid total","description":"Returns the current unpaid amount across customer invoices. This is useful for dashboard badges and automation that should pause when debt exists.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Current unpaid invoice summary.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"data":{"type":"object","properties":{"unpaidTotal":{"type":"number"},"currency":{"type":"string"}},"required":["unpaidTotal","currency"],"additionalProperties":true}},"required":["ok","data"],"additionalProperties":true},"example":{"ok":true,"data":{"unpaidTotal":0,"currency":"EUR"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.unpaid_total.read"]},{"BearerAuth":["billing.unpaid_total.read"]}],"operationId":"billingUnpaidTotal"}},"/v1/billing/orders":{"get":{"tags":["Billing"],"summary":"Browse orders","description":"Returns paginated customer orders and supports filtering by order or payment status for reporting and customer portals.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"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.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page_size","in":"query","required":false,"description":"Deprecated compatibility alias for limit; values must match when supplied together.","schema":{"type":"integer"},"deprecated":true},{"name":"pageSize","in":"query","required":false,"description":"Deprecated compatibility alias for limit; range 1–100, default 50.","schema":{"type":"integer"},"deprecated":true},{"name":"status","in":"query","required":false,"description":"Optional order status filter.","schema":{"type":"string"}},{"name":"paymentStatus","in":"query","required":false,"description":"Optional payment status filter.","schema":{"type":"string"}},{"name":"external_id","in":"query","required":false,"description":"Exact customer reference on an owned order item; applied before pagination.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Paginated order list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"page":{"type":"integer","exclusiveMinimum":0},"pageSize":{"type":"integer","exclusiveMinimum":0},"total":{"type":"integer","minimum":0},"pages":{"type":"integer","exclusiveMinimum":0},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"total":{"type":"string"},"paymentStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"paymentMethod":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"invoice":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"},"paidTotal":{"type":"string"},"refundedTotal":{"type":"string"},"currency":{"type":"string"},"type":{"type":"string"},"createdAt":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"payDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"order":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"additionalProperties":true},{"type":"null"}]}},"required":["id","number","status","total","paidTotal","currency"],"additionalProperties":true},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"variantId":{"anyOf":[{"type":"string"},{"type":"null"}]},"quantity":{"type":"integer"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","productId","variantId","quantity"],"additionalProperties":false}}},"required":["id","status","currency","total"],"additionalProperties":true}}},"required":["ok","items"],"additionalProperties":true},"example":{"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"}}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.orders.read"]},{"BearerAuth":["billing.orders.read"]}],"operationId":"billingOrders"}},"/v1/billing/services":{"get":{"tags":["Billing"],"summary":"Browse billable services","description":"Returns the billing-facing service list. Use this endpoint when the main goal is commercial visibility rather than grouped customer dashboards.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"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.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page_size","in":"query","required":false,"description":"Deprecated compatibility alias for limit; values must match when supplied together.","schema":{"type":"integer"},"deprecated":true},{"name":"pageSize","in":"query","required":false,"description":"Deprecated compatibility alias for limit; range 1–100, default 50.","schema":{"type":"integer"},"deprecated":true},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Paginated billing service list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"page":{"type":"integer","exclusiveMinimum":0},"pageSize":{"type":"integer","exclusiveMinimum":0},"total":{"type":"integer","minimum":0},"pages":{"type":"integer","exclusiveMinimum":0},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"activationAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingUnit":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingCount":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"object","additionalProperties":{"type":"string"}},"provisioning_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"meta":{"anyOf":[{"type":"object","properties":{"serviceType":{"type":"string"},"includedByDefault":{"type":"boolean"},"instanceIndex":{"type":"number"}},"additionalProperties":false},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"counts":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"group_by":{"type":"string","const":"type","enum":["type"]},"groups":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"activationAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingUnit":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingCount":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"object","additionalProperties":{"type":"string"}},"provisioning_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"meta":{"anyOf":[{"type":"object","properties":{"serviceType":{"type":"string"},"includedByDefault":{"type":"boolean"},"instanceIndex":{"type":"number"}},"additionalProperties":false},{"type":"null"}]}},"required":["id"],"additionalProperties":true}}}},"required":["ok","items"],"additionalProperties":true},"example":{"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"}}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]}],"operationId":"billingServices"}},"/v1/billing/products":{"get":{"tags":["Billing"],"summary":"Browse product catalog","description":"Returns product catalog entries that can be used for storefront search, quoting, and pre-checkout selection flows.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"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.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page_size","in":"query","required":false,"description":"Deprecated compatibility alias for limit; values must match when supplied together.","schema":{"type":"integer"},"deprecated":true},{"name":"pageSize","in":"query","required":false,"description":"Deprecated compatibility alias for limit; range 1–100, default 50.","schema":{"type":"integer"},"deprecated":true},{"name":"category","in":"query","required":false,"description":"Optional category filter.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional free-text search query.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Paginated product list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"pages":{"type":"number"},"next_offset":{"anyOf":[{"type":"number"},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"sku":{"type":"string"},"serviceType":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}},"addons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"qty":{"type":"number"},"price":{"type":"string"},"unitPrice":{"anyOf":[{"type":"string"},{"type":"number"}]},"setupFee":{"anyOf":[{"type":"string"},{"type":"number"}]},"chargeType":{"type":"string"},"billedSeparately":{"type":"boolean"}},"required":["key"],"additionalProperties":true}},"billingOptions":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"currency":{"type":"string"},"price":{"type":"string"},"setupFee":{"type":"string"}},"required":["unit","count","currency","price"],"additionalProperties":true}}},"required":["id","productId","sku","serviceType","attributes","addons","billingOptions"],"additionalProperties":true}}},"required":["id","name","category","variants"],"additionalProperties":true}}},"required":["ok","items"],"additionalProperties":true,"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"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"}]}]}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"billingProducts"}},"/v1/billing/products/{productId}/variants/{variantId}/order-options":{"get":{"tags":["Billing"],"summary":"Discover product order options","description":"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.","parameters":[{"name":"productId","in":"path","required":true,"description":"Product UUID from the catalog.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"Variant UUID belonging to this product.","schema":{"type":"string"}},{"name":"region","in":"query","required":false,"description":"Region code from GET /v1/regions, for example nl or pt. Case-insensitive.","schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"Pricing currency, default EUR.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Product-specific location and OS options. A catalog outage returns an error, never fallback options.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"productId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"supported":{"type":"boolean"},"capacityVerified":{"type":"boolean"},"purchase":{"type":"object","properties":{"draft_order":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false},"atomic_deploy":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"type":"boolean"},"eligible":{"type":"boolean"},"requires_approval":{"type":"boolean"},"payment_required":{"type":"boolean"},"payment_methods":{"type":"array","items":{"type":"string","const":"balance","enum":["balance"]}},"partial_payment":{"type":"boolean"},"idempotency_required":{"type":"boolean"},"permitted":{"type":"boolean"}},"required":["implemented","enabled","eligible","requires_approval","payment_required","payment_methods","partial_payment","idempotency_required"],"additionalProperties":false}},"required":["draft_order","atomic_deploy"],"additionalProperties":false},"requirements":{"type":"object","properties":{"atomic_deploy":{"type":"object","additionalProperties":{"type":"object","properties":{"required":{"type":"boolean"},"type":{"type":"string","enum":["string","integer","number","array"]},"format":{"type":"string","enum":["hostname","domain","uuid","ipv4"]},"source":{"type":"string","pattern":"^\\/v1\\/"},"min_items":{"type":"integer","exclusiveMinimum":0},"max_items":{"type":"integer","exclusiveMinimum":0},"allowed_values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]},"maxItems":100}},"required":["required","type"],"additionalProperties":false}}},"required":["atomic_deploy"],"additionalProperties":false},"reason":{"type":"string","enum":["unsupported_product_type","unsupported_location"]},"serviceType":{"anyOf":[{"type":"string"},{"type":"null"}]},"requiredFields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"format":{"type":"string","enum":["hostname","domain","uuid"]},"minLength":{"type":"number"}},"required":["field","label","description"],"additionalProperties":false}},"conditionalRequiredFields":{"type":"array","items":{"type":"object","properties":{"whenField":{"type":"string"},"whenEquals":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"format":{"type":"string","enum":["hostname","domain","uuid"]},"minLength":{"type":"number"}},"required":["field","label","description"],"additionalProperties":false}}},"required":["whenField","whenEquals","fields"],"additionalProperties":false}},"optionalFields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"description":{"type":"string"},"format":{"type":"string"}},"required":["field","description","format"],"additionalProperties":false}},"defaults":{"type":"object","properties":{"location":{"type":"string"}},"additionalProperties":false},"addons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"chargeType":{"type":"string"},"maxQty":{"anyOf":[{"type":"number"},{"type":"null"}]},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"speedGbps":{"anyOf":[{"type":"number"},{"type":"null"}]},"billingOptions":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"currency":{"type":"string"},"price":{"anyOf":[{"type":"string"},{"type":"number"}]},"setupFee":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}},"required":["unit","count","currency","price"],"additionalProperties":false}}},"required":["key","name","chargeType","maxQty","kind","speedGbps","billingOptions"],"additionalProperties":false}},"billingOptions":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"currency":{"type":"string"},"price":{"anyOf":[{"type":"string"},{"type":"number"}]},"setupFee":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}},"required":["unit","count","currency","price"],"additionalProperties":false}},"currency":{"type":"string","enum":["EUR","USD"]},"quoteUrl":{"type":"string","const":"/v1/billing/orders/preview","enum":["/v1/billing/orders/preview"]},"orderUrl":{"type":"string","const":"/v1/billing/orders/draft","enum":["/v1/billing/orders/draft"]},"checkoutEnabled":{"type":"boolean"},"pricingMode":{"type":"string","enum":["configured","domain_quote"]},"connectivity":{"type":"object","properties":{"physicalCapacityGbps":{"anyOf":[{"type":"number"},{"type":"null"}]},"defaultGbps":{"anyOf":[{"type":"number"},{"type":"null"}]},"options":{"type":"array","items":{"type":"object","properties":{"speedGbps":{"type":"number","exclusiveMinimum":0}},"required":["speedGbps"],"additionalProperties":false}}},"required":["physicalCapacityGbps","defaultGbps","options"],"additionalProperties":false},"ipv4":{"type":"object","properties":{"included":{"type":"integer","minimum":0},"maxAdditional":{"type":"integer","minimum":0}},"required":["included","maxAdditional"],"additionalProperties":false},"orderExpirationMinutes":{"type":"number","exclusiveMinimum":0},"tcpProxy":{"type":"object","properties":{"includedPorts":{"type":"integer","exclusiveMinimum":0},"maxPorts":{"type":"integer","exclusiveMinimum":0}},"required":["includedPorts","maxPorts"],"additionalProperties":false},"locations":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"configurationCode":{"type":"string"},"availableStock":{"type":"integer","minimum":0},"operatingSystems":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"id":{"type":"number","exclusiveMinimum":0},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"arch":{"anyOf":[{"type":"string"},{"type":"null"}]},"isDefault":{"type":"boolean"},"sshKeysSupported":{"type":"boolean"}},"required":["code","name","family","version","arch","isDefault"],"additionalProperties":false}}},"required":["code","name","operatingSystems"],"additionalProperties":false}}},"required":["ok","productId","variantId","supported","capacityVerified","requiredFields","locations"],"additionalProperties":false},"example":{"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}]}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"billingProductOrderOptions"}},"/v1/billing/transactions":{"get":{"tags":["Billing"],"summary":"Browse transactions","description":"Returns paginated financial transaction records for account history and payment auditing.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"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.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page_size","in":"query","required":false,"description":"Deprecated compatibility alias for limit; values must match when supplied together.","schema":{"type":"integer"},"deprecated":true},{"name":"pageSize","in":"query","required":false,"description":"Deprecated compatibility alias for limit; range 1–100, default 50.","schema":{"type":"integer"},"deprecated":true},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Paginated transaction list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"pages":{"type":"number"},"next_offset":{"anyOf":[{"type":"number"},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string"},"status":{"type":"string"},"type":{"type":"string"},"currency":{"type":"string"},"amountIn":{"type":"string"},"amountOut":{"type":"string"},"fee":{"type":"string"},"gateway":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"meta":{"anyOf":[{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}},{"type":"null"}]}},"required":["id","createdAt","status","type","currency","amountIn","amountOut","fee","gateway","invoiceId","meta"],"additionalProperties":true}}},"required":["ok","items"],"additionalProperties":true,"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"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}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.transactions.read"]},{"BearerAuth":["billing.transactions.read"]}],"operationId":"billingTransactions"}},"/v1/billing/orders/preview":{"post":{"tags":["Billing"],"summary":"Preview order total","description":"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.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"idempotency_key":{"type":"string","minLength":1,"maxLength":200},"currency":{"type":"string","enum":["EUR","USD"]},"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":{"description":"Order preview with calculated totals.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"currency":{"type":"string","maxLength":3,"minLength":3},"reserved":{"type":"boolean","const":false,"enum":[false]},"subtotal":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"tax":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"breakdown":{"type":"object","properties":{"base_price":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"addons":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"setup_fee":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"tax":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"}},"required":["base_price","addons","setup_fee","tax","total"],"additionalProperties":false},"quote":{"type":"object","properties":{"id":{"type":"string","pattern":"^quo_[a-f0-9]{64}$"},"currency":{"type":"string","maxLength":3,"minLength":3},"total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"breakdown":{"type":"object","properties":{"base_price":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"addons":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"setup_fee":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"tax":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"}},"required":["base_price","addons","setup_fee","tax","total"],"additionalProperties":false},"guaranteed":{"type":"boolean","const":false,"enum":[false]},"pricing_revision":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"recommended_max_total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"}},"required":["id","currency","total","breakdown","guaranteed","pricing_revision","recommended_max_total"],"additionalProperties":false},"links":{"type":"object","properties":{"deploy":{"type":"string","pattern":"^\\/v1\\/deploy\\/[A-Za-z0-9._%/-]+$"}},"required":["deploy"],"additionalProperties":false},"items":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string","maxLength":500},"sku":{"type":"string","maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":100},"billing":{"type":"object","properties":{"unit":{"type":"string","maxLength":20},"count":{"type":"integer","minimum":1,"maximum":120}},"required":["unit","count"],"additionalProperties":false},"unitPrice":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"setupFee":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"subtotal":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"addons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","maxLength":120},"name":{"type":"string","maxLength":500},"qty":{"type":"integer","minimum":1,"maximum":100},"unitPrice":{"anyOf":[{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},{"type":"number","minimum":0}]},"setupFee":{"anyOf":[{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},{"type":"number","minimum":0}]},"chargeType":{"type":"string","maxLength":40},"billedSeparately":{"type":"boolean"}},"required":["key","name","qty","unitPrice","setupFee","chargeType"],"additionalProperties":false},"maxItems":100}},"required":["productId","variantId","productName","sku","quantity","billing","unitPrice","setupFee","subtotal","addons"],"additionalProperties":false},"maxItems":50}},"required":["ok","currency","reserved","subtotal","tax","total","breakdown","items"],"additionalProperties":false},"example":{"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":[]}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"billingOrderPreview"}},"/v1/deploy/{region}/{productCode}/{variantCode}/quote":{"post":{"tags":["Deployments"],"summary":"Quote a configured product by code","description":"Accepts exactly the same simple or legacy body as deployment. Uses authoritative account currency, configuration, tax and add-on prices. Returns a price breakdown and reserved=false; creates no order, invoice, reservation or payment. No Idempotency-Key required. The quote object adds an opaque diagnostic id, guaranteed=false, currency, final total, breakdown, pricing_revision and recommended_max_total. Pass recommended_max_total as max_total to deployment. The revision fingerprints this priced cart; it is not a price lock, reservation or redeemable quote. A quote is optional and is not a stock or price guarantee.","parameters":[{"name":"region","in":"path","required":true,"description":"Eligible region, for example nl or pt. A single region is required.","schema":{"type":"string"}},{"name":"productCode","in":"path","required":true,"description":"Product family.","schema":{"type":"string","enum":["vps","dedicated","tcp-proxy","waf","license","webhosting","storage","dns","domain","other"]}},{"name":"variantCode","in":"path","required":true,"description":"Exact case-sensitive public SKU, for example 2G or PTV4-1. Never an internal inventory ID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"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},"userConfig":{"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},"maxTotal":{"type":"string","pattern":"^(0|[1-9]\\d{0,9})(\\.\\d{1,2})?$"}},"required":["billing"],"additionalProperties":false,"deprecated":true,"description":"Deprecated compatibility deployment shape. Prefer the canonical snake_case payload; no sunset date has been assigned."},{"type":"object","properties":{"billing_cycle":{"type":"string","enum":["monthly","quarterly","semi_annually","annually","biennially","triennially","hourly","daily","weekly","one_time"],"default":"monthly"},"hostname":{"type":"string","maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$"},"os":{"anyOf":[{"type":"string","minLength":1,"maxLength":160},{"type":"integer","exclusiveMinimum":0}]},"ssh_key_id":{"type":"string","format":"uuid"},"connectivity_gbps":{"type":"number","exclusiveMinimum":0,"maximum":100},"additional_ips":{"type":"integer","minimum":0,"maximum":100},"backend_ip":{"type":"string"},"ports":{"type":"array","items":{"type":"object","properties":{"listen":{"type":"integer","minimum":1,"maximum":65535},"backend":{"type":"integer","minimum":1,"maximum":65535}},"required":["listen","backend"],"additionalProperties":false},"minItems":1,"maxItems":100},"domain":{"type":"string","minLength":1,"maxLength":253},"license_ip":{"type":"string"},"parent_service_id":{"type":"string","format":"uuid"},"addons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"},"qty":{"type":"integer","minimum":1,"maximum":100}},"required":["key","qty"],"additionalProperties":false},"maxItems":50},"max_total":{"type":"string","pattern":"^(0|[1-9]\\d{0,9})(\\.\\d{1,2})?$"},"external_id":{"type":"string","minLength":1,"maxLength":120},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":120}}},"additionalProperties":false}],"example":{"billing_cycle":"monthly","hostname":"test","os":"debian-13","max_total":"25.00"},"description":"Simple fields: billing_cycle, hostname, os, owned ssh_key_id, dedicated connectivity_gbps/additional_ips, TCP backend_ip/ports, external_id/labels, max_total. Use discovered choices; dedicated OS accepts its exact code or numeric ID. Path fixes region. Legacy billing/userConfig/addons/maxTotal remains accepted; never mix both shapes. Ceilings include tax/setup/add-ons in account currency."}}}},"responses":{"200":{"description":"Validated price, breakdown and selected line items.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"currency":{"type":"string","maxLength":3,"minLength":3},"reserved":{"type":"boolean","const":false,"enum":[false]},"subtotal":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"tax":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"breakdown":{"type":"object","properties":{"base_price":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"addons":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"setup_fee":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"tax":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"}},"required":["base_price","addons","setup_fee","tax","total"],"additionalProperties":false},"quote":{"type":"object","properties":{"id":{"type":"string","pattern":"^quo_[a-f0-9]{64}$"},"currency":{"type":"string","maxLength":3,"minLength":3},"total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"breakdown":{"type":"object","properties":{"base_price":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"addons":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"setup_fee":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"tax":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"}},"required":["base_price","addons","setup_fee","tax","total"],"additionalProperties":false},"guaranteed":{"type":"boolean","const":false,"enum":[false]},"pricing_revision":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"recommended_max_total":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"}},"required":["id","currency","total","breakdown","guaranteed","pricing_revision","recommended_max_total"],"additionalProperties":false},"links":{"type":"object","properties":{"deploy":{"type":"string","pattern":"^\\/v1\\/deploy\\/[A-Za-z0-9._%/-]+$"}},"required":["deploy"],"additionalProperties":false},"items":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string","maxLength":500},"sku":{"type":"string","maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":100},"billing":{"type":"object","properties":{"unit":{"type":"string","maxLength":20},"count":{"type":"integer","minimum":1,"maximum":120}},"required":["unit","count"],"additionalProperties":false},"unitPrice":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"setupFee":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"subtotal":{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},"addons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","maxLength":120},"name":{"type":"string","maxLength":500},"qty":{"type":"integer","minimum":1,"maximum":100},"unitPrice":{"anyOf":[{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},{"type":"number","minimum":0}]},"setupFee":{"anyOf":[{"type":"string","pattern":"^\\d{1,20}(\\.\\d{1,10})?$"},{"type":"number","minimum":0}]},"chargeType":{"type":"string","maxLength":40},"billedSeparately":{"type":"boolean"}},"required":["key","name","qty","unitPrice","setupFee","chargeType"],"additionalProperties":false},"maxItems":100}},"required":["productId","variantId","productName","sku","quantity","billing","unitPrice","setupFee","subtotal","addons"],"additionalProperties":false},"maxItems":50}},"required":["ok","currency","reserved","subtotal","tax","total","breakdown","items"],"additionalProperties":false},"example":{"ok":true,"currency":"EUR","subtotal":"12.00","tax":"0.00","total":"12.00","reserved":false,"breakdown":{"base_price":"12.00","addons":"0.00","setup_fee":"0.00","tax":"0.00","total":"12.00"},"items":[{"productId":"00000000-0000-4000-8000-000000000001","variantId":"00000000-0000-4000-8000-000000000002","productName":"Example VPS","sku":"2G","quantity":1,"billing":{"unit":"MONTH","count":1},"unitPrice":"12","setupFee":"0","subtotal":"12","addons":[]}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.products.read"]},{"BearerAuth":["billing.products.read"]}],"operationId":"productVariantQuote"}},"/v1/operations":{"get":{"tags":["Integrations"],"summary":"Recover an operation by idempotency key","description":"Lookup is confined to the authenticated account and permitted operation kinds. Keys are scoped to the original credential, HTTP method and exact path. Supply method/path together and optionally credential_id to disambiguate a key reused across endpoints or credentials (409 operation_lookup_ambiguous). Only new tracked deployment/VPS/dedicated writes with a retained identity are recoverable. 404 operation_not_found does not prove the write never executed. Identities remain after terminal receipt retention (90 days by default); 410 operation_expired means the original receipt is no longer available. Pending/unknown receipts are retained for reconciliation. Never generate a new key to repeat an uncertain write.","parameters":[{"name":"idempotency_key","in":"query","required":true,"description":"Original Idempotency-Key; 8–128 letters, digits, dot, underscore, colon or dash.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$"}},{"name":"method","in":"query","required":false,"description":"Original HTTP method; supply with path.","schema":{"type":"string","enum":["POST","PUT","PATCH","DELETE"]}},{"name":"path","in":"query","required":false,"description":"Exact original /v1/ path without query string; supply with method.","schema":{"type":"string","maxLength":512,"pattern":"^\\/v1\\/[A-Za-z0-9/._~%:-]+$"}},{"name":"credential_id","in":"query","required":false,"description":"Original credential UUID, when needed for disambiguation.","schema":{"type":"string","format":"uuid"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Original operation receipt; owner and read scopes are checked.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false},"example":{"ok":true,"operation":{"id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","kind":"vps","action":"reboot","status":"succeeded","done":true,"progress":100,"stage":null,"created_at":"2026-10-01T00:00:00.000Z","updated_at":"2026-10-01T00:00:00.000Z","service_ids":["00000000-0000-4000-8000-000000000001"],"error":null,"result":{"service_id":"00000000-0000-4000-8000-000000000001"}},"links":{"operation":"/v1/operations/op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","service":"/v1/services/00000000-0000-4000-8000-000000000001"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]},{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]},{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"x-required-together":[["method","path"]],"operationId":"recoverOperation"}},"/v1/operations/{operationId}":{"get":{"tags":["Integrations"],"summary":"Read operation status","description":"Poll the opaque operation_id returned by supported wallet deployments and VPS/dedicated actions. Owner checks and the underlying read scope are enforced on every read. When durable_operations is enabled, new handles are stored independently of encryption keys and the first observed terminal outcome is immutable. Terminal receipts retain 90 days by default; pending/unknown receipts remain for reconciliation. Legacy encrypted handles remain readable but can be invalidated by encryption-key rotation. Deployment readiness respects historical activation; a service error alone is not proof of permanent provisioning failure. The canonical operation has status, done, progress, stage and optional typed result. Result is populated only on succeeded; failed/cancelled are terminal, unknown is nonterminal and is not success. Tracked writes accept x-bf-response-format: operation; the default response preserves legacy fields. DNSSEC and other untracked workflows retain their documented polling contracts. Client wait timeout never repeats/cancels a purchase.","parameters":[{"name":"operationId","in":"path","required":true,"description":"Opaque op_ token from the accepted response.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Unified status, safe progress and service IDs.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false},"example":{"ok":true,"operation":{"id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","kind":"vps","action":"reboot","status":"succeeded","done":true,"progress":100,"stage":null,"created_at":"2026-10-01T00:00:00.000Z","updated_at":"2026-10-01T00:00:00.000Z","service_ids":["00000000-0000-4000-8000-000000000001"],"error":null}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]},{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]},{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"getOperation"}},"/v1/services/{serviceId}/metadata":{"patch":{"tags":["Integrations"],"summary":"Replace customer integration metadata","description":"Replaces only this owned service’s external_id and labels; omitted fields are cleared. Does not change hardware, price, credentials or lifecycle. Up to 20 bounded labels. Do not store secrets in labels. Searches use external_id or label=key=value.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":120},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":120}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Saved customer reference and labels.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"service_id":{"type":"string","format":"uuid"},"external_id":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":120}}},"required":["ok","service_id","external_id","labels"],"additionalProperties":false},"example":{"ok":true,"service_id":"00000000-0000-4000-8000-000000000001","external_id":"example-vps-1","labels":{"environment":"test"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.write"]},{"BearerAuth":["billing.services.write"]}],"operationId":"serviceMetadataUpdate"}},"/v1/webhooks":{"get":{"tags":["Integrations"],"summary":"List webhook endpoints","description":"Owned endpoints without signing secrets. Maximum five per account; feature must be enabled for this environment.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Owned webhook endpoints.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["invoice.paid","service.ready","service.suspended","service.terminated","operation.failed","operation.succeeded","operation.cancelled","invoice.created","invoice.overdue","service.provisioning","service.expiring","operation.started","backup.started","backup.completed","backup.failed","snapshot.created","snapshot.failed","dns.changed","service.power_changed","domain.verification_required","domain.renewal_pending","domain.renewed","domain.transfer_updated"]},"maxItems":23},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","url","events","enabled","createdAt"],"additionalProperties":false},"maxItems":5}},"required":["ok","items"],"additionalProperties":false},"example":{"ok":true,"items":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["webhooks.read"]},{"BearerAuth":["webhooks.read"]}],"operationId":"listWebhooks"},"post":{"tags":["Integrations"],"summary":"Register a signed webhook","description":"HTTPS port 443, public IPv4 destinations only. Verified TLS, pinned DNS, no redirects. Events: invoice.paid, service.ready, service.suspended, service.terminated and operation.failed (Billing provisioning-job failures, not all power/reinstall failures). No historical backfill. Sensitive signing_secret is returned on creation or identical retry while the endpoint exists: never log it or send it to AI. At-least-once delivery: verify raw-body HMAC and timestamp, deduplicate event IDs, return 2xx promptly. Off by default until migration and worker deployment.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable action key: 8–128 letters, digits, dot, underscore, colon or hyphen. Reuse the same key and payload on retries; inspect task state after a timeout.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["invoice.paid","service.ready","service.suspended","service.terminated","operation.failed","operation.succeeded","operation.cancelled","invoice.created","invoice.overdue","service.provisioning","service.expiring","operation.started","backup.started","backup.completed","backup.failed","snapshot.created","snapshot.failed","dns.changed","service.power_changed","domain.verification_required","domain.renewal_pending","domain.renewed","domain.transfer_updated"]},"minItems":1,"maxItems":23}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"201":{"description":"New endpoint and private signing secret.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["invoice.paid","service.ready","service.suspended","service.terminated","operation.failed","operation.succeeded","operation.cancelled","invoice.created","invoice.overdue","service.provisioning","service.expiring","operation.started","backup.started","backup.completed","backup.failed","snapshot.created","snapshot.failed","dns.changed","service.power_changed","domain.verification_required","domain.renewal_pending","domain.renewed","domain.transfer_updated"]},"maxItems":23},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","url","events","enabled","createdAt"],"additionalProperties":false},"signing_secret":{"type":"string","pattern":"^whsec_[A-Za-z0-9_-]{43}$"}},"required":["ok","item","signing_secret"],"additionalProperties":false},"example":{"ok":true,"item":{"id":"00000000-0000-4000-8000-000000000001","url":"https://example.com/hooks","events":["invoice.paid"],"enabled":true,"createdAt":"2026-10-01T00:00:00.000Z"},"signing_secret":"whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["webhooks.write"]},{"BearerAuth":["webhooks.write"]}],"operationId":"webhookCreate"}},"/v1/version":{"get":{"tags":["Integrations"],"summary":"Read API contract revision","description":"Authenticated discovery. release is a configured public release label or null, not an internal image or provider identifier. A contract revision is not proof of product availability.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"API version and contract revision.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"api_version":{"type":"string","const":"1","enum":["1"]},"contract_revision":{"type":"string","const":"2026-10-07.1","enum":["2026-10-07.1"]},"release":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$"},{"type":"null"}]},"deployment":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$"},{"type":"null"}]},"released_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["ok","api_version","contract_revision","release","deployment","released_at"],"additionalProperties":false},"example":{"ok":true,"api_version":"1","contract_revision":"2026-10-07.1","release":null,"deployment":null,"released_at":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":[]},{"BearerAuth":[]}],"operationId":"apiVersion"}},"/v1/capabilities":{"get":{"tags":["Integrations"],"summary":"Discover capabilities and effective permissions","description":"Distinguishes implemented support, environment enabled state and effective key permissions. enabled=null and availability=unconfirmed mean the backend could not confirm a gate, not that it is disabled. partial=true indicates incomplete discovery. Does not guarantee region inventory, provider health or order approval. Networking and generic metrics are reported not_implemented until supported.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Capability gates and key permissions.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"contract_revision":{"type":"string","const":"2026-10-07.1","enum":["2026-10-07.1"]},"dependency_revision":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9._-]{1,80}$"},{"type":"null"}]},"partial":{"type":"boolean"},"features":{"type":"object","additionalProperties":{"type":"object","properties":{"implemented":{"type":"boolean"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"permitted":{"type":"boolean"},"availability":{"type":"string","enum":["enabled","disabled","unconfirmed","not_implemented"]}},"required":["implemented","enabled","permitted","availability"],"additionalProperties":false}},"operation_policy":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"string","enum":["deployment","vps","dedicated"]}},"terminal_retention_days":{"type":"integer","exclusiveMinimum":0},"pending_retention":{"type":"string","const":"until_reconciled","enum":["until_reconciled"]},"lookup_identity_retention":{"type":"string","const":"indefinite","enum":["indefinite"]},"key_scope":{"type":"string","const":"account_credential_method_path","enum":["account_credential_method_path"]},"response_header":{"type":"string","const":"x-bf-response-format","enum":["x-bf-response-format"]},"response_value":{"type":"string","const":"operation","enum":["operation"]}},"required":["kinds","terminal_retention_days","pending_retention","lookup_identity_retention","key_scope","response_header","response_value"],"additionalProperties":false}},"required":["ok","contract_revision","dependency_revision","partial","features"],"additionalProperties":false},"example":{"ok":true,"contract_revision":"2026-10-07.1","dependency_revision":null,"partial":true,"features":{"webhooks":{"implemented":true,"enabled":null,"permitted":true,"availability":"unconfirmed"},"private_networks":{"implemented":false,"enabled":false,"permitted":false,"availability":"not_implemented"}}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":[]},{"BearerAuth":[]}],"operationId":"apiCapabilities"}},"/v1/audit/events":{"get":{"tags":["Integrations"],"summary":"Read account audit history","description":"Default view=requests preserves request history. view=activity merges durable API/MCP actions and Billing business events with actor/action/resource/status filters. Activity partial=true means a history source was unavailable; available_sources lists confirmed sources. Reuse opaque cursors with the same filters; ownership is always enforced. Acceptance is not provider completion. No passwords, tokens, private keys or webhook secrets. Activity source_ip follows the existing privacy masking policy.","parameters":[{"name":"limit","in":"query","description":"Maximum items, default 50 (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"view","in":"query","required":false,"description":"History view.","schema":{"type":"string","enum":["requests","activity"]}},{"name":"cursor","in":"query","required":false,"description":"Reuse next_cursor exactly with the same owner and filters.","schema":{"type":"string"}},{"name":"method","in":"query","required":false,"description":"HTTP method; request view only.","schema":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]}},{"name":"actor_type","in":"query","required":false,"description":"Verified actor category.","schema":{"type":"string","enum":["user","api_key","oauth_app","hosted_mcp","local_mcp","support","system","unknown"]}},{"name":"actor_id","in":"query","required":false,"description":"Exact verified actor UUID.","schema":{"type":"string"}},{"name":"action","in":"query","required":false,"description":"Semantic action, for example vps.reinstall.","schema":{"type":"string"}},{"name":"resource_type","in":"query","required":false,"description":"Resource category.","schema":{"type":"string"}},{"name":"resource_id","in":"query","required":false,"description":"Exact resource identity.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Action phase.","schema":{"type":"string","enum":["requested","accepted","rejected","unknown","succeeded","failed","cancelled","committed"]}},{"name":"request_id","in":"query","required":false,"description":"Exact request UUID.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Inclusive ISO 8601 timestamp.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Inclusive ISO 8601 timestamp.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Filtered history and next_cursor.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"next_cursor":{"anyOf":[{"type":"string","pattern":"^\\d+$"},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d+$"},"occurred_at":{"type":"string","format":"date-time"},"actor":{"type":"object","properties":{"type":{"type":"string","const":"api_key","enum":["api_key"]},"api_key_prefix":{"type":"string","maxLength":32}},"required":["type","api_key_prefix"],"additionalProperties":false},"type":{"type":"string","const":"api_request","enum":["api_request"]},"method":{"type":"string","maxLength":10},"path":{"type":"string","maxLength":300},"http_status":{"type":"integer","minimum":100,"maximum":599},"request_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"outcome":{"type":"string","enum":["accepted","rejected","unknown"]}},"required":["id","occurred_at","actor","type","method","path","http_status","request_id","outcome"],"additionalProperties":false},"maxItems":100}},"required":["ok","next_cursor","items"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"partial":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string","maxLength":800},{"type":"null"}]},"available_sources":{"type":"array","items":{"type":"string","enum":["api","billing"]}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key","oauth_app","hosted_mcp","local_mcp","support","system","unknown"]},"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["type","id"],"additionalProperties":false},"action":{"type":"string","maxLength":300},"resource_type":{"type":"string","maxLength":40},"resource_id":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}]},"request_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"idempotency_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}]},"source_ip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"status":{"type":"string","enum":["requested","accepted","rejected","unknown","succeeded","failed","cancelled","committed"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","actor","action","resource_type","resource_id","request_id","idempotency_key","source_ip","status","created_at"],"additionalProperties":false},"maxItems":100}},"required":["ok","partial","next_cursor","available_sources","items"],"additionalProperties":false}]},"example":{"ok":true,"next_cursor":null,"items":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["audit.read"]},{"BearerAuth":["audit.read"]}],"operationId":"auditEvents"}},"/v1/webhooks/{id}/test":{"post":{"tags":["Integrations"],"summary":"Queue a signed webhook test","description":"Queues a synthetic webhook.test event through the normal delivery worker. HTTP 202 means queued, not delivered. Read delivery history to check the result. Enabled owned endpoints only; one new test per endpoint per minute. Idempotency-Key is required; identical retries return the same delivery. Empty request body. Requires webhook_management capability.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned endpoint UUID.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable action key: 8–128 letters, digits, dot, underscore, colon or hyphen. Reuse the same key and payload on retries; inspect task state after a timeout.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"202":{"description":"Test event and delivery IDs.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"endpoint_id":{"type":"string","format":"uuid"},"delivery_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"pending","enum":["pending"]}},"required":["ok","endpoint_id","delivery_id","event_id","status"],"additionalProperties":false},"example":{"ok":true,"endpoint_id":"00000000-0000-4000-8000-000000000001","delivery_id":"00000000-0000-4000-8000-000000000002","event_id":"00000000-0000-4000-8000-000000000002","status":"pending"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["webhooks.write"]},{"BearerAuth":["webhooks.write"]}],"operationId":"webhookTest"}},"/v1/webhooks/{id}/rotate-secret":{"post":{"tags":["Integrations"],"summary":"Rotate webhook signing secret","description":"Replaces the signing secret for an owned endpoint immediately. An already in-flight delivery may still use the old secret; accept both briefly at your receiver. Idempotency-Key is required. Identical retries return the same secret for 24 hours unless a subsequent rotation superseded it; superseded or expired keys never rotate again. Sensitive signing_secret: never log or send it to AI. Empty request body. Requires webhook_management capability.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned endpoint UUID.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable action key: 8–128 letters, digits, dot, underscore, colon or hyphen. Reuse the same key and payload on retries; inspect task state after a timeout.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"New private signing secret.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"endpoint_id":{"type":"string","format":"uuid"},"signing_secret":{"type":"string","pattern":"^whsec_[A-Za-z0-9_-]{43}$"},"rotated_at":{"type":"string","format":"date-time"}},"required":["ok","endpoint_id","signing_secret","rotated_at"],"additionalProperties":false},"example":{"ok":true,"endpoint_id":"00000000-0000-4000-8000-000000000001","signing_secret":"whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","rotated_at":"2026-10-01T00:00:00.000Z"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["webhooks.write"]},{"BearerAuth":["webhooks.write"]}],"operationId":"webhookRotateSecret"}},"/v1/webhooks/{id}":{"patch":{"tags":["Integrations"],"summary":"Enable or pause webhook deliveries","description":"Pauses new and queued deliveries; an in-flight attempt may finish. Re-enable resumes pending deliveries.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned endpoint UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["invoice.paid","service.ready","service.suspended","service.terminated","operation.failed","operation.succeeded","operation.cancelled","invoice.created","invoice.overdue","service.provisioning","service.expiring","operation.started","backup.started","backup.completed","backup.failed","snapshot.created","snapshot.failed","dns.changed","service.power_changed","domain.verification_required","domain.renewal_pending","domain.renewed","domain.transfer_updated"]},"maxItems":23},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","url","events","enabled","createdAt"],"additionalProperties":false}},"required":["ok","item"],"additionalProperties":false},"example":{"ok":true,"item":{"id":"00000000-0000-4000-8000-000000000001","url":"https://example.com/hooks","events":["invoice.paid"],"enabled":false,"createdAt":"2026-10-01T00:00:00.000Z"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["webhooks.write"]},{"BearerAuth":["webhooks.write"]}],"operationId":"webhookUpdate"},"delete":{"tags":["Integrations"],"summary":"Delete a webhook endpoint","description":"Deletes the endpoint and its delivery history. An in-flight attempt may finish. Use a new retry key for an intentional replacement.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned endpoint UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Endpoint deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["webhooks.write"]},{"BearerAuth":["webhooks.write"]}],"operationId":"webhookDelete"}},"/v1/webhooks/{id}/deliveries":{"get":{"tags":["Integrations"],"summary":"Read webhook delivery history","description":"Owned delivery results, no response bodies or signing secrets. Delivered records retain 30 days, failed records 90 days. Paused pending events remain until deletion. Up to 12 attempts with exponential backoff capped at six hours.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned endpoint UUID.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum items, default 50 (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Start offset, default 0. Use next_offset from the response; null means finished. This contract has no page or pageSize fields.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Delivery attempts and next_offset.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"next_offset":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer","minimum":0},"lastHttpStatus":{"anyOf":[{"type":"integer"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"deliveredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"payload":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"anyOf":[{"type":"string","enum":["invoice.paid","service.ready","service.suspended","service.terminated","operation.failed","operation.succeeded","operation.cancelled","invoice.created","invoice.overdue","service.provisioning","service.expiring","operation.started","backup.started","backup.completed","backup.failed","snapshot.created","snapshot.failed","dns.changed","service.power_changed","domain.verification_required","domain.renewal_pending","domain.renewed","domain.transfer_updated"]},{"type":"string","const":"webhook.test","enum":["webhook.test"]}]},"created_at":{"type":"string","format":"date-time"},"schema_version":{"type":"number","const":1,"enum":[1]},"api_version":{"type":"string","const":"1","enum":["1"]},"data":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"service_id":{"type":"string","format":"uuid"},"invoice_id":{"type":"string","format":"uuid"},"endpoint_id":{"type":"string","format":"uuid"},"zone_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"zone_name":{"type":"string","maxLength":253},"change_id":{"type":"string","format":"uuid"},"action":{"type":"string","maxLength":64},"due_at":{"type":"string","format":"date-time"},"status":{"type":"string","maxLength":40},"currency":{"type":"string","maxLength":3,"minLength":3},"total":{"type":"string","maxLength":50},"operation_type":{"type":"string","pattern":"^[a-z_-]{1,40}$"},"code":{"type":"string","const":"operation_failed","enum":["operation_failed"]},"operation_id":{"type":"string","maxLength":80},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50}},"additionalProperties":false}},"required":["id","type","created_at","data"],"additionalProperties":false}},"required":["id","eventId","status","attempts","lastHttpStatus","createdAt","deliveredAt","payload"],"additionalProperties":false},"maxItems":100}},"required":["ok","next_offset","items"],"additionalProperties":false},"example":{"ok":true,"items":[],"next_offset":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["webhooks.read"]},{"BearerAuth":["webhooks.read"]}],"operationId":"webhookDeliveries"}},"/v1/webhooks/{id}/deliveries/{deliveryId}/retry":{"post":{"tags":["Integrations"],"summary":"Retry an exhausted delivery","description":"Only failed deliveries on your enabled endpoint can be retried. Pending/leased/successful events cannot be replayed; repeating this request returns delivery_not_retryable. Event ID is preserved.","parameters":[{"name":"id","in":"path","required":true,"description":"Owned endpoint UUID.","schema":{"type":"string"}},{"name":"deliveryId","in":"path","required":true,"description":"Failed delivery UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Delivery requeued.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"delivery_id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"pending","enum":["pending"]}},"required":["ok","delivery_id","status"],"additionalProperties":false},"example":{"ok":true,"delivery_id":"00000000-0000-4000-8000-000000000002","status":"pending"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["webhooks.write"]},{"BearerAuth":["webhooks.write"]}],"operationId":"webhookRetry"}},"/v1/deploy/{region}/{productCode}/{variantCode}":{"post":{"tags":["Deployments"],"summary":"Deploy product variant from wallet","description":"One call validates a public VPS, managed dedicated, TCP proxy, Website Protection or software-license variant, creates its order/invoice, charges the full final order amount to the account balance and queues normal provisioning. Insufficient funds returns HTTP 402 insufficient_credit with no committed order/payment. Uses account billing currency and authoritative prices including tax, setup and add-ons. max_total is an optional decimal-string spending ceiling in that currency. Requires both scopes. Idempotency-Key is required; reuse identical arguments after interruption. Never charges a card or tops up the wallet. Acceptance is not a ready server: inspect returned serviceIds. Dedicated admin approvals, inventory and license rollout gates still apply. Domains/free products are not supported by this convenience endpoint; legacy unpaid checkout/payment remain unchanged.","parameters":[{"name":"region","in":"path","required":true,"description":"Region code, for example nl or pt.","schema":{"type":"string"}},{"name":"productCode","in":"path","required":true,"description":"Catalog product_code: vps, dedicated, tcp-proxy, waf or license.","schema":{"type":"string"}},{"name":"variantCode","in":"path","required":true,"description":"Exact public catalog variant_code/SKU, for example 2G or PTV4-1.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable retry key, 8–128 characters. Never replace it after an uncertain response.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"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},"userConfig":{"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},"maxTotal":{"type":"string","pattern":"^(0|[1-9]\\d{0,9})(\\.\\d{1,2})?$"}},"required":["billing"],"additionalProperties":false,"deprecated":true,"description":"Deprecated compatibility deployment shape. Prefer the canonical snake_case payload; no sunset date has been assigned."},{"type":"object","properties":{"billing_cycle":{"type":"string","enum":["monthly","quarterly","semi_annually","annually","biennially","triennially","hourly","daily","weekly","one_time"],"default":"monthly"},"hostname":{"type":"string","maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$"},"os":{"anyOf":[{"type":"string","minLength":1,"maxLength":160},{"type":"integer","exclusiveMinimum":0}]},"ssh_key_id":{"type":"string","format":"uuid"},"connectivity_gbps":{"type":"number","exclusiveMinimum":0,"maximum":100},"additional_ips":{"type":"integer","minimum":0,"maximum":100},"backend_ip":{"type":"string"},"ports":{"type":"array","items":{"type":"object","properties":{"listen":{"type":"integer","minimum":1,"maximum":65535},"backend":{"type":"integer","minimum":1,"maximum":65535}},"required":["listen","backend"],"additionalProperties":false},"minItems":1,"maxItems":100},"domain":{"type":"string","minLength":1,"maxLength":253},"license_ip":{"type":"string"},"parent_service_id":{"type":"string","format":"uuid"},"addons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9_.:-]+$"},"qty":{"type":"integer","minimum":1,"maximum":100}},"required":["key","qty"],"additionalProperties":false},"maxItems":50},"max_total":{"type":"string","pattern":"^(0|[1-9]\\d{0,9})(\\.\\d{1,2})?$"},"external_id":{"type":"string","minLength":1,"maxLength":120},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":120}}},"additionalProperties":false}],"example":{"billing_cycle":"monthly","hostname":"test","os":"debian-13","max_total":"25.00"},"description":"Simple fields: billing_cycle, hostname, os, owned ssh_key_id, dedicated connectivity_gbps/additional_ips, TCP backend_ip/ports, external_id/labels, max_total. Use discovered choices; dedicated OS accepts its exact code or numeric ID. Path fixes region. Legacy billing/userConfig/addons/maxTotal remains accepted; never mix both shapes. Ceilings include tax/setup/add-ons in account currency."}}}},"responses":{"200":{"description":"Fully paid order with asynchronous provisioning queued.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"orderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoiceId":{"type":"string"},"invoiceNumber":{"type":"string"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"},"paidTotal":{"type":"string"},"currency":{"type":"string"},"createdAt":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"payDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"refundedTotal":{"type":"string"}},"required":["id","number","status","total","paidTotal","currency"],"additionalProperties":true},"total":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string"},"paymentStatus":{"type":"string"},"serviceIds":{"type":"array","items":{"type":"string"}},"message":{"type":"string"},"deploymentStatusUrl":{"type":"string"},"applied":{"type":"boolean"},"payNow":{"type":"string"},"paidNow":{"type":"string"},"fullyPaid":{"type":"boolean"},"provisioning":{"type":"string"},"operation_id":{"type":"string"},"operation_url":{"type":"string"}},"required":["ok","paidNow","fullyPaid","provisioning"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"orderId":"00000000-0000-4000-8000-000000000001","invoiceId":"00000000-0000-4000-8000-000000000002","invoiceNumber":"INV-EXAMPLE-000001","total":"100.00","currency":"EUR","status":"paid","paidNow":"100.00","fullyPaid":true,"serviceIds":["00000000-0000-4000-8000-000000000003"],"provisioning":"queued","operation_id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","operation_url":"/v1/operations/op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.order.create","billing.invoice.pay"]},{"BearerAuth":["billing.order.create","billing.invoice.pay"]}],"operationId":"productVariantDeploy"}},"/v1/billing/orders/draft":{"post":{"tags":["Billing"],"summary":"Start draft order","description":"Creates a draft order from one or more items so you can continue into invoice creation and payment.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idempotency_key":{"type":"string","minLength":1,"maxLength":200},"currency":{"type":"string","enum":["EUR","USD"]},"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":{"description":"Created draft order and related billing payload.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"orderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoiceId":{"type":"string"},"invoiceNumber":{"type":"string"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"},"paidTotal":{"type":"string"},"currency":{"type":"string"},"createdAt":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"payDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"refundedTotal":{"type":"string"}},"required":["id","number","status","total","paidTotal","currency"],"additionalProperties":true},"total":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string"},"paymentStatus":{"type":"string"},"serviceIds":{"type":"array","items":{"type":"string"}},"message":{"type":"string"},"deploymentStatusUrl":{"type":"string"},"applied":{"type":"boolean"},"payNow":{"type":"string"}},"required":["ok"],"additionalProperties":true},"example":{"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"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.order.create"]},{"BearerAuth":["billing.order.create"]}],"operationId":"billingOrderDraft"}},"/v1/billing/invoices/{id}/pay":{"post":{"tags":["Billing"],"summary":"Pay invoice from wallet","description":"Attempts to settle the target invoice using account balance. This is the customer API path for balance-driven payment automation.","parameters":[{"name":"id","in":"path","required":true,"description":"Invoice UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Invoice payment result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"paidNow":{"type":"string"},"partial":{"type":"boolean"},"fullyPaid":{"type":"boolean"},"invoiceId":{"type":"string"},"orderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"meta":{"type":"object","properties":{"createdServices":{"type":"number"},"renewedServices":{"type":"number"},"createdServiceIds":{"type":"array","items":{"type":"string"}},"provisioning":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true}},"required":["ok","paidNow","partial","fullyPaid","invoiceId","orderId","status","meta"],"additionalProperties":true},"example":{"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}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.invoice.pay"]},{"BearerAuth":["billing.invoice.pay"]}],"operationId":"payInvoice"}},"/v1/services":{"get":{"tags":["Services"],"summary":"Browse services","description":"Returns customer service summaries with hostname and recorded region code. Region uses provider/migration metadata, falling back to original order location; use VPS status for the currently assigned region. Null means unavailable. Does not disclose internal node or cluster identifiers. Ownership, status, type, search, external_id and label filters are applied server-side before pagination and counts. The default is active plus suspended; historical states require an explicit status filter. group_by=type groups only the current page, not the complete inventory.","parameters":[{"name":"status","in":"query","required":false,"description":"Service lifecycle status; defaults to active and suspended when no status filter is supplied. Power state is separate.","schema":{"type":"string","enum":["active","suspended","terminated","provisioning","error","maintenance","all"]}},{"name":"type","in":"query","required":false,"description":"High-level normalized service family: vps, dedicated, webhosting, storage, dns, domain or other (comma-separated). Distinct from catalog product_code: tcp-proxy and license map to other; waf maps to dns. Applied before pagination; use discovered product_code for purchasing.","schema":{"type":"string"}},{"name":"statuses","in":"query","required":false,"description":"Comma-separated lifecycle statuses, for example active,suspended. Use this or status, not both. Filtering and counts use service status, never runtime power state.","schema":{"type":"string"}},{"name":"types","in":"query","required":false,"description":"Comma-separated service types. Alias for type; do not supply both.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Search hostname, customer IPv4/IPv6, display name, product name, SKU or full service UUID; maximum 200 characters. Applied before pagination.","schema":{"type":"string"}},{"name":"external_id","in":"query","required":false,"description":"Exact customer integration reference; applied before pagination.","schema":{"type":"string"}},{"name":"label","in":"query","required":false,"description":"Exact metadata label match: key=value. Applied before pagination.","schema":{"type":"string"}},{"name":"include_counts","in":"query","required":false,"description":"Request counts only for selected statuses, with the same ownership, type and search filters. Omitted by default.","schema":{"type":"string","enum":["true","false"]}},{"name":"group_by","in":"query","required":false,"description":"Group the current page by type, retaining items and pagination.","schema":{"type":"string","enum":["type"]}},{"name":"page","in":"query","required":false,"description":"Page number for pagination.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"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.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"page_size","in":"query","required":false,"description":"Deprecated compatibility alias for limit; values must match when supplied together.","schema":{"type":"integer"},"deprecated":true},{"name":"pageSize","in":"query","required":false,"description":"Deprecated compatibility alias for limit; range 1–100, default 50.","schema":{"type":"integer"},"deprecated":true},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Paginated service list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"page":{"type":"integer","exclusiveMinimum":0},"pageSize":{"type":"integer","exclusiveMinimum":0},"total":{"type":"integer","minimum":0},"pages":{"type":"integer","exclusiveMinimum":0},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"activationAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingUnit":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingCount":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"object","additionalProperties":{"type":"string"}},"provisioning_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"meta":{"anyOf":[{"type":"object","properties":{"serviceType":{"type":"string"},"includedByDefault":{"type":"boolean"},"instanceIndex":{"type":"number"}},"additionalProperties":false},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"counts":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"group_by":{"type":"string","const":"type","enum":["type"]},"groups":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"activationAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingUnit":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingCount":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"object","additionalProperties":{"type":"string"}},"provisioning_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"meta":{"anyOf":[{"type":"object","properties":{"serviceType":{"type":"string"},"includedByDefault":{"type":"boolean"},"instanceIndex":{"type":"number"}},"additionalProperties":false},{"type":"null"}]}},"required":["id"],"additionalProperties":true}}}},"required":["ok","items"],"additionalProperties":true},"example":{"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"}}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]}],"operationId":"listServices"}},"/v1/services/grouped":{"get":{"tags":["Services"],"summary":"Browse services by type","description":"Returns the complete filtered customer-safe inventory grouped by type, without pagination. Intended for dashboard inventory. This is a legacy compatibility endpoint. Its default is active only, retained for backward compatibility; automation and MCP clients should pass status explicitly and prefer /v1/services?statuses=active,suspended&group_by=type for relevant lifecycle states. status=suspended or status=all explicitly includes other states. This differs from GET /v1/services?group_by=type, which groups only its current paginated result set. This endpoint supports status and type filters; use /v1/services for search and integration-metadata filters.","parameters":[{"name":"status","in":"query","required":false,"description":"Legacy default active; pass this explicitly. Filter by service status. Use all to disable status filtering.","schema":{"type":"string","enum":["active","suspended","terminated","provisioning","error","maintenance","all"]}},{"name":"type","in":"query","required":false,"description":"Optional comma-separated list of service types to keep in the grouped response.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Grouped service list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"status":{"type":"string"},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"services":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"null"}]},{"type":"array","items":{"type":"string"}}]},"ipv6":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"null"}]},{"type":"array","items":{"type":"string"}}]},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"power":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}}}},"required":["ok","status","type","services"],"additionalProperties":true},"example":{"ok":true,"status":"active","type":null,"services":{"dns":[],"vps":[],"dedicated":[],"webhosting":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]}],"deprecated":true,"operationId":"listServicesGrouped"}},"/v1/services/{serviceId}":{"get":{"tags":["Services"],"summary":"Open service detail","description":"Returns the customer-facing detail view for one service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Detailed service record.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"activationAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingUnit":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingCount":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"object","additionalProperties":{"type":"string"}},"provisioning_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"meta":{"anyOf":[{"type":"object","properties":{"serviceType":{"type":"string"},"includedByDefault":{"type":"boolean"},"instanceIndex":{"type":"number"}},"additionalProperties":false},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok","item"],"additionalProperties":true},"example":{"ok":true,"item":{"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"}}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]}],"operationId":"getService"}},"/v1/services/{serviceId}/autopay":{"patch":{"tags":["Services"],"summary":"Toggle wallet autopay","description":"Enables or disables autopay for a supported service so future renewal invoices can be handled automatically when policy allows it.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated autopay state.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"serviceId":{"type":"string"},"autopayEnabled":{"type":"boolean"}},"required":["ok","serviceId","autopayEnabled"],"additionalProperties":true},"example":{"ok":true,"serviceId":"00000000-0000-4000-8000-000000000001","autopayEnabled":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.write"]},{"BearerAuth":["billing.services.write"]}],"operationId":"serviceAutopay"}},"/v1/services/{serviceId}/renewal/options":{"get":{"tags":["Services"],"summary":"Review renewal options","description":"Returns valid renewal units or counts for the target service before you create a renewal checkout.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Available renewal options.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"currency":{"type":"string"},"current":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"price":{"type":"string"},"recurringUnitPrice":{"type":"string"},"variantId":{"type":"string"},"sku":{"type":"string"},"dims":{"type":"object","properties":{"cpu":{"type":"number"},"ram":{"type":"number"},"disk":{"type":"number"}},"required":["cpu","ram","disk"],"additionalProperties":true}},"additionalProperties":true},"options":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"price":{"type":"string"},"targetRecurringUnitPrice":{"type":"string"},"credit":{"type":"string"},"payNow":{"type":"string"},"variantId":{"type":"string"},"sku":{"type":"string"}},"additionalProperties":true}},"billing":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"}},"required":["unit","count"],"additionalProperties":true},"proration":{"type":"object","properties":{"fraction":{"type":"number"},"multiplier":{"type":"number"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"}},"additionalProperties":true},"extraDiskGB":{"type":"number"},"keepExtraDisk":{"type":"boolean"},"service":{"type":"object","properties":{"category":{"type":"string"},"isCpanel":{"type":"boolean"}},"additionalProperties":true}},"required":["ok"],"additionalProperties":true},"example":{"ok":true,"currency":"EUR","current":{"unit":"MONTH","count":1,"value":"MONTH:1","label":"Monthly","recurringUnitPrice":"100.00"},"options":[{"unit":"MONTH","count":1,"value":"MONTH:1","label":"Monthly","price":"100.00"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]}],"operationId":"serviceRenewalOptions"}},"/v1/services/{serviceId}/renewal":{"post":{"tags":["Services"],"summary":"Renew and pay using the current billing cycle","description":"Renews the existing plan and billing cycle from account balance in one call. Reuses an eligible unpaid renewal invoice or creates one; never pays a purchase, upgrade, changed-cycle or mixed-service invoice. Full payment only: insufficient credit or max_total violation rolls back new invoices and any debit. Idempotency-Key is required: reuse the same key and exact body after an interrupted response. The financial receipt is durable. Optional max_total caps the outstanding amount in invoice/account currency; it is not a supplied price. Domain renewals can return renewal_pending=true: paid_through remains the last confirmed date until provider processing completes. Manual suspensions are not cleared by this request.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique renewal attempt key, 8–128 letters, digits or . _ : -. Reuse it on retries; a new key authorizes another cycle.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_total":{"type":"string","pattern":"^(0|[1-9]\\d{0,9})(\\.\\d{1,2})?$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Paid renewal receipt, or paid pending provider confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"service_id":{"type":"string"},"invoice_id":{"type":"string"},"invoice_number":{"type":"string"},"status":{"type":"string"},"invoice_status":{"type":"string"},"paid_now":{"type":"string"},"currency":{"type":"string"},"billing":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"}},"required":["unit","count"],"additionalProperties":true},"paid_through":{"anyOf":[{"type":"string"},{"type":"null"}]},"renewal_pending":{"type":"boolean"}},"required":["ok","service_id","invoice_id","invoice_number","status","invoice_status","paid_now","currency","billing","paid_through","renewal_pending"],"additionalProperties":true},"example":{"ok":true,"service_id":"00000000-0000-4000-8000-000000000001","invoice_id":"00000000-0000-4000-8000-000000000002","invoice_number":"INV-EXAMPLE-001","status":"paid","invoice_status":"paid","paid_now":"10.00","currency":"EUR","billing":{"unit":"MONTH","count":1},"paid_through":"2026-11-01T00:00:00.000Z","renewal_pending":false}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.write","billing.invoice.pay"]},{"BearerAuth":["billing.services.write","billing.invoice.pay"]}],"operationId":"serviceRenewal"}},"/v1/services/{serviceId}/renewal/checkout":{"post":{"tags":["Services"],"summary":"Start renewal checkout","description":"Creates a renewal billing flow for the selected service and renewal period.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unit":{"type":"string","minLength":1},"count":{"type":"integer","minimum":1}},"required":["unit","count"],"additionalProperties":false}}}},"responses":{"200":{"description":"Renewal checkout result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"orderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoiceId":{"type":"string"},"invoiceNumber":{"type":"string"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"},"paidTotal":{"type":"string"},"currency":{"type":"string"},"createdAt":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"payDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"refundedTotal":{"type":"string"}},"required":["id","number","status","total","paidTotal","currency"],"additionalProperties":true},"total":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string"},"paymentStatus":{"type":"string"},"serviceIds":{"type":"array","items":{"type":"string"}},"message":{"type":"string"},"deploymentStatusUrl":{"type":"string"},"applied":{"type":"boolean"},"payNow":{"type":"string"}},"required":["ok"],"additionalProperties":true},"example":{"ok":true,"orderId":null,"invoiceId":"00000000-0000-4000-8000-000000000002","invoiceNumber":"INV-EXAMPLE-000001","total":"100.00","currency":"EUR","status":"unpaid"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.write"]},{"BearerAuth":["billing.services.write"]}],"operationId":"serviceRenewalCheckout"}},"/v1/services/{serviceId}/upgrade/options":{"get":{"tags":["Services"],"summary":"Review upgrade options","description":"Returns supported upgrade choices for the selected service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Available upgrade options.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"currency":{"type":"string"},"current":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"price":{"type":"string"},"recurringUnitPrice":{"type":"string"},"variantId":{"type":"string"},"sku":{"type":"string"},"dims":{"type":"object","properties":{"cpu":{"type":"number"},"ram":{"type":"number"},"disk":{"type":"number"}},"required":["cpu","ram","disk"],"additionalProperties":true}},"additionalProperties":true},"options":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"price":{"type":"string"},"targetRecurringUnitPrice":{"type":"string"},"credit":{"type":"string"},"payNow":{"type":"string"},"variantId":{"type":"string"},"sku":{"type":"string"}},"additionalProperties":true}},"billing":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"}},"required":["unit","count"],"additionalProperties":true},"proration":{"type":"object","properties":{"fraction":{"type":"number"},"multiplier":{"type":"number"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"}},"additionalProperties":true},"extraDiskGB":{"type":"number"},"keepExtraDisk":{"type":"boolean"},"service":{"type":"object","properties":{"category":{"type":"string"},"isCpanel":{"type":"boolean"}},"additionalProperties":true}},"required":["ok"],"additionalProperties":true},"example":{"ok":true,"extraDiskGB":0,"keepExtraDisk":false,"service":{"category":"vps","isCpanel":false},"current":{"variantId":"00000000-0000-4000-8000-000000000001","sku":"4G","dims":{"cpu":2,"ram":4,"disk":40}},"currency":"EUR","billing":{"unit":"MONTH","count":1},"proration":{"multiplier":1,"fraction":1,"periodStart":"2026-10-01T00:00:00.000Z","periodEnd":"2026-11-01T00:00:00.000Z"},"options":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]}],"operationId":"serviceUpgradeOptions"}},"/v1/services/{serviceId}/upgrade/checkout":{"post":{"tags":["Services"],"summary":"Start upgrade checkout","description":"Creates or applies an upgrade flow for the selected service and variant.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid"}},"required":["variant_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Upgrade checkout result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"orderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoiceId":{"type":"string"},"invoiceNumber":{"type":"string"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"},"paidTotal":{"type":"string"},"currency":{"type":"string"},"createdAt":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"payDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"refundedTotal":{"type":"string"}},"required":["id","number","status","total","paidTotal","currency"],"additionalProperties":true},"total":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string"},"paymentStatus":{"type":"string"},"serviceIds":{"type":"array","items":{"type":"string"}},"message":{"type":"string"},"deploymentStatusUrl":{"type":"string"},"applied":{"type":"boolean"},"payNow":{"type":"string"}},"required":["ok"],"additionalProperties":true},"example":{"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"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.write"]},{"BearerAuth":["billing.services.write"]}],"operationId":"serviceUpgradeCheckout"}},"/v1/services/{serviceId}/billing/options":{"get":{"tags":["Services"],"summary":"Review billing options","description":"Returns the current billing-cycle choices exposed for the selected service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Available billing options.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"currency":{"type":"string"},"current":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"price":{"type":"string"},"recurringUnitPrice":{"type":"string"},"variantId":{"type":"string"},"sku":{"type":"string"},"dims":{"type":"object","properties":{"cpu":{"type":"number"},"ram":{"type":"number"},"disk":{"type":"number"}},"required":["cpu","ram","disk"],"additionalProperties":true}},"additionalProperties":true},"options":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"price":{"type":"string"},"targetRecurringUnitPrice":{"type":"string"},"credit":{"type":"string"},"payNow":{"type":"string"},"variantId":{"type":"string"},"sku":{"type":"string"}},"additionalProperties":true}},"billing":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"}},"required":["unit","count"],"additionalProperties":true},"proration":{"type":"object","properties":{"fraction":{"type":"number"},"multiplier":{"type":"number"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"}},"additionalProperties":true},"extraDiskGB":{"type":"number"},"keepExtraDisk":{"type":"boolean"},"service":{"type":"object","properties":{"category":{"type":"string"},"isCpanel":{"type":"boolean"}},"additionalProperties":true}},"required":["ok"],"additionalProperties":true},"example":{"ok":true,"currency":"EUR","current":{"unit":"MONTH","count":1,"value":"MONTH:1","label":"Monthly"},"options":[{"unit":"MONTH","count":1,"value":"MONTH:1","label":"Monthly","price":"100.00"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]}],"operationId":"serviceBillingOptions"}},"/v1/services/{serviceId}/billing/change/options":{"get":{"tags":["Services"],"summary":"Review billing-cycle options","description":"Returns the proration-aware billing-cycle change choices for a service before checkout.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Available billing-cycle change options.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"currency":{"type":"string"},"current":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"price":{"type":"string"},"recurringUnitPrice":{"type":"string"},"variantId":{"type":"string"},"sku":{"type":"string"},"dims":{"type":"object","properties":{"cpu":{"type":"number"},"ram":{"type":"number"},"disk":{"type":"number"}},"required":["cpu","ram","disk"],"additionalProperties":true}},"additionalProperties":true},"options":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"},"price":{"type":"string"},"targetRecurringUnitPrice":{"type":"string"},"credit":{"type":"string"},"payNow":{"type":"string"},"variantId":{"type":"string"},"sku":{"type":"string"}},"additionalProperties":true}},"billing":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"}},"required":["unit","count"],"additionalProperties":true},"proration":{"type":"object","properties":{"fraction":{"type":"number"},"multiplier":{"type":"number"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"}},"additionalProperties":true},"extraDiskGB":{"type":"number"},"keepExtraDisk":{"type":"boolean"},"service":{"type":"object","properties":{"category":{"type":"string"},"isCpanel":{"type":"boolean"}},"additionalProperties":true}},"required":["ok"],"additionalProperties":true},"example":{"ok":true,"currency":"EUR","current":{"unit":"MONTH","count":1,"value":"MONTH:1","label":"Monthly","recurringUnitPrice":"100.00"},"proration":{"fraction":1,"periodStart":"2026-10-01T00:00:00.000Z","periodEnd":"2026-11-01T00:00:00.000Z"},"options":[{"unit":"MONTH","count":1,"value":"MONTH:1","label":"Monthly","targetRecurringUnitPrice":"100.00","credit":"100.00","payNow":"0.00"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.read"]},{"BearerAuth":["billing.services.read"]}],"operationId":"serviceBillingChangeOptions"}},"/v1/services/{serviceId}/billing/change/checkout":{"post":{"tags":["Services"],"summary":"Start billing-cycle change","description":"Creates a prorated checkout when a customer changes the service billing cycle.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unit":{"type":"string","minLength":1},"count":{"type":"integer","minimum":1}},"required":["unit","count"],"additionalProperties":false}}}},"responses":{"200":{"description":"Billing-cycle change checkout result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"orderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoiceId":{"type":"string"},"invoiceNumber":{"type":"string"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"},"paidTotal":{"type":"string"},"currency":{"type":"string"},"createdAt":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"payDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"refundedTotal":{"type":"string"}},"required":["id","number","status","total","paidTotal","currency"],"additionalProperties":true},"total":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string"},"paymentStatus":{"type":"string"},"serviceIds":{"type":"array","items":{"type":"string"}},"message":{"type":"string"},"deploymentStatusUrl":{"type":"string"},"applied":{"type":"boolean"},"payNow":{"type":"string"}},"required":["ok"],"additionalProperties":true},"example":{"ok":true,"applied":true,"payNow":"0.00","currency":"EUR"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.write"]},{"BearerAuth":["billing.services.write"]}],"operationId":"serviceBillingChangeCheckout"}},"/v1/services/{serviceId}/cancel":{"post":{"tags":["Services"],"summary":"Request service cancellation","description":"Convenience alias for service termination. Use this when the customer intent is straightforward cancellation.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Recommended stable retry key. CLI 0.1.17 makes the flag optional: an omitted key is generated once, saved locally before dispatch and printed for explicit retries. Reuse the same key and exact payload. With durable_writes enabled, the API retains the dispatch identity after its encrypted response expires in 24 hours. An unknown outcome requires inspecting service/operation state; never generate a new key to retry it. Missing keys keep legacy behavior.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Cancellation result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["billing.services.write"]},{"BearerAuth":["billing.services.write"]}],"operationId":"serviceCancel"}},"/v1/services/{serviceId}/dns/waf":{"get":{"tags":["Service DNS/WAF"],"summary":"Check DNS/WAF eligibility","description":"Returns the protection mode and service eligibility for DNS proxy and WAF-related actions on the selected service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"DNS/WAF eligibility details.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"serviceId":{"type":"string"},"serviceStatus":{"type":"string"},"backendIpv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"dnsWaf":{"type":"object","properties":{"serviceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"active":{"type":"boolean"}},"required":["serviceId","active"],"additionalProperties":true},"free":{"type":"object","properties":{"eligible":{"type":"boolean"}},"required":["eligible"],"additionalProperties":true},"eligible":{"type":"boolean"},"mode":{"type":"string"}},"required":["ok","serviceId","serviceStatus","backendIpv4","dnsWaf","free","eligible","mode"],"additionalProperties":true},"example":{"ok":true,"serviceId":"00000000-0000-4000-8000-000000000001","serviceStatus":"active","backendIpv4":"192.0.2.10","dnsWaf":{"serviceId":null,"active":false},"free":{"eligible":true},"eligible":true,"mode":"free"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"serviceDnsWafStatus"}},"/v1/services/{serviceId}/dns/waf/record":{"get":{"tags":["Service DNS/WAF"],"summary":"Inspect protected record","description":"Returns the current proxy, protection, and origin values for one service-scoped DNS record.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"domain","in":"query","required":true,"description":"Zone or apex domain for the protected record.","schema":{"type":"string"}},{"name":"name","in":"query","required":true,"description":"Record name such as @ or www.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Protected record status.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"serviceId":{"type":"string"},"serviceStatus":{"type":"string"},"backendIpv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"domain":{"type":"string"},"record":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"values":{"type":"array","items":{"type":"string"}},"proxied":{"type":"boolean"},"originValues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"protection":{"type":"boolean"}},"required":["name","type","ttl","values"],"additionalProperties":true}},"required":["ok","serviceId","serviceStatus","backendIpv4","domain","record"],"additionalProperties":true},"example":{"ok":true,"serviceId":"00000000-0000-4000-8000-000000000001","serviceStatus":"active","backendIpv4":"192.0.2.10","domain":"example.com","record":{"name":"example.com.","type":"A","ttl":300,"values":["192.0.2.10"],"proxied":false,"originValues":null,"protection":false}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"getServiceDnsWafRecord"}},"/v1/services/{serviceId}/dns/waf/record/proxy":{"post":{"tags":["Service DNS/WAF"],"summary":"Toggle proxy mode","description":"Enables or disables proxy mode for a service-scoped record. This is the main action for moving a record behind the managed proxy layer.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"enabled":{"type":"boolean"},"ttl":{"type":"integer","minimum":1,"maximum":86400}},"required":["domain","name","enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated proxy state.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"appliedTo":{"type":"string"},"proxied":{"type":"boolean"},"providerBackends":{"type":"array","items":{"type":"string"}}},"required":["ok","appliedTo","proxied"],"additionalProperties":true},"example":{"ok":true,"appliedTo":"powerdns","proxied":true,"providerBackends":["192.0.2.10"]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"serviceDnsWafRecordProxy"}},"/v1/services/{serviceId}/dns/waf/record/protection":{"post":{"tags":["Service DNS/WAF"],"summary":"Toggle protection mode","description":"Enables or disables the protection layer for a proxied record.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"enabled":{"type":"boolean"}},"required":["domain","name","enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated protection state.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"fqdn":{"type":"string","description":"Lowercase hostname without a trailing root dot, for example example.com. Inputs accept either form. DNS RRset names and record values retain DNS notation."},"protection":{"type":"boolean"}},"required":["ok","fqdn","protection"],"additionalProperties":true},"example":{"ok":true,"fqdn":"example.com","protection":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"serviceDnsWafRecordProtection"}},"/v1/services/{serviceId}/dns/waf/record/origin-sync":{"post":{"tags":["Service DNS/WAF"],"summary":"Run origin sync","description":"Refreshes the protected record origin target so the proxy backend follows the current service IP.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["domain","name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Origin sync result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"fqdn":{"type":"string","description":"Lowercase hostname without a trailing root dot, for example example.com. Inputs accept either form. DNS RRset names and record values retain DNS notation."},"backendIpv4":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ok","fqdn","backendIpv4"],"additionalProperties":true},"example":{"ok":true,"fqdn":"example.com","backendIpv4":"192.0.2.10"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"serviceDnsWafRecordOriginSync"}},"/v1/services/{serviceId}/dns/waf/record/proxy-config/show":{"post":{"tags":["Service DNS/WAF"],"summary":"View proxy settings","description":"Returns the proxy configuration for an owned proxied record. Accepts an owned DNS zone name or service UUID. With a zone-name selector, domain is optional and must match when supplied; name defaults to @. Prefer the read-only GET /v1/dns/zones/{name}/records/config. This legacy POST can ensure proxy registration.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your DNS zone name (example.com) or an owned service UUID. A name selects the owned zone directly; a UUID also requires domain in the query/body.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":1024},"name":{"type":"string","minLength":1,"maxLength":253,"default":"@"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Current proxy configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"data":{"$ref":"#/$defs/JsonValue"},"html":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ok","data"],"additionalProperties":true,"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"ok":true,"data":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"serviceDnsWafProxyConfigShow"}},"/v1/services/{serviceId}/dns/waf/record/proxy-config/update-setting":{"post":{"tags":["Service DNS/WAF"],"summary":"Change proxy setting","description":"Changes one supported proxy setting such as force SSL, SSL mode, or custom loader behavior.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"option":{"type":"string","enum":["ssl_schema","force_ssl","ssl","custom_loader"]},"value":{"type":"string","minLength":1}},"required":["domain","name","option","value"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated proxy setting result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"serviceDnsWafProxyConfigUpdateSetting"}},"/v1/services/{serviceId}/dns/waf/record/proxy-config/get-ssl":{"post":{"tags":["Service DNS/WAF"],"summary":"View SSL settings","description":"Returns certificate metadata and configuration readiness for the selected protected record. ready confirms a matching, currently valid certificate in the provider configuration; it does not confirm public DNS propagation or browser trust. Provider lookup failures return a safe error.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["domain","name"],"additionalProperties":false}}}},"responses":{"200":{"description":"SSL configuration details.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"data":{"anyOf":[{"type":"object","properties":{"hasCert":{"type":"boolean"},"ready":{"type":"boolean"},"status":{"type":"string","enum":["ready","missing","invalid","expired","not_yet_valid","disabled","pending","unknown"]},"mode":{"anyOf":[{"type":"string"},{"type":"null"}]},"readiness_scope":{"type":"string","const":"certificate_configuration","enum":["certificate_configuration"]},"cert":{"type":"object","properties":{"subject":{"type":"string"},"issuer":{"type":"string"},"validFrom":{"type":"string"},"validTo":{"type":"string"},"fingerprint256":{"type":"string"},"serialNumber":{"type":"string"},"subjectAltName":{"type":"string"}},"required":["subject","issuer"],"additionalProperties":true}},"required":["hasCert"],"additionalProperties":true},{"type":"null"}]}},"required":["ok","data"],"additionalProperties":true},"example":{"ok":true,"data":{"hasCert":true,"ready":true,"status":"ready","mode":"c","readiness_scope":"certificate_configuration","cert":{"subject":"CN=example.com","issuer":"CN=Example CA","validFrom":"2026-10-01T00:00:00.000Z","validTo":"2027-10-06T00:00:00.000Z","fingerprint256":"AA:BB:CC"}}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"serviceDnsWafProxyConfigGetSsl"}},"/v1/services/{serviceId}/dns/waf/record/proxy-config/upload-ssl":{"post":{"tags":["Service DNS/WAF"],"summary":"Upload custom SSL certificate","description":"Validates the hostname, validity dates, certificate chain syntax and matching private key before uploading. Domains may be configured before DNS points to the proxy. Returns certificate configuration readiness and expected_fingerprint256 after readback. pending or unknown means the accepted upload is not yet confirmed; check get-ssl before retrying. Private key material is never returned.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"mode":{"type":"string","enum":["c","w"]},"cert":{"type":"string","minLength":1},"pkey":{"type":"string","minLength":1},"bundle":{"type":"string","default":""}},"required":["domain","name","mode","cert","pkey"],"additionalProperties":false}}}},"responses":{"200":{"description":"SSL upload result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"data":{"type":"object","properties":{"hasCert":{"type":"boolean"},"ready":{"type":"boolean"},"status":{"type":"string","enum":["ready","missing","invalid","expired","not_yet_valid","disabled","pending","unknown"]},"mode":{"anyOf":[{"type":"string"},{"type":"null"}]},"readiness_scope":{"type":"string","const":"certificate_configuration","enum":["certificate_configuration"]},"cert":{"type":"object","properties":{"subject":{"type":"string"},"issuer":{"type":"string"},"validFrom":{"type":"string"},"validTo":{"type":"string"},"fingerprint256":{"type":"string"},"serialNumber":{"type":"string"},"subjectAltName":{"type":"string"}},"required":["subject","issuer"],"additionalProperties":true}},"required":["hasCert"],"additionalProperties":true},"expected_fingerprint256":{"type":"string"}},"required":["ok"],"additionalProperties":true},"example":{"ok":true,"data":{"hasCert":false,"ready":false,"status":"pending","mode":"c","readiness_scope":"certificate_configuration"},"expected_fingerprint256":"AA:BB:CC"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"serviceDnsWafProxyConfigUploadSsl"}},"/v1/services/{serviceId}/dns/waf/record/proxy-config/get-loader":{"post":{"tags":["Service DNS/WAF"],"summary":"View custom loader","description":"Returns the currently configured custom loader or response page for a protected record.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["domain","name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Current loader configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"data":{"$ref":"#/$defs/JsonValue"},"html":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ok","data"],"additionalProperties":true,"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"ok":true,"data":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"serviceDnsWafProxyConfigGetLoader"}},"/v1/services/{serviceId}/dns/waf/record/proxy-config/upload-loader":{"post":{"tags":["Service DNS/WAF"],"summary":"Upload custom loader","description":"Uploads custom HTML used by the proxy layer for the selected record.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"html":{"type":"string","minLength":1}},"required":["domain","name","html"],"additionalProperties":false}}}},"responses":{"200":{"description":"Loader upload result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"data":{"$ref":"#/$defs/JsonValue"},"html":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ok","data"],"additionalProperties":true,"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"ok":true,"data":null,"html":"<!doctype html><title>Loading</title>"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"serviceDnsWafProxyConfigUploadLoader"}},"/v1/dedicated/catalog":{"get":{"tags":["Dedicated Servers"],"summary":"Browse dedicated inventory","description":"Returns currently sellable configurations, regions, hardware, billing periods, and compatible operating-system profiles.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Available dedicated inventory.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"region":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"operatingSystems":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"code":{"type":"string"},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"arch":{"anyOf":[{"type":"string"},{"type":"null"}]},"isDefault":{"type":"boolean"},"allowSshKeys":{"type":"boolean"}},"additionalProperties":true}}},"required":["code"],"additionalProperties":true},"hardware":{"type":"object","properties":{"lineName":{"type":"string"},"cpuSockets":{"type":"number"},"ramGb":{"type":"number"},"storageGb":{"type":"number"},"linkGbps":{"type":"number"},"physicalLinkGbps":{"type":"number"},"cpuDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"ramDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"storageDescription":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"availableStock":{"anyOf":[{"type":"number"},{"type":"null"}]},"osProfiles":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"name":{"type":"string"},"allowSshKeys":{"type":"boolean"},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"type":"boolean"}},"required":["id","name"],"additionalProperties":true}},"billingProductId":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingVariantId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code"],"additionalProperties":true}}},"required":["ok","items"],"additionalProperties":true},"example":{"ok":true,"items":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedCatalog"}},"/v1/dedicated/deployments":{"post":{"tags":["Dedicated Servers"],"summary":"Create dedicated deployment","description":"Creates an unpaid order and invoice using catalog configurationCode, regionCode, numeric osProfileId, hostname, optional owned sshKeyId, billing and selectable add-ons. Use order-options to discover valid add-on keys and quantities, and preview the same complete configuration before ordering. Provisioning begins only after payment and any configured approval. Never invent configuration or OS IDs.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable action key: 8–128 letters, digits, dot, underscore, colon or hyphen. Reuse the same key and payload on retries; inspect task state after a timeout.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configuration_code":{"type":"string","minLength":1,"maxLength":160},"region_code":{"type":"string","pattern":"^[A-Z0-9-]{2,16}$"},"os_profile_id":{"type":"integer","exclusiveMinimum":0},"hostname":{"type":"string","minLength":1,"maxLength":253,"pattern":"^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$"},"ssh_key_id":{"type":"string","format":"uuid"},"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},"currency":{"type":"string","enum":["EUR","USD"],"default":"EUR"},"billing":{"type":"object","properties":{"unit":{"type":"string","enum":["MONTH","QUARTAL","SEMIANNUAL","YEAR"],"default":"MONTH"},"count":{"type":"integer","minimum":1,"maximum":120,"default":1}},"additionalProperties":false,"default":{"unit":"MONTH","count":1}}},"required":["configuration_code","region_code","os_profile_id","hostname"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created order and invoice; not yet installed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"orderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoiceId":{"type":"string"},"invoiceNumber":{"type":"string"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"},"paidTotal":{"type":"string"},"currency":{"type":"string"},"createdAt":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"payDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"refundedTotal":{"type":"string"}},"required":["id","number","status","total","paidTotal","currency"],"additionalProperties":true},"total":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string"},"paymentStatus":{"type":"string"},"serviceIds":{"type":"array","items":{"type":"string"}},"message":{"type":"string"},"deploymentStatusUrl":{"type":"string"},"applied":{"type":"boolean"},"payNow":{"type":"string"}},"required":["ok"],"additionalProperties":true},"example":{"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","deploymentStatusUrl":"/v1/dedicated/deployments/00000000-0000-4000-8000-000000000001","message":"Invoice created. Provisioning begins after payment and any configured approval."}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.write"]},{"BearerAuth":["dedicated.write"]}],"operationId":"dedicatedDeploy"}},"/v1/dedicated/deployments/{orderId}":{"get":{"tags":["Dedicated Servers"],"summary":"Check deployment","description":"Returns payment, provisioning, service, IP, power, OS, and operation state for a dedicated order without exposing its password.","parameters":[{"name":"orderId","in":"path","required":true,"description":"Dedicated deployment order UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Dedicated deployment status.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"deployment":{"type":"object","properties":{"orderId":{"type":"string"},"orderStatus":{"type":"string"},"paymentStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoice":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"},"paidTotal":{"type":"string"},"currency":{"type":"string"},"createdAt":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"payDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"refundedTotal":{"type":"string"}},"required":["id","number","status","total","paidTotal","currency"],"additionalProperties":true},{"type":"null"}]},"serviceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"serviceStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"ip":{"anyOf":[{"type":"string"},{"type":"null"}]},"power":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"osName":{"anyOf":[{"type":"string"},{"type":"null"}]},"operations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true}}},"required":["orderId","orderStatus","paymentStatus","invoice","serviceId","serviceStatus","ip","power","hostname","osName","operations"],"additionalProperties":true}},"required":["ok","deployment"],"additionalProperties":true},"example":{"ok":true,"deployment":{"orderId":"00000000-0000-4000-8000-000000000001","orderStatus":"pending","paymentStatus":"unpaid","invoice":{"id":"00000000-0000-4000-8000-000000000001","number":"INV-EXAMPLE-000001","status":"unpaid","total":"100.00","paidTotal":"0.00","currency":"EUR"},"serviceId":null,"serviceStatus":null,"ip":null,"power":null,"hostname":null,"osName":null,"operations":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedDeployment"}},"/v1/dedicated/{serviceId}":{"get":{"tags":["Dedicated Servers"],"summary":"Check dedicated server","description":"Returns the owned server lifecycle, hardware, operating system, IP, power state, and recent operations.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Dedicated server status.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"lifecycleStatus":{"type":"string"},"service":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string"},"configurationCode":{"type":"string"},"regionCode":{"type":"string"},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"osName":{"anyOf":[{"type":"string"},{"type":"null"}]},"hardware":{"type":"object","properties":{"lineName":{"type":"string"},"cpuSockets":{"type":"number"},"ramGb":{"type":"number"},"storageGb":{"type":"number"},"linkGbps":{"type":"number"},"physicalLinkGbps":{"type":"number"},"cpuDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"ramDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"storageDescription":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"primaryIp":{"anyOf":[{"type":"string"},{"type":"null"}]},"power":{"anyOf":[{"type":"string"},{"type":"null"}]},"powerCheckedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"rescueMode":{"type":"boolean"},"canManage":{"type":"boolean"},"canConsole":{"type":"boolean"},"canReinstall":{"type":"boolean"},"canRescue":{"type":"boolean"},"suspensionReason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"operations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true}}},"required":["ok","lifecycleStatus","service","operations"],"additionalProperties":true},"example":{"ok":true,"lifecycleStatus":"active","service":{"state":"active","configurationCode":"EXAMPLE","regionCode":"PT","hostname":"server.example.com","osName":"Debian 13","hardware":{"lineName":"Example dedicated server","cpuSockets":2,"ramGb":256,"storageGb":240,"linkGbps":10,"physicalLinkGbps":10,"cpuDescription":"Example CPU","ramDescription":"DDR4 ECC","storageDescription":"SSD"},"primaryIp":"192.0.2.10","power":"online","powerCheckedAt":"2026-10-01T00:00:00.000Z","rescueMode":false,"canManage":true,"canConsole":true,"canReinstall":true,"canRescue":true},"operations":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedStatus"}},"/v1/dedicated/{serviceId}/credentials":{"get":{"tags":["Dedicated Servers"],"summary":"Reveal current credentials","description":"Explicit no-store credential endpoint. Returns the owned server IP, username, and current generated password after activation.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Dedicated server access credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"serviceId":{"type":"string"},"ip":{"anyOf":[{"type":"string"},{"type":"null"}]},"username":{"type":"string"},"password":{"anyOf":[{"type":"string"},{"type":"null"}]},"credentialKind":{"type":"string"},"operationId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ok","serviceId","ip","username","password"],"additionalProperties":true},"example":{"ok":true,"serviceId":"00000000-0000-4000-8000-000000000001","ip":"192.0.2.10","username":"root","password":"<generated-password>","credentialKind":"activate","operationId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.credentials.read"]},{"BearerAuth":["dedicated.credentials.read"]}],"operationId":"dedicatedCredentials"}},"/v1/dedicated/{serviceId}/power":{"post":{"tags":["Dedicated Servers"],"summary":"Queue power action","description":"Body action: start, stop, restart or exit_rescue. Exiting rescue boots the installed system from disk. Interrupting actions require explicit intent. Task acceptance is not completion; inspect the returned task.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable action key: 8–128 letters, digits, dot, underscore, colon or hyphen. Reuse the same key and payload on retries; inspect task state after a timeout.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["start","stop","restart","exit_rescue"]}},"required":["action"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued power operation.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"operation":{"id":"00000000-0000-4000-8000-000000000002","kind":"power_on","state":"queued"},"operation_id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","operation_url":"/v1/operations/op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.write"]},{"BearerAuth":["dedicated.write"]}],"operationId":"dedicatedPower"}},"/v1/dedicated/{serviceId}/tasks":{"get":{"tags":["Dedicated Servers"],"summary":"List dedicated tasks","description":"Returns customer-visible operations for the owned server. Read history before repeating an uncertain action.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Dedicated task history.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}}},"required":["ok","tasks"],"additionalProperties":true},"example":{"ok":true,"tasks":[{"id":"00000000-0000-4000-8000-000000000002","kind":"reinstall","status":"in_progress","stage":"installing","errorCode":null,"createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedTasks"}},"/v1/dedicated/{serviceId}/traffic":{"get":{"tags":["Dedicated Servers"],"summary":"Read network traffic","description":"Returns available network samples. Rates are bits per second and traffic totals are bytes. Missing statistics are not zero traffic. Does not report guest resource usage.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Network statistics or unavailable result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"available":{"type":"boolean"},"period":{"type":"string"},"interfaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"timestamp":{"anyOf":[{"type":"string"},{"type":"number"}]},"bytesIn":{"type":"number"},"bytesOut":{"type":"number"},"rx":{"type":"number"},"tx":{"type":"number"},"watts":{"anyOf":[{"type":"number"},{"type":"null"}]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"connections":{"type":"number"},"errors":{"type":"number"},"blockedPackets":{"type":"number"}},"additionalProperties":true}},"rx":{"type":"number"},"tx":{"type":"number"}},"additionalProperties":true}}},"required":["ok","available","period","interfaces"],"additionalProperties":true},"example":{"ok":true,"available":false,"period":"24h","interfaces":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"getDedicatedByServiceIdTraffic"}},"/v1/dedicated/{serviceId}/power-stats":{"get":{"tags":["Dedicated Servers"],"summary":"Read electrical power statistics","description":"Electrical consumption in watts, not CPU utilization. Any estimated energy value is not a billing meter. Hardware may not expose measurements.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Power statistics or unavailable result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"available":{"type":"boolean"},"period":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"timestamp":{"anyOf":[{"type":"string"},{"type":"number"}]},"bytesIn":{"type":"number"},"bytesOut":{"type":"number"},"rx":{"type":"number"},"tx":{"type":"number"},"watts":{"anyOf":[{"type":"number"},{"type":"null"}]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"connections":{"type":"number"},"errors":{"type":"number"},"blockedPackets":{"type":"number"}},"additionalProperties":true}},"summary":{"type":"object","properties":{"currentWatts":{"anyOf":[{"type":"number"},{"type":"null"}]},"averageWatts":{"anyOf":[{"type":"number"},{"type":"null"}]},"peakWatts":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimatedKwh":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["currentWatts","averageWatts","peakWatts","estimatedKwh"],"additionalProperties":true}},"required":["ok","available","period","points","summary"],"additionalProperties":true},"example":{"ok":true,"available":false,"period":"24h","points":[],"summary":{"currentWatts":null,"averageWatts":null,"peakWatts":null,"estimatedKwh":null}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedStats"}},"/v1/dedicated/{serviceId}/reinstall-options":{"get":{"tags":["Dedicated Servers"],"summary":"List compatible installation images","description":"Read compatible numeric profile IDs before requesting reinstall. Reading options does not start an installation.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Compatible OS profiles.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"enabled":{"type":"boolean"},"profiles":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"name":{"type":"string"},"allowSshKeys":{"type":"boolean"},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"type":"boolean"}},"required":["id","name"],"additionalProperties":true}},"currentProfileId":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]}},"required":["ok","enabled","profiles"],"additionalProperties":true},"example":{"ok":true,"enabled":true,"currentProfileId":1,"profiles":[{"id":1,"name":"Debian 13","allowSshKeys":true}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedReinstallOptions"}},"/v1/dedicated/{serviceId}/rescue-options":{"get":{"tags":["Dedicated Servers"],"summary":"List compatible rescue images","description":"Read compatible numeric rescue profile IDs before requesting maintenance boot.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Compatible rescue profiles.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"enabled":{"type":"boolean"},"profiles":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"name":{"type":"string"},"allowSshKeys":{"type":"boolean"},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"type":"boolean"}},"required":["id","name"],"additionalProperties":true}},"currentProfileId":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]}},"required":["ok","enabled","profiles"],"additionalProperties":true},"example":{"ok":true,"enabled":true,"profiles":[{"id":2,"name":"Example rescue image"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedRescueOptions"}},"/v1/dedicated/{serviceId}/reinstall":{"post":{"tags":["Dedicated Servers"],"summary":"Erase and reinstall the server","description":"Irreversibly overwrites installed data. Read compatible profiles first; use an account-owned SSH key when supported. Inspect the returned task rather than submitting another installation.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable action key: 8–128 letters, digits, dot, underscore, colon or hyphen. Reuse the same key and payload on retries; inspect task state after a timeout.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profile_id":{"type":"integer","exclusiveMinimum":0},"hostname":{"type":"string","pattern":"^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$"},"ssh_key_id":{"type":"string","format":"uuid"},"confirmation":{"type":"string","const":"ERASE","enum":["ERASE"]}},"required":["profile_id","confirmation"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued reinstall operation.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"operation":{"id":"00000000-0000-4000-8000-000000000002","state":"waiting_provider"},"operation_id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","operation_url":"/v1/operations/op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.write"]},{"BearerAuth":["dedicated.write"]}],"operationId":"dedicatedReinstall"}},"/v1/dedicated/{serviceId}/rescue":{"post":{"tags":["Dedicated Servers"],"summary":"Boot a rescue environment","description":"Interrupts applications and connections; does not itself reinstall the OS. Use a compatible rescue profile, then exit_rescue to return to installed-system boot.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable action key: 8–128 letters, digits, dot, underscore, colon or hyphen. Reuse the same key and payload on retries; inspect task state after a timeout.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profile_id":{"type":"integer","exclusiveMinimum":0},"confirmation":{"type":"string","const":"RESCUE","enum":["RESCUE"]}},"required":["profile_id","confirmation"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued rescue operation.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"operation":{"id":"00000000-0000-4000-8000-000000000002","state":"waiting_provider"},"operation_id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","operation_url":"/v1/operations/op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.write"]},{"BearerAuth":["dedicated.write"]}],"operationId":"dedicatedRescue"}},"/v1/dedicated/{serviceId}/tasks/{taskId}":{"get":{"tags":["Dedicated Servers"],"summary":"Check dedicated task","description":"Returns bounded customer-safe status for a power or maintenance task.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"taskId","in":"path","required":true,"description":"Dedicated operation UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Dedicated task status.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok","task"],"additionalProperties":true},"example":{"ok":true,"task":{"id":"00000000-0000-4000-8000-000000000002","kind":"reinstall","status":"in_progress","stage":"installing","errorCode":null,"createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedTask"}},"/v1/dedicated/{serviceId}/password-reset":{"post":{"tags":["Dedicated Servers"],"summary":"Reset dedicated password","description":"Interrupts connections while maintenance replaces the OS administrator password. Track the returned task; retrieve the result privately only after success.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable action key: 8–128 letters, digits, dot, underscore, colon or hyphen. Reuse the same key and payload on retries; inspect task state after a timeout.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"202":{"description":"Queued password reset.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"operation":{"id":"00000000-0000-4000-8000-000000000002","state":"waiting_provider"},"operation_id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","operation_url":"/v1/operations/op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.write"]},{"BearerAuth":["dedicated.write"]}],"operationId":"dedicatedPasswordReset"}},"/v1/dedicated/{serviceId}/password-reset-credential":{"get":{"tags":["Dedicated Servers"],"summary":"Reveal reset password","description":"Explicit no-store endpoint returning the generated password after successful reset. Sensitive output: do not log or send to an AI conversation.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"operationId","in":"query","required":false,"description":"Optional password-reset operation UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"New dedicated server password.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operationId":{"type":"string"},"password":{"type":"string"}},"required":["ok","operationId","password"],"additionalProperties":true},"example":{"ok":true,"operationId":"00000000-0000-4000-8000-000000000002","password":"<generated-password>"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.credentials.read"]},{"BearerAuth":["dedicated.credentials.read"]}],"operationId":"dedicatedPasswordResetCredential"}},"/v1/vps/{serviceId}/status":{"get":{"tags":["VPS"],"summary":"Check VPS status","description":"Returns hostname, assigned region code (for example NL or PT), customer IPv4/IPv6, power state and selected runtime metrics. Region describes the hosting country, not a specific datacenter building; null means unavailable. Does not disclose internal node or cluster identifiers. Ownership, status, type, search, external_id and label filters are applied server-side before pagination and counts. The default is active plus suspended; historical states require an explicit status filter. group_by=type groups only the current page, not the complete inventory.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"VPS runtime status, hostname and assigned region.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"vm":{"type":"object","properties":{"status":{"type":"string"},"power":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"os":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"guestVerified":{"type":"boolean"}},"required":["name","version","family","source","guestVerified"],"additionalProperties":true},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"uptime":{"anyOf":[{"type":"number"},{"type":"null"}]},"cpus":{"anyOf":[{"type":"number"},{"type":"null"}]},"cpu":{"anyOf":[{"type":"number"},{"type":"null"}]},"mem":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxmem":{"anyOf":[{"type":"number"},{"type":"null"}]},"disk":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxdisk":{"anyOf":[{"type":"number"},{"type":"null"}]},"netin":{"anyOf":[{"type":"number"},{"type":"null"}]},"netout":{"anyOf":[{"type":"number"},{"type":"null"}]},"diskread":{"anyOf":[{"type":"number"},{"type":"null"}]},"diskwrite":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["status"],"additionalProperties":true}},"required":["ok","vm"],"additionalProperties":true},"example":{"ok":true,"vm":{"status":"running","power":"on","hostname":"server.example.com","os":{"name":"Debian","version":"13","family":"debian","source":"provisioning_metadata","guestVerified":false},"ipv4":"192.0.2.10","ipv6":null,"uptime":3600,"cpus":2,"cpu":0.05,"mem":536870912,"maxmem":4294967296,"disk":0,"maxdisk":42949672960,"netin":0,"netout":0,"diskread":0,"diskwrite":0}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"vpsStatus"}},"/v1/vps/{serviceId}/credentials":{"get":{"tags":["VPS"],"summary":"Reveal recorded VPS credentials","description":"Explicit, audited, no-store password retrieval. The platform-recorded root password may differ if changed inside the guest. Never log output or send it to a hosted AI conversation.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Recorded rootPassword, hostname, IPv4 and IPv6.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"serviceId":{"type":"string"},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"rootPassword":{"anyOf":[{"type":"string"},{"type":"null"}]},"credentialSource":{"type":"string"},"guestVerified":{"type":"boolean"}},"required":["ok","serviceId","hostname","ipv4","ipv6","rootPassword","credentialSource","guestVerified"],"additionalProperties":true},"example":{"ok":true,"serviceId":"00000000-0000-4000-8000-000000000001","hostname":"server.example.com","ipv4":"192.0.2.10","ipv6":null,"rootPassword":"<generated-password>","credentialSource":"platform_record","guestVerified":false}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.credentials.read"]},{"BearerAuth":["vps.credentials.read"]}],"operationId":"vpsCredentials"}},"/v1/vps/{serviceId}/console":{"get":{"tags":["VPS"],"summary":"Open browser console","description":"Returns an authenticated portal console URL, not a raw VNC connection or provider ticket. Browser login and service access are checked before connecting.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Console URL and requiresBrowserLogin.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"serviceId":{"type":"string"},"consoleUrl":{"type":"string"},"requiresBrowserLogin":{"type":"boolean","const":true,"enum":[true]},"transport":{"type":"string","const":"browser","enum":["browser"]}},"required":["ok","serviceId","consoleUrl","requiresBrowserLogin","transport"],"additionalProperties":true},"example":{"ok":true,"serviceId":"00000000-0000-4000-8000-000000000001","consoleUrl":"https://my.blazingfast.io/manage/vps/00000000-0000-4000-8000-000000000001/vnc","requiresBrowserLogin":true,"transport":"browser"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"vpsConsole"}},"/v1/dedicated/{serviceId}/console":{"get":{"tags":["Dedicated Servers"],"summary":"Open browser console","description":"Returns an authenticated portal console URL. No provider address or VNC password is exposed. Sign in to connect.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Console URL and requiresBrowserLogin.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"serviceId":{"type":"string"},"consoleUrl":{"type":"string"},"requiresBrowserLogin":{"type":"boolean","const":true,"enum":[true]},"transport":{"type":"string","const":"browser","enum":["browser"]}},"required":["ok","serviceId","consoleUrl","requiresBrowserLogin","transport"],"additionalProperties":true},"example":{"ok":true,"serviceId":"00000000-0000-4000-8000-000000000001","consoleUrl":"https://my.blazingfast.io/manage/dedicated/00000000-0000-4000-8000-000000000001/console","requiresBrowserLogin":true,"transport":"browser"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dedicated.read"]},{"BearerAuth":["dedicated.read"]}],"operationId":"dedicatedConsole"}},"/v1/vps/{serviceId}/reboot":{"post":{"tags":["VPS"],"summary":"Reboot server","description":"Triggers a reboot action for the selected VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Recommended stable retry key. CLI 0.1.17 makes the flag optional: an omitted key is generated once, saved locally before dispatch and printed for explicit retries. Reuse the same key and exact payload. With durable_writes enabled, the API retains the dispatch identity after its encrypted response expires in 24 hours. An unknown outcome requires inspecting service/operation state; never generate a new key to retry it. Missing keys keep legacy behavior.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Reboot action result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"actionId":"00000000-0000-4000-8000-000000000002","operation_id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","operation_url":"/v1/operations/op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"rebootVps"}},"/v1/vps/{serviceId}/start":{"post":{"tags":["VPS"],"summary":"Start server","description":"Starts a stopped VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Recommended stable retry key. CLI 0.1.17 makes the flag optional: an omitted key is generated once, saved locally before dispatch and printed for explicit retries. Reuse the same key and exact payload. With durable_writes enabled, the API retains the dispatch identity after its encrypted response expires in 24 hours. An unknown outcome requires inspecting service/operation state; never generate a new key to retry it. Missing keys keep legacy behavior.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Start action result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"actionId":"00000000-0000-4000-8000-000000000002","operation_id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","operation_url":"/v1/operations/op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsStart"}},"/v1/vps/{serviceId}/stop":{"post":{"tags":["VPS"],"summary":"Stop server","description":"Stops a running VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Recommended stable retry key. CLI 0.1.17 makes the flag optional: an omitted key is generated once, saved locally before dispatch and printed for explicit retries. Reuse the same key and exact payload. With durable_writes enabled, the API retains the dispatch identity after its encrypted response expires in 24 hours. An unknown outcome requires inspecting service/operation state; never generate a new key to retry it. Missing keys keep legacy behavior.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Stop action result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"actionId":"00000000-0000-4000-8000-000000000002","operation_id":"op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE","operation_url":"/v1/operations/op_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsStop"}},"/v1/vps/{serviceId}/password/reset":{"post":{"tags":["VPS"],"summary":"Reset root password","description":"Generates and applies a new root password, then returns it once to the caller.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Recommended stable retry key. CLI 0.1.17 makes the flag optional: an omitted key is generated once, saved locally before dispatch and printed for explicit retries. Reuse the same key and exact payload. With durable_writes enabled, the API retains the dispatch identity after its encrypted response expires in 24 hours. An unknown outcome requires inspecting service/operation state; never generate a new key to retry it. Missing keys keep legacy behavior.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Generated password and reset result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"newPassword":{"type":"string"},"credentialSynced":{"type":"boolean"},"actionId":{"type":"string"},"operation_id":{"type":"string"},"operation_url":{"type":"string"}},"required":["ok","newPassword","credentialSynced"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"newPassword":"<generated-password>","credentialSynced":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsPasswordReset"}},"/v1/vps/{serviceId}/actions/{actionId}":{"get":{"tags":["VPS"],"summary":"Check action status","description":"Polls the current state of a long-running VPS action such as power, backup, or reinstall work.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"actionId","in":"path","required":true,"description":"Action UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Action status details.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"action":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},{"type":"null"}]}},"required":["ok","action"],"additionalProperties":true},"example":{"ok":true,"action":{"id":"00000000-0000-4000-8000-000000000002","type":"start","phase":"completed","createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"vpsActionStatus"}},"/v1/vps/{serviceId}/reinstall/os":{"get":{"tags":["VPS"],"summary":"Browse reinstall images","description":"Returns operating system choices available for VPS reinstall.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Available reinstall operating systems.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"osTemplates":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"code":{"type":"string"},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"arch":{"anyOf":[{"type":"string"},{"type":"null"}]},"isDefault":{"type":"boolean"},"allowSshKeys":{"type":"boolean"}},"additionalProperties":true}}},"required":["ok","osTemplates"],"additionalProperties":true},"example":{"ok":true,"osTemplates":[{"code":"debian-13","name":"Debian","version":"13","arch":"amd64"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"vpsReinstallOs"}},"/v1/vps/{serviceId}/reinstall":{"post":{"tags":["VPS"],"summary":"Start reinstall","description":"Queues a durable reinstall and returns HTTP 202 with an action ID and operation URL. Poll the operation URL until completion, then read VPS credentials separately with vps.credentials.read. Acceptance does not mean the guest is ready.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Recommended stable retry key. CLI 0.1.17 makes the flag optional: an omitted key is generated once, saved locally before dispatch and printed for explicit retries. Reuse the same key and exact payload. With durable_writes enabled, the API retains the dispatch identity after its encrypted response expires in 24 hours. An unknown outcome requires inspecting service/operation state; never generate a new key to retry it. Missing keys keep legacy behavior.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"os_code":{"type":"string","minLength":1},"hostname":{"type":"string","minLength":1,"maxLength":255},"ssh_key_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"ssh_public_key":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"firewall_policy_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"string","const":"__DEFAULT__","enum":["__DEFAULT__"]},{"type":"null"}]},"os_name":{"type":"string","minLength":1},"os_version":{"type":"string","minLength":1},"os_arch":{"type":"string","minLength":1}},"required":["os_code"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued reinstall receipt.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true},"message":{"type":"string"},"osCode":{"type":"string"},"vmid":{"type":"number"},"newPassword":{"type":"string"},"credentialSynced":{"type":"boolean"},"serviceConfigSynced":{"type":"boolean"}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"actionId":"00000000-0000-4000-8000-000000000002","queued":true,"status":"queued","operation_id":"op_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","operation_url":"/v1/operations/op_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsReinstall"}},"/v1/vps/{serviceId}/sshkey":{"put":{"tags":["VPS"],"summary":"Update VPS SSH key","description":"Applies a public SSH key or a saved SSH key reference to the target VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ssh_key_id":{"type":"string","format":"uuid"},"public_key":{"type":"string","minLength":1,"maxLength":8192}},"additionalProperties":false}}}},"responses":{"200":{"description":"SSH key assignment result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsSshkeySet"}},"/v1/vps/{serviceId}/snapshots":{"get":{"tags":["VPS"],"summary":"Browse snapshots","description":"Returns existing snapshots for the target VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Snapshot list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"snapshots":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"running":{"type":"number"},"snaptime":{"type":"number"},"parent":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"],"additionalProperties":true}}},"required":["ok","snapshots"],"additionalProperties":true},"example":{"ok":true,"snapshots":[{"name":"before-upgrade","description":"Before upgrade","running":0}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"listVpsSnapshots"},"post":{"tags":["VPS"],"summary":"Take snapshot","description":"Creates a new snapshot for the target VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","minLength":1,"maxLength":200},"include_ram":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Snapshot creation result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true},"snapname":{"type":"string"}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"actionId":"00000000-0000-4000-8000-000000000002","snapname":"before-upgrade"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsSnapshotCreate"}},"/v1/vps/{serviceId}/snapshots/progress":{"get":{"tags":["VPS"],"summary":"Check snapshot progress","description":"Returns the current progress state for an in-flight snapshot operation.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Snapshot progress.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"inProgress":{"type":"boolean"},"actionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"action":{"anyOf":[{"type":"string","enum":["create","rollback","delete"]},{"type":"null"}]},"target":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastRequestedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastResult":{"anyOf":[{"type":"string","enum":["success","failed"]},{"type":"null"}]}},"required":["ok","inProgress","actionId","action","target","lastRequestedAt","lastResult"],"additionalProperties":true},"example":{"ok":true,"inProgress":false,"actionId":null,"lastRequestedAt":null,"lastResult":null,"action":null,"target":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"vpsSnapshotsProgress"}},"/v1/vps/{serviceId}/snapshots/{name}/rollback":{"post":{"tags":["VPS"],"summary":"Restore snapshot","description":"Restores the VPS from the named snapshot.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"name","in":"path","required":true,"description":"Snapshot name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Snapshot rollback result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"actionId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsSnapshotRollback"}},"/v1/vps/{serviceId}/snapshots/{name}":{"delete":{"tags":["VPS"],"summary":"Remove snapshot","description":"Deletes the named VPS snapshot.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"name":"name","in":"path","required":true,"description":"Snapshot name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Snapshot deletion result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"actionId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsSnapshotDelete"}},"/v1/vps/{serviceId}/backup":{"get":{"tags":["VPS"],"summary":"Check backup status","description":"Returns current backup information for the VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Current backup state.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"storageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"usedBytes":{"type":"number"},"backupCount":{"type":"number"},"poolUsedBytes":{"type":"number"},"poolBackupCount":{"type":"number"},"quota":{"type":"object","properties":{"freeGiB":{"type":"number"},"purchasedGiB":{"type":"number"},"limitBytes":{"type":"number"},"freeBytes":{"type":"number"}},"required":["freeGiB","purchasedGiB","limitBytes","freeBytes"],"additionalProperties":true},"files":{"type":"array","items":{"type":"object","properties":{"volid":{"type":"string"},"name":{"type":"string"},"size":{"type":"number"},"ctime":{"type":"number"},"format":{"type":"string"}},"additionalProperties":true}},"backup":{"$ref":"#/$defs/JsonValue"},"os":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"code":{"type":"string"},"name":{"type":"string"},"family":{"anyOf":[{"type":"string"},{"type":"null"}]},"version":{"anyOf":[{"type":"string"},{"type":"null"}]},"arch":{"anyOf":[{"type":"string"},{"type":"null"}]},"isDefault":{"type":"boolean"},"allowSshKeys":{"type":"boolean"}},"additionalProperties":true},{"type":"null"}]}},"required":["ok","storageId","usedBytes","backupCount","poolUsedBytes","poolBackupCount","quota","files","backup","os"],"additionalProperties":true,"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"ok":true,"storageId":"example-backup-storage","usedBytes":0,"backupCount":0,"poolUsedBytes":0,"poolBackupCount":0,"quota":{"freeGiB":10,"purchasedGiB":0,"limitBytes":10737418240,"freeBytes":10737418240},"files":[],"backup":null,"os":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"getVpsBackup"},"delete":{"tags":["VPS"],"summary":"Delete backup files","description":"Deletes the current backup record or configured backup object for the VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Backup deletion result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"deleted":{"type":"number"}},"required":["ok","deleted"],"additionalProperties":true},"example":{"ok":true,"deleted":1}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsBackupDelete"}},"/v1/vps/{serviceId}/backup/schedule":{"get":{"tags":["VPS"],"summary":"View backup schedule","description":"Returns current backup schedule settings for the VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Backup schedule settings.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"schedule":{"type":"object","properties":{"enabled":{"type":"boolean"},"cadence":{"type":"string"},"atHour":{"type":"number"},"atMinute":{"type":"number"},"dayOfWeek":{"type":"number"},"timezone":{"type":"string"}},"required":["enabled"],"additionalProperties":true}},"required":["ok","schedule"],"additionalProperties":true},"example":{"ok":true,"schedule":{"enabled":false}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"getVpsBackupSchedule"},"put":{"tags":["VPS"],"summary":"Change backup schedule","description":"Creates or updates the backup schedule for the VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"cadence":{"type":"string","enum":["daily","weekly"]},"at_hour":{"type":"integer","minimum":0,"maximum":23},"at_minute":{"type":"integer","minimum":0,"maximum":59},"day_of_week":{"type":"integer","minimum":0,"maximum":6}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated backup schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"schedule":{"type":"object","properties":{"enabled":{"type":"boolean"},"cadence":{"type":"string"},"atHour":{"type":"number"},"atMinute":{"type":"number"},"dayOfWeek":{"type":"number"},"timezone":{"type":"string"}},"required":["enabled"],"additionalProperties":true}},"required":["ok","schedule"],"additionalProperties":true},"example":{"ok":true,"schedule":{"enabled":false}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsBackupSchedulePut"}},"/v1/vps/{serviceId}/backup/run":{"post":{"tags":["VPS"],"summary":"Start backup","description":"Starts an on-demand backup for the selected VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Backup run result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"actionId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsBackupRun"}},"/v1/vps/{serviceId}/backup/progress":{"get":{"tags":["VPS"],"summary":"Check backup progress","description":"Returns current progress for an active backup job.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Backup progress.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"running":{"type":"boolean"},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"phase":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"action":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},{"type":"null"}]},"actionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"target":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true,"inProgress":false,"actionId":null,"lastRequestedAt":null,"lastResult":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"vpsBackupProgress"}},"/v1/vps/{serviceId}/backup/cancel":{"post":{"tags":["VPS"],"summary":"Cancel backup run","description":"Requests cancellation of an active backup job.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Backup cancellation result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"cancelled":{"type":"boolean"}},"required":["ok","cancelled"],"additionalProperties":true},"example":{"ok":true,"cancelled":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsBackupCancel"}},"/v1/vps/{serviceId}/backup/restore":{"post":{"tags":["VPS"],"summary":"Start backup restore","description":"Starts a restore from the current or selected VPS backup artifact.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"in":"header","name":"x-bf-response-format","required":false,"schema":{"type":"string","enum":["operation"]},"description":"Opt into the canonical Operation receipt for this tracked write. Requires canonical_operation_responses enabled. Omit for the legacy response. Retried requests may replay their initial response format; use its operation_id or operation.id to poll."},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"auto_start":{"type":"boolean"},"file":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Backup restore result.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"actionId":{"type":"string"},"operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"operation_id":{"type":"string"},"operation_url":{"type":"string"},"status":{"type":"string"},"phase":{"type":"string"},"already":{"type":"boolean"},"queued":{"type":"boolean"},"task":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"status":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"operation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["deployment","vps","dedicated"]},"action":{"type":"string"},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled","unknown"]},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"service_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"result":{"anyOf":[{"anyOf":[{"type":"object","properties":{"service_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"invoice_id":{"type":"string","format":"uuid"}},"required":["service_ids"],"additionalProperties":false},{"type":"object","properties":{"service_id":{"type":"string","format":"uuid"},"os":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"snapshot_name":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9._:-]+$"},"power_state":{"type":"string","enum":["running","stopped"]}},"required":["service_id"],"additionalProperties":false}]},{"type":"null"}]}},"required":["id","kind","action","status","done","progress","stage","created_at","updated_at","service_ids","error"],"additionalProperties":false},"links":{"type":"object","properties":{"operation":{"type":"string","pattern":"^\\/v1\\/operations\\/op_[A-Za-z0-9_-]+$"},"service":{"type":"string","pattern":"^\\/v1\\/services\\/[0-9a-f-]{36}$"},"invoice":{"type":"string","pattern":"^\\/v1\\/billing\\/invoices\\/[0-9a-f-]{36}$"},"order":{"type":"string","pattern":"^\\/v1\\/billing\\/orders\\/[0-9a-f-]{36}$"}},"required":["operation"],"additionalProperties":false}},"required":["ok","operation"],"additionalProperties":false}],"description":"Legacy response by default; x-bf-response-format: operation opts into the canonical receipt when durable operations are enabled. Retries retain the initial cached response format."},"example":{"ok":true,"actionId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsBackupRestore"}},"/v1/vps/{serviceId}/backup/restore/progress":{"get":{"tags":["VPS"],"summary":"Check restore progress","description":"Returns progress for an active backup restore.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Backup restore progress.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"running":{"type":"boolean"},"done":{"type":"boolean"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"phase":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"action":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"phase":{"type":"string"},"progress":{"anyOf":[{"type":"number"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"done":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},{"type":"null"}]},"actionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"target":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true,"inProgress":false,"actionId":null,"lastRequestedAt":null,"lastResult":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"vpsBackupRestoreProgress"}},"/v1/dns/templates":{"get":{"tags":["DNS"],"summary":"Browse DNS templates","description":"Returns reusable DNS templates that can be applied during zone creation.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"DNS template list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"values":{"type":"array","items":{"type":"string"}},"proxied":{"type":"boolean"},"originValues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"protection":{"type":"boolean"}},"required":["name","type","ttl","values"],"additionalProperties":true}},"rrsets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"records":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"disabled":{"type":"boolean"}},"required":["content"],"additionalProperties":true}},"changetype":{"type":"string"},"comments":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"account":{"type":"string"},"modified_at":{"type":"number"}},"additionalProperties":true}}},"required":["name","type","ttl","records"],"additionalProperties":true}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"system":{"type":"boolean"},"visibility":{"type":"string"},"isHidden":{"type":"boolean"}},"required":["id","name"],"additionalProperties":true}}},"required":["ok","templates"],"additionalProperties":true},"example":{"ok":true,"templates":[{"id":"00000000-0000-4000-8000-000000000001","name":"Example template","createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z","system":false,"visibility":"private","isHidden":false}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"listDnsTemplates"},"post":{"tags":["DNS"],"summary":"Save DNS template","description":"Creates a reusable DNS template from a zone-file fragment.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"zone_file":{"type":"string","minLength":1,"maxLength":500000}},"required":["name","zone_file"],"additionalProperties":false}}}},"responses":{"200":{"description":"Created DNS template.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"values":{"type":"array","items":{"type":"string"}},"proxied":{"type":"boolean"},"originValues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"protection":{"type":"boolean"}},"required":["name","type","ttl","values"],"additionalProperties":true}},"rrsets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"records":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"disabled":{"type":"boolean"}},"required":["content"],"additionalProperties":true}},"changetype":{"type":"string"},"comments":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"account":{"type":"string"},"modified_at":{"type":"number"}},"additionalProperties":true}}},"required":["name","type","ttl","records"],"additionalProperties":true}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"system":{"type":"boolean"},"visibility":{"type":"string"},"isHidden":{"type":"boolean"}},"required":["id","name"],"additionalProperties":true}},"required":["ok","template"],"additionalProperties":true},"example":{"ok":true,"template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example template","zoneFile":"@ 300 IN A 192.0.2.10","createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z","system":false,"visibility":"private"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsTemplateCreate"}},"/v1/dns/templates/{id}":{"get":{"tags":["DNS"],"summary":"Open DNS template","description":"Returns an owned or public system template by name or UUID. Name matching is case-insensitive and checks your templates first; public system defaults are a fallback. Other accounts are excluded. Only duplicate names within the selected scope return template_identifier_ambiguous. Edit/delete routes still require UUIDs.","parameters":[{"name":"id","in":"path","required":true,"description":"Your template name (cpanel2 or My template) or UUID; URL-encode spaces and Unicode.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"DNS template detail.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"values":{"type":"array","items":{"type":"string"}},"proxied":{"type":"boolean"},"originValues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"protection":{"type":"boolean"}},"required":["name","type","ttl","values"],"additionalProperties":true}},"rrsets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"records":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"disabled":{"type":"boolean"}},"required":["content"],"additionalProperties":true}},"changetype":{"type":"string"},"comments":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"account":{"type":"string"},"modified_at":{"type":"number"}},"additionalProperties":true}}},"required":["name","type","ttl","records"],"additionalProperties":true}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"system":{"type":"boolean"},"visibility":{"type":"string"},"isHidden":{"type":"boolean"}},"required":["id","name"],"additionalProperties":true}},"required":["ok","template"],"additionalProperties":true},"example":{"ok":true,"template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example template","zoneFile":"@ 300 IN A 192.0.2.10","createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z","system":false,"visibility":"private"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"getDnsTemplate"},"patch":{"tags":["DNS"],"summary":"Edit DNS template","description":"Updates the name or zone-file content of an existing template.","parameters":[{"name":"id","in":"path","required":true,"description":"DNS template UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"zone_file":{"type":"string","minLength":1,"maxLength":500000}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated DNS template.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"values":{"type":"array","items":{"type":"string"}},"proxied":{"type":"boolean"},"originValues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"protection":{"type":"boolean"}},"required":["name","type","ttl","values"],"additionalProperties":true}},"rrsets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"records":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"disabled":{"type":"boolean"}},"required":["content"],"additionalProperties":true}},"changetype":{"type":"string"},"comments":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"account":{"type":"string"},"modified_at":{"type":"number"}},"additionalProperties":true}}},"required":["name","type","ttl","records"],"additionalProperties":true}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"system":{"type":"boolean"},"visibility":{"type":"string"},"isHidden":{"type":"boolean"}},"required":["id","name"],"additionalProperties":true}},"required":["ok","template"],"additionalProperties":true},"example":{"ok":true,"template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example template","zoneFile":"@ 300 IN A 192.0.2.10","createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z","system":false,"visibility":"private"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsTemplateUpdate"},"delete":{"tags":["DNS"],"summary":"Remove DNS template","description":"Deletes a DNS template.","parameters":[{"name":"id","in":"path","required":true,"description":"DNS template UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"DNS template deletion result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsTemplateDelete"}},"/v1/dns/zones":{"get":{"tags":["DNS"],"summary":"Browse DNS zones","description":"Returns owned customer DNS zones. Use view=summary for a lightweight, read-only inventory with name search before pagination; it returns total, limit, offset and zones. The default legacy view remains unchanged. Summary results sort by zone name and do not contact nameservers or change billing links.","parameters":[{"name":"q","in":"query","required":false,"description":"Optional zone name search filter.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Optional legacy-view sort key; summary always sorts by name.","schema":{"type":"string"}},{"name":"view","in":"query","required":false,"description":"Use summary for lightweight paginated zone cards.","schema":{"type":"string","enum":["summary"]}},{"name":"limit","in":"query","description":"Summary only: maximum zones returned.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","description":"Summary only: number of matching zones to skip.","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"DNS zone list. Summary adds total, limit and offset; zones contain name, status and createdAt only.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"zones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"}},"required":["name","status","createdAt"],"additionalProperties":true}}},"required":["ok","zones"],"additionalProperties":true},"example":{"ok":true,"zones":[{"name":"example.com","status":"active","createdAt":"2026-10-01T00:00:00.000Z"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"listDnsZones"},"post":{"tags":["DNS"],"summary":"Create or preview DNS zone","description":"Body: name; at most one of templateId UUID, zoneFile text (100000 characters max), or records array ({name,type,ttl,values}, max 200 sets, 50 values/set, TTL 1–86400 seconds). Omit all sources for an empty zone. dryRun:true validates and returns records/notes without creating or reserving a zone; requires an existing active DNS service. Use separate Idempotency-Keys for preview and creation. Platform apex NS replaces imported NS and SOA is managed automatically. Zone files support IN records, relative names, $ORIGIN, $TTL and multiline records; external includes/generation and foreign owners are rejected. Resolve template names via GET /v1/dns/templates and inspect their details; templates must be owned or public. Existing zones are never overwritten. A records may be proxied by the existing protection policy. Does not register domains or change registrar delegation.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253},"template_id":{"type":"string","format":"uuid"},"zone_file":{"type":"string","minLength":1,"maxLength":100000},"records":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SOA","PTR","SRV","CAA","SSHFP","TLSA","NAPTR","LOC","DS","DNSKEY"]},"ttl":{"type":"integer","minimum":1,"maximum":86400},"values":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096},"minItems":1,"maxItems":50}},"required":["name","type","values"],"additionalProperties":false},"maxItems":200},"dry_run":{"type":"boolean"}},"required":["name"],"additionalProperties":false,"description":"At most one of templateId, zoneFile or records. Omit all three for an empty zone. Names and record ownership are validated by the backend."}}}},"responses":{"200":{"description":"Created zone, or normalized records and notes for dryRun.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"zoneId":{"type":"string"},"zone":{"$ref":"#/$defs/JsonValue"}},"required":["ok","zoneId","zone"],"additionalProperties":true},{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"dryRun":{"type":"boolean","const":true,"enum":[true]},"name":{"type":"string"},"records":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"values":{"type":"array","items":{"type":"string"}},"proxied":{"type":"boolean"},"originValues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"protection":{"type":"boolean"}},"required":["name","type","ttl","values"],"additionalProperties":true}},"notes":{"type":"array","items":{"type":"string"}}},"required":["ok","dryRun","name","records","notes"],"additionalProperties":true}],"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"ok":true,"zoneId":"00000000-0000-4000-8000-000000000001","zone":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"createDnsZone"}},"/v1/dns/zones/{name}":{"get":{"tags":["DNS"],"summary":"Open DNS zone","description":"Returns one DNS zone and its customer-facing detail view.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"DNS zone detail.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"domain":{"type":"object","properties":{"name":{"type":"string"},"zoneId":{"type":"string"},"status":{"type":"string"},"adminLock":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["name","zoneId","status","adminLock","createdAt","updatedAt"],"additionalProperties":true}},"required":["ok","domain"],"additionalProperties":true},"example":{"ok":true,"domain":{"name":"example.com","zoneId":"00000000-0000-4000-8000-000000000001","status":"active","adminLock":false,"createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"getDnsZone"},"delete":{"tags":["DNS"],"summary":"Remove DNS zone","description":"Deletes a DNS zone.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"DNS zone deletion result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsZoneDelete"}},"/v1/dns/zones/{name}/records/simple":{"get":{"tags":["DNS"],"summary":"Browse simple records","description":"Returns simplified DNS records for a zone.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Simple DNS records.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"service":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"suspendedReason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","suspendedReason"],"additionalProperties":true},"records":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"values":{"type":"array","items":{"type":"string"}},"proxied":{"type":"boolean"},"originValues":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"protection":{"type":"boolean"}},"required":["name","type","ttl","values"],"additionalProperties":true}}},"required":["ok","service","records"],"additionalProperties":true},"example":{"ok":true,"service":{"id":"00000000-0000-4000-8000-000000000001","status":"active","suspendedReason":null},"records":[{"name":"@","type":"A","ttl":300,"values":["192.0.2.10"],"proxied":false,"originValues":null,"protection":false,"wafEligible":false,"protectionMode":"none"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"listDnsRecordsSimple"},"post":{"tags":["DNS"],"summary":"Save simple record","description":"Creates or replaces a simplified DNS record set.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["append","replace"]},"record":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253},"type":{"type":"string","minLength":1,"maxLength":16},"ttl":{"type":"integer","minimum":1,"maximum":86400},"values":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50},"protect":{"type":"boolean"}},"required":["name","type","values"],"additionalProperties":false}},"required":["record"],"additionalProperties":false}}}},"responses":{"200":{"description":"Simple record upsert result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"appliedTo":{"type":"string"},"changeId":{"type":"string"}},"required":["ok","appliedTo"],"additionalProperties":true},"example":{"ok":true,"appliedTo":"powerdns","changeId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsRecordsSimpleSet"},"delete":{"tags":["DNS"],"summary":"Remove simple record","description":"Deletes a simplified DNS record set from the zone.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253},"type":{"type":"string","minLength":1,"maxLength":16}},"required":["name","type"],"additionalProperties":false}}}},"responses":{"200":{"description":"Simple record deletion result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"appliedTo":{"type":"string"},"changeId":{"type":"string"}},"required":["ok","appliedTo"],"additionalProperties":true},"example":{"ok":true,"appliedTo":"powerdns","changeId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsRecordsSimpleDelete"}},"/v1/dns/zones/{name}/records":{"get":{"tags":["DNS"],"summary":"Browse raw rrsets","description":"Returns advanced rrset data for customers that need lower-level DNS editing.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Raw rrset list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"source":{"type":"string"},"rrsets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"ttl":{"type":"number"},"records":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"disabled":{"type":"boolean"}},"required":["content"],"additionalProperties":true}},"changetype":{"type":"string"},"comments":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"account":{"type":"string"},"modified_at":{"type":"number"}},"additionalProperties":true}}},"required":["name","type","ttl","records"],"additionalProperties":true}}},"required":["ok","source","rrsets"],"additionalProperties":true},"example":{"ok":true,"source":"powerdns","rrsets":[{"name":"example.com.","type":"A","ttl":300,"records":[{"content":"192.0.2.10","disabled":false}]}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.read"]},{"BearerAuth":["dns.read"]}],"operationId":"getDnsRrsets"},"patch":{"tags":["DNS"],"summary":"Apply rrset changes","description":"Applies advanced rrset changes using REPLACE or DELETE style operations.","parameters":[{"name":"name","in":"path","required":true,"description":"Zone or domain name.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rrsets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253},"type":{"type":"string","minLength":1,"maxLength":16},"ttl":{"type":"integer","minimum":0,"maximum":2147483647},"changetype":{"type":"string","enum":["REPLACE","DELETE"]},"records":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"disabled":{"type":"boolean"}},"required":["content"],"additionalProperties":false}}},"required":["name","type"],"additionalProperties":false}}},"required":["rrsets"],"additionalProperties":false}}}},"responses":{"200":{"description":"Raw rrset patch result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"appliedTo":{"type":"string"},"changeId":{"type":"string"}},"required":["ok","appliedTo"],"additionalProperties":true},"example":{"ok":true,"appliedTo":"powerdns","changeId":"00000000-0000-4000-8000-000000000002"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["dns.write"]},{"BearerAuth":["dns.write"]}],"operationId":"dnsRrsetsPatch"}},"/v1/domains/tlds":{"get":{"tags":["Domains"],"summary":"Browse supported TLDs","description":"Returns customer-searchable TLD data for domain purchase and transfer flows.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Supported TLD list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"tlds":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"name":{"type":"string"},"tld":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"dnssec":{"type":"boolean"}},"required":["name"],"additionalProperties":true}]}}},"required":["ok","tlds"],"additionalProperties":true},"example":{"ok":true,"tlds":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"domainTlds"}},"/v1/domains/check":{"post":{"tags":["Domains"],"summary":"Check availability","description":"Checks one or more domains for availability.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"string","minLength":3},"minItems":1,"maxItems":50}},"required":["domains"],"additionalProperties":false}}}},"responses":{"200":{"description":"Availability results.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"available":{"type":"boolean"},"premium":{"type":"boolean"},"price":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"renewalPrice":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"renewalCurrency":{"anyOf":[{"type":"string"},{"type":"null"}]},"transferPrice":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"transferCurrency":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_private_whois_allowed":{"type":"boolean"}},"required":["domain"],"additionalProperties":true}},"hasMore":{"type":"boolean"},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"}},"required":["ok","results"],"additionalProperties":true},"example":{"ok":true,"results":[{"domain":"example.com","available":false,"premium":false,"price":null,"renewalPrice":null,"renewalCurrency":null,"currency":null,"transferPrice":null,"transferCurrency":null,"is_private_whois_allowed":false}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"domainCheck"}},"/v1/domains/search":{"post":{"tags":["Domains"],"summary":"Search domains","description":"Searches available domains by keyword with paging support.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":63},"page":{"type":"integer","minimum":0,"default":0},"page_size":{"type":"integer","minimum":5,"maximum":50,"default":20}},"required":["keyword"],"additionalProperties":false}}}},"responses":{"200":{"description":"Domain search results.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"available":{"type":"boolean"},"premium":{"type":"boolean"},"price":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"renewalPrice":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"renewalCurrency":{"anyOf":[{"type":"string"},{"type":"null"}]},"transferPrice":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"transferCurrency":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_private_whois_allowed":{"type":"boolean"}},"required":["domain"],"additionalProperties":true}},"hasMore":{"type":"boolean"},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"}},"required":["ok","results"],"additionalProperties":true},"example":{"ok":true,"results":[],"hasMore":false,"page":0,"total":0}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"domainSearch"}},"/v1/domains/suggest":{"post":{"tags":["Domains"],"summary":"Suggest domains","description":"Returns suggestion-style domain options derived from a keyword.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":253},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["keyword"],"additionalProperties":false}}}},"responses":{"200":{"description":"Domain suggestions.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"suggestions":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"domain":{"type":"string"},"available":{"type":"boolean"},"premium":{"type":"boolean"},"price":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"renewalPrice":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"renewalCurrency":{"anyOf":[{"type":"string"},{"type":"null"}]},"transferPrice":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"}]},{"type":"null"}]},"transferCurrency":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_private_whois_allowed":{"type":"boolean"}},"required":["domain"],"additionalProperties":true}]}}},"required":["ok","suggestions"],"additionalProperties":true},"example":{"ok":true,"suggestions":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"domainSuggest"}},"/v1/domains":{"get":{"tags":["Domains"],"summary":"Browse domains","description":"Returns domain services already attached to the customer account.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Customer domain service list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"domains":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"serviceId":{"type":"string"}},"required":["id"],"additionalProperties":true}}},"required":["ok","domains"],"additionalProperties":true},"example":{"ok":true,"domains":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"listDomains"}},"/v1/domains/{serviceId}":{"get":{"tags":["Domains"],"summary":"Open domain detail","description":"Returns the current detail view for one domain service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Domain service detail.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"service_id":{"type":"string"},"domain_name":{"type":"string"},"service":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"productName":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv6":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"domain":{"anyOf":[{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}},{"type":"null"}]}},"required":["ok","service_id","domain_name","service","domain"],"additionalProperties":true,"$defs":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/$defs/JsonValue"}}]}}},"example":{"ok":true,"service_id":"00000000-0000-4000-8000-000000000001","domain_name":"example.com","service":{"id":"00000000-0000-4000-8000-000000000001","status":"active"},"domain":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"getDomain"}},"/v1/domains/{serviceId}/status":{"get":{"tags":["Domains"],"summary":"Check domain status","description":"Returns current domain lifecycle or verification status for one domain service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Domain status details.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"normalizedStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_lockable":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"is_locked":{"type":"boolean"},"is_private_whois_enabled":{"type":"boolean"},"is_private_whois_allowed":{"type":"boolean"},"is_abusive":{"type":"boolean"},"is_deleted":{"type":"boolean"},"can_renew":{"type":"boolean"},"delete_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"soft_quarantine_expiry_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"restorable_until":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiration_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"renewal_date":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ok","status"],"additionalProperties":true},"example":{"ok":true,"status":null}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"domainStatus"}},"/v1/domains/{serviceId}/nameservers":{"put":{"tags":["Domains"],"summary":"Update nameservers","description":"Replaces nameserver configuration for a domain service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nameservers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"ip":{"type":"string"}},"required":["name"],"additionalProperties":false},"minItems":2,"maxItems":13}},"required":["nameservers"],"additionalProperties":false}}}},"responses":{"200":{"description":"Nameserver update result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.write"]},{"BearerAuth":["domains.write"]}],"operationId":"domainNameserversUpdate"}},"/v1/domains/{serviceId}/lock":{"put":{"tags":["Domains"],"summary":"Change transfer lock","description":"Enables or disables the domain lock state.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locked":{"type":"boolean"}},"required":["locked"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated domain lock state.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"locked":{"type":"boolean"}},"required":["ok","locked"],"additionalProperties":true},"example":{"ok":true,"locked":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.write"]},{"BearerAuth":["domains.write"]}],"operationId":"domainLock"}},"/v1/domains/{serviceId}/whois-privacy":{"put":{"tags":["Domains"],"summary":"Change WHOIS privacy","description":"Enables or disables WHOIS privacy when the domain and registrar flow allow it.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated WHOIS privacy state.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"enabled":{"type":"boolean"}},"required":["ok","enabled"],"additionalProperties":true},"example":{"ok":true,"enabled":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.write"]},{"BearerAuth":["domains.write"]}],"operationId":"domainWhoisPrivacy"}},"/v1/domains/{serviceId}/auth-code":{"get":{"tags":["Domains"],"summary":"View transfer code","description":"Returns the current transfer authorization code when available.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Transfer auth code.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"auth_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ok","auth_code"],"additionalProperties":true},"example":{"ok":true,"auth_code":"<transfer-code>"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"domainAuthCode"}},"/v1/domains/{serviceId}/transfer-status":{"get":{"tags":["Domains"],"summary":"Check transfer status","description":"Returns the current transfer state for a domain service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Transfer status details.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"transferStatus":{"type":"string"},"isActive":{"type":"boolean"}},"required":["ok","transferStatus","isActive"],"additionalProperties":true},"example":{"ok":true,"transferStatus":"unknown","isActive":false}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"domainTransferStatus"}},"/v1/domains/{serviceId}/resend-verification":{"post":{"tags":["Domains"],"summary":"Resend verification","description":"Resends a verification step for a domain when the registrar flow requires it.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Verification resend result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.write"]},{"BearerAuth":["domains.write"]}],"operationId":"domainResendVerification"}},"/v1/domains/{serviceId}/contacts":{"put":{"tags":["Domains"],"summary":"Assign contacts","description":"Assigns registrant, admin, tech, or billing contacts to a domain service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Your registered domain name (example.com) or service UUID. Names are case-insensitive and normalized to IDNA ASCII; one trailing dot is accepted. Exact matches are restricted to your non-terminated domain services. Multiple matches return domain_identifier_ambiguous; use the UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"type":"object","properties":{"registrant":{"type":"string","format":"uuid"},"admin":{"type":"string","format":"uuid"},"tech":{"type":"string","format":"uuid"},"billing":{"type":"string","format":"uuid"}},"additionalProperties":false}},"required":["contact_ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated domain contacts.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.write"]},{"BearerAuth":["domains.write"]}],"operationId":"domainAssignContacts"}},"/v1/domains/contacts":{"get":{"tags":["Domains"],"summary":"Browse domain contacts","description":"Returns saved domain contact records available for assignment.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Domain contact list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"companyName":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"phone":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}}},"required":["ok","contacts"],"additionalProperties":true},"example":{"ok":true,"contacts":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.read"]},{"BearerAuth":["domains.read"]}],"operationId":"listDomainContacts"},"post":{"tags":["Domains"],"summary":"Save domain contact","description":"Creates a reusable domain contact record.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","minLength":1},"last_name":{"type":"string","minLength":1},"company_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":1},"address":{"type":"object","properties":{"street":{"type":"string","minLength":1},"number":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"zipcode":{"type":"string","minLength":1},"state":{"type":"string"},"country":{"type":"string","maxLength":2,"minLength":2}},"required":["street","number","city","zipcode","country"],"additionalProperties":false},"tag":{"type":"string"},"vat":{"type":"string","maxLength":30,"pattern":"^[A-Za-z0-9\\-. ]*$"},"passport_number":{"type":"string","maxLength":30,"pattern":"^[A-Za-z0-9\\- ]*$"},"tax_id":{"type":"string","maxLength":30,"pattern":"^[A-Za-z0-9\\-. ]*$"},"additional_data":{"type":"object","additionalProperties":{}}},"required":["first_name","last_name","email","phone","address"],"additionalProperties":false}}}},"responses":{"200":{"description":"Created domain contact.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"contact":{"type":"object","properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"companyName":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"phone":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true},"handle":{"type":"string"}},"required":["ok","contact"],"additionalProperties":true},"example":{"ok":true,"contact":{"id":"00000000-0000-4000-8000-000000000001","firstName":"Example","lastName":"Customer","country":"NL"},"handle":"EXAMPLE-HANDLE"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.write"]},{"BearerAuth":["domains.write"]}],"operationId":"domainContactCreate"}},"/v1/domains/contacts/{contactId}":{"put":{"tags":["Domains"],"summary":"Edit domain contact","description":"Replaces a saved domain contact record.","parameters":[{"name":"contactId","in":"path","required":true,"description":"Domain contact UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","minLength":1},"last_name":{"type":"string","minLength":1},"company_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":1},"address":{"type":"object","properties":{"street":{"type":"string","minLength":1},"number":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"zipcode":{"type":"string","minLength":1},"state":{"type":"string"},"country":{"type":"string","maxLength":2,"minLength":2}},"required":["street","number","city","zipcode","country"],"additionalProperties":false},"tag":{"type":"string"},"vat":{"type":"string","maxLength":30,"pattern":"^[A-Za-z0-9\\-. ]*$"},"passport_number":{"type":"string","maxLength":30,"pattern":"^[A-Za-z0-9\\- ]*$"},"tax_id":{"type":"string","maxLength":30,"pattern":"^[A-Za-z0-9\\-. ]*$"},"additional_data":{"type":"object","additionalProperties":{}}},"required":["first_name","last_name","email","phone","address"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated domain contact.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"contact":{"type":"object","properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"companyName":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"phone":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":true}},"required":["ok","contact"],"additionalProperties":true},"example":{"ok":true,"contact":{"id":"00000000-0000-4000-8000-000000000001","firstName":"Example","lastName":"Customer","country":"NL"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.write"]},{"BearerAuth":["domains.write"]}],"operationId":"domainContactUpdate"},"delete":{"tags":["Domains"],"summary":"Remove domain contact","description":"Deletes a saved domain contact record.","parameters":[{"name":"contactId","in":"path","required":true,"description":"Domain contact UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Domain contact deletion result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["domains.write"]},{"BearerAuth":["domains.write"]}],"operationId":"domainContactDelete"}},"/v1/ssh/keys":{"get":{"tags":["SSH"],"summary":"Browse SSH keys","description":"Returns saved SSH keys for the customer account.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"SSH key list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"fingerprint":{"type":"string"},"isPrimary":{"type":"boolean"},"hasPrivateKey":{"type":"boolean"},"type":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true}}},"required":["ok","keys"],"additionalProperties":true},"example":{"ok":true,"keys":[{"id":"00000000-0000-4000-8000-000000000001","name":"Example key","algorithm":"ed25519","fingerprint":"SHA256:example-fingerprint","isPrimary":false,"hasPrivateKey":false,"createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.read"]},{"BearerAuth":["ssh.read"]}],"operationId":"listSshKeys"},"post":{"tags":["SSH"],"summary":"Save SSH key","description":"Stores a new public SSH key for later provisioning or VPS assignment.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"public_key":{"type":"string","minLength":1,"maxLength":8192}},"required":["name","public_key"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created SSH key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"fingerprint":{"type":"string"},"isPrimary":{"type":"boolean"},"hasPrivateKey":{"type":"boolean"},"type":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true}},"required":["ok","key"],"additionalProperties":true},"example":{"ok":true,"key":{"id":"00000000-0000-4000-8000-000000000001","name":"Example key","algorithm":"ed25519","fingerprint":"SHA256:example-fingerprint","isPrimary":false,"hasPrivateKey":false,"createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.write"]},{"BearerAuth":["ssh.write"]}],"operationId":"sshKeyImport"}},"/v1/ssh/keys/generate":{"post":{"tags":["SSH"],"summary":"Generate SSH keypair","description":"Generates a new SSH keypair and returns the private key once.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"algorithm":{"type":"string","minLength":1},"format":{"type":"string","minLength":1},"passphrase":{"type":"string","minLength":8,"maxLength":200}},"required":["name","passphrase"],"additionalProperties":false}}}},"responses":{"201":{"description":"Generated SSH keypair.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"fingerprint":{"type":"string"},"isPrimary":{"type":"boolean"},"hasPrivateKey":{"type":"boolean"},"type":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true},"privateKey":{"type":"string"}},"required":["ok","key","privateKey"],"additionalProperties":true},"example":{"ok":true,"key":{"id":"00000000-0000-4000-8000-000000000001","name":"Example key","algorithm":"ed25519","fingerprint":"SHA256:example-fingerprint","isPrimary":false,"hasPrivateKey":true,"createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"},"privateKey":"<private-key-returned-once>"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.write"]},{"BearerAuth":["ssh.write"]}],"operationId":"sshKeyGenerate"}},"/v1/ssh/keys/{id}/public":{"get":{"tags":["SSH"],"summary":"View public key","description":"Returns the public portion of one saved SSH key.","parameters":[{"name":"id","in":"path","required":true,"description":"SSH key UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Public SSH key material.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"id":{"type":"string"},"publicKey":{"type":"string"}},"required":["ok","id","publicKey"],"additionalProperties":true},"example":{"ok":true,"id":"00000000-0000-4000-8000-000000000001","publicKey":"<public-ssh-key>"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.read"]},{"BearerAuth":["ssh.read"]}],"operationId":"sshKeyPublic"}},"/v1/ssh/keys/{id}/private":{"post":{"tags":["SSH"],"summary":"Export private key","description":"Exports the private portion of a generated SSH key when the correct passphrase is supplied.","parameters":[{"name":"id","in":"path","required":true,"description":"SSH key UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"passphrase":{"type":"string","minLength":1,"maxLength":200}},"required":["passphrase"],"additionalProperties":false}}}},"responses":{"200":{"description":"Private SSH key export result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"privateKey":{"type":"string"}},"required":["ok","privateKey"],"additionalProperties":true},"example":{"ok":true,"privateKey":"<private-key>"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.write"]},{"BearerAuth":["ssh.write"]}],"operationId":"sshKeyPrivateExport"}},"/v1/ssh/keys/{id}":{"put":{"tags":["SSH"],"summary":"Edit SSH key","description":"Replaces the name and public key material of an existing SSH key record.","parameters":[{"name":"id","in":"path","required":true,"description":"SSH key UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"public_key":{"type":"string","minLength":1,"maxLength":8192}},"required":["name","public_key"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated SSH key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"fingerprint":{"type":"string"},"isPrimary":{"type":"boolean"},"hasPrivateKey":{"type":"boolean"},"type":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true}},"required":["ok","key"],"additionalProperties":true},"example":{"ok":true,"key":{"id":"00000000-0000-4000-8000-000000000001","name":"Example key","algorithm":"ed25519","fingerprint":"SHA256:example-fingerprint","isPrimary":false,"hasPrivateKey":false,"createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.write"]},{"BearerAuth":["ssh.write"]}],"operationId":"sshKeyUpdate"},"patch":{"tags":["SSH"],"summary":"Rename SSH key","description":"Changes only the display name of an SSH key.","parameters":[{"name":"id","in":"path","required":true,"description":"SSH key UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Renamed SSH key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"fingerprint":{"type":"string"},"isPrimary":{"type":"boolean"},"hasPrivateKey":{"type":"boolean"},"type":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id"],"additionalProperties":true}},"required":["ok","key"],"additionalProperties":true},"example":{"ok":true,"key":{"id":"00000000-0000-4000-8000-000000000001","name":"Example key","algorithm":"ed25519","fingerprint":"SHA256:example-fingerprint","isPrimary":false,"hasPrivateKey":false,"createdAt":"2026-10-01T00:00:00.000Z","updatedAt":"2026-10-01T00:00:00.000Z"}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.write"]},{"BearerAuth":["ssh.write"]}],"operationId":"sshKeyRename"},"delete":{"tags":["SSH"],"summary":"Remove SSH key","description":"Deletes an SSH key from the customer account.","parameters":[{"name":"id","in":"path","required":true,"description":"SSH key UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"SSH key deletion result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.write"]},{"BearerAuth":["ssh.write"]}],"operationId":"sshKeyDelete"}},"/v1/ssh/keys/{id}/primary":{"put":{"tags":["SSH"],"summary":"Set primary SSH key","description":"Marks one SSH key as the primary default choice for relevant workflows.","parameters":[{"name":"id","in":"path","required":true,"description":"SSH key UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Updated primary SSH key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["ssh.write"]},{"BearerAuth":["ssh.write"]}],"operationId":"sshKeySetPrimary"}},"/v1/firewall/policies":{"get":{"tags":["Firewall"],"summary":"Browse firewall policies","description":"Returns reusable firewall policies available to the customer.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Firewall policy list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"policies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"policyIn":{"type":"string"},"policyOut":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"type":{"type":"string"},"action":{"type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"dest":{"anyOf":[{"type":"string"},{"type":"null"}]},"proto":{"anyOf":[{"type":"string"},{"type":"null"}]},"sport":{"anyOf":[{"type":"string"},{"type":"null"}]},"dport":{"anyOf":[{"type":"string"},{"type":"null"}]},"comment":{"anyOf":[{"type":"string"},{"type":"null"}]},"enable":{"anyOf":[{"type":"boolean"},{"type":"number"}]},"position":{"type":"number"}},"additionalProperties":true}}},"required":["id","name"],"additionalProperties":true}}},"required":["ok","policies"],"additionalProperties":true},"example":{"ok":true,"policies":[{"id":"00000000-0000-4000-8000-000000000001","name":"Example policy","description":null,"isPrimary":false,"policyIn":"DROP","policyOut":"ACCEPT","rules":[]}]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["firewall.read"]},{"BearerAuth":["firewall.read"]}],"operationId":"listFirewallPolicies"},"post":{"tags":["Firewall"],"summary":"Save firewall policy","description":"Creates a reusable firewall policy with default actions and optional rules.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"description":{"type":"string","maxLength":500},"policy_in":{"type":"string","enum":["DROP","ACCEPT"]},"policy_out":{"type":"string","enum":["DROP","ACCEPT"]},"rules":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string","enum":["IN","OUT"]},"type":{"type":"string","enum":["in","out"]},"action":{"type":"string","enum":["ACCEPT","DROP","REJECT"]},"proto":{"type":"string","enum":["tcp","udp","icmp","TCP","UDP","ICMP","any","all","ANY","ALL"]},"dport":{"anyOf":[{"type":"string"},{"type":"number"}]},"sport":{"anyOf":[{"type":"string"},{"type":"number"}]},"source":{"anyOf":[{"type":"string"},{"type":"number"}]},"destination":{"anyOf":[{"type":"string"},{"type":"number"}]},"dest":{"anyOf":[{"type":"string"},{"type":"number"}]},"comment":{"type":"string","maxLength":200},"enabled":{"anyOf":[{"type":"boolean"},{"type":"string"},{"type":"number"}]},"enable":{"anyOf":[{"type":"boolean"},{"type":"string"},{"type":"number"}]},"iface":{"type":"string","maxLength":64},"log":{"type":"string","maxLength":64}},"required":["action"],"additionalProperties":false}},"is_primary":{"type":"boolean"}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Created firewall policy.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"policyIn":{"type":"string"},"policyOut":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"type":{"type":"string"},"action":{"type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"dest":{"anyOf":[{"type":"string"},{"type":"null"}]},"proto":{"anyOf":[{"type":"string"},{"type":"null"}]},"sport":{"anyOf":[{"type":"string"},{"type":"null"}]},"dport":{"anyOf":[{"type":"string"},{"type":"null"}]},"comment":{"anyOf":[{"type":"string"},{"type":"null"}]},"enable":{"anyOf":[{"type":"boolean"},{"type":"number"}]},"position":{"type":"number"}},"additionalProperties":true}}},"required":["id","name"],"additionalProperties":true}},"required":["ok","policy"],"additionalProperties":true},"example":{"ok":true,"policy":{"id":"00000000-0000-4000-8000-000000000001","name":"Example policy","description":null,"isPrimary":false,"policyIn":"DROP","policyOut":"ACCEPT","rules":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["firewall.write"]},{"BearerAuth":["firewall.write"]}],"operationId":"firewallPolicyCreate"}},"/v1/firewall/policies/{policyId}":{"patch":{"tags":["Firewall"],"summary":"Edit firewall policy","description":"Updates policy metadata or replaces rules when a new rule list is provided.","parameters":[{"name":"policyId","in":"path","required":true,"description":"Firewall policy UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"description":{"type":"string","maxLength":500},"policy_in":{"type":"string","enum":["DROP","ACCEPT"]},"policy_out":{"type":"string","enum":["DROP","ACCEPT"]},"rules":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string","enum":["IN","OUT"]},"type":{"type":"string","enum":["in","out"]},"action":{"type":"string","enum":["ACCEPT","DROP","REJECT"]},"proto":{"type":"string","enum":["tcp","udp","icmp","TCP","UDP","ICMP","any","all","ANY","ALL"]},"dport":{"anyOf":[{"type":"string"},{"type":"number"}]},"sport":{"anyOf":[{"type":"string"},{"type":"number"}]},"source":{"anyOf":[{"type":"string"},{"type":"number"}]},"destination":{"anyOf":[{"type":"string"},{"type":"number"}]},"dest":{"anyOf":[{"type":"string"},{"type":"number"}]},"comment":{"type":"string","maxLength":200},"enabled":{"anyOf":[{"type":"boolean"},{"type":"string"},{"type":"number"}]},"enable":{"anyOf":[{"type":"boolean"},{"type":"string"},{"type":"number"}]},"iface":{"type":"string","maxLength":64},"log":{"type":"string","maxLength":64}},"required":["action"],"additionalProperties":false}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated firewall policy.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPrimary":{"type":"boolean"},"policyIn":{"type":"string"},"policyOut":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"type":{"type":"string"},"action":{"type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"dest":{"anyOf":[{"type":"string"},{"type":"null"}]},"proto":{"anyOf":[{"type":"string"},{"type":"null"}]},"sport":{"anyOf":[{"type":"string"},{"type":"null"}]},"dport":{"anyOf":[{"type":"string"},{"type":"null"}]},"comment":{"anyOf":[{"type":"string"},{"type":"null"}]},"enable":{"anyOf":[{"type":"boolean"},{"type":"number"}]},"position":{"type":"number"}},"additionalProperties":true}}},"required":["id","name"],"additionalProperties":true}},"required":["ok","policy"],"additionalProperties":true},"example":{"ok":true,"policy":{"id":"00000000-0000-4000-8000-000000000001","name":"Example policy","description":null,"isPrimary":false,"policyIn":"DROP","policyOut":"ACCEPT","rules":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["firewall.write"]},{"BearerAuth":["firewall.write"]}],"operationId":"firewallPolicyUpdate"},"delete":{"tags":["Firewall"],"summary":"Remove firewall policy","description":"Deletes a reusable firewall policy.","parameters":[{"name":"policyId","in":"path","required":true,"description":"Firewall policy UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Firewall policy deletion result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["firewall.write"]},{"BearerAuth":["firewall.write"]}],"operationId":"firewallPolicyDelete"}},"/v1/firewall/policies/{policyId}/primary":{"post":{"tags":["Firewall"],"summary":"Set primary firewall policy","description":"Marks a firewall policy as the primary default policy.","parameters":[{"name":"policyId","in":"path","required":true,"description":"Firewall policy UUID.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Primary policy update result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["firewall.write"]},{"BearerAuth":["firewall.write"]}],"operationId":"firewallPolicySetPrimary"}},"/v1/vps/{serviceId}/firewall/policy":{"get":{"tags":["Firewall"],"summary":"View VPS firewall policy","description":"Returns the effective firewall policy selection for a VPS.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Effective firewall policy.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"requestedPolicyId":{"anyOf":[{"type":"string"},{"type":"null"}]},"primaryPolicyId":{"anyOf":[{"type":"string"},{"type":"null"}]},"effectivePolicyId":{"anyOf":[{"type":"string"},{"type":"null"}]},"effectiveMode":{"type":"string"}},"required":["ok","requestedPolicyId","primaryPolicyId","effectivePolicyId","effectiveMode"],"additionalProperties":true},"example":{"ok":true,"requestedPolicyId":null,"primaryPolicyId":"00000000-0000-4000-8000-000000000001","effectivePolicyId":"00000000-0000-4000-8000-000000000001","effectiveMode":"primary"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.read"]},{"BearerAuth":["vps.read"]}],"operationId":"getVpsFirewallPolicy"}},"/v1/vps/{serviceId}/firewall/policy/apply":{"post":{"tags":["Firewall"],"summary":"Apply policy to VPS","description":"Applies a selected firewall policy to a VPS service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"policy_id":{"type":"string","minLength":1,"maxLength":128}},"required":["policy_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Firewall policy apply result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["vps.write"]},{"BearerAuth":["vps.write"]}],"operationId":"vpsFirewallPolicyApply"}},"/v1/storage/volumes":{"get":{"tags":["Storage"],"summary":"Browse storage volumes","description":"Returns customer-visible storage volumes.","parameters":[{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Storage volume list.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"serviceId":{"type":"string"},"billingServiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"sizeGb":{"type":"number"},"sizeBytes":{"type":"number"},"attachedTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"attachedServiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true}}},"required":["ok","items"],"additionalProperties":true},"example":{"ok":true,"items":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["storage.read"]},{"BearerAuth":["storage.read"]}],"operationId":"listStorageVolumes"}},"/v1/storage/volumes/{serviceId}/attach-options":{"get":{"tags":["Storage"],"summary":"View attach options","description":"Returns eligible target services or VMs that can accept the selected volume.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Volume attach options.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"serviceId":{"type":"string"},"billingServiceId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"sizeGb":{"type":"number"},"sizeBytes":{"type":"number"},"attachedTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"attachedServiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"ipv4":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true}}},"required":["ok","items"],"additionalProperties":true},"example":{"ok":true,"items":[]}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["storage.read"]},{"BearerAuth":["storage.read"]}],"operationId":"storageVolumeAttachOptions"}},"/v1/storage/volumes/{serviceId}/attach":{"post":{"tags":["Storage"],"summary":"Attach volume","description":"Attaches the selected volume to a target service.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target_service_id":{"type":"string","format":"uuid"}},"required":["target_service_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Volume attach result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["storage.write"]},{"BearerAuth":["storage.write"]}],"operationId":"storageVolumeAttach"}},"/v1/storage/volumes/{serviceId}/detach":{"post":{"tags":["Storage"],"summary":"Detach volume","description":"Detaches the selected volume from its current target.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"responses":{"200":{"description":"Volume detach result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]}},"required":["ok"],"additionalProperties":true},"example":{"ok":true}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["storage.write"]},{"BearerAuth":["storage.write"]}],"operationId":"storageVolumeDetach"}},"/v1/storage/volumes/{serviceId}/rename":{"post":{"tags":["Storage"],"summary":"Rename volume","description":"Changes the customer-visible volume name.","parameters":[{"name":"serviceId","in":"path","required":true,"description":"Customer-visible UUID of the service you want to inspect or change.","schema":{"type":"string"}},{"in":"header","name":"x-client-request-id","required":false,"description":"Optional client correlation label, 1–120 letters/digits/dots/underscores/colons/hyphens. Logged alongside the server request ID; never an idempotency key.","schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"}},{"name":"x-ts","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":1,"maxLength":20},"x-required-with-auth":"SignedAuth"},{"name":"x-nonce","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":8,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-content-sha256","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":200},"x-required-with-auth":"SignedAuth"},{"name":"x-signature","in":"header","required":false,"description":"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.","schema":{"type":"string","minLength":10,"maxLength":300},"x-required-with-auth":"SignedAuth"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Volume rename result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true,"enum":[true]},"billingServiceId":{"type":"string"},"name":{"type":"string"}},"required":["ok","billingServiceId","name"],"additionalProperties":true},"example":{"ok":true,"billingServiceId":"00000000-0000-4000-8000-000000000001","name":"Example volume"}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}},"default":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"field_errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]}}},"required":["code","message","request_id","field_errors"],"description":"Canonical error envelope. New clients should read these nested fields."},"ok":{"type":"boolean","const":false},"code":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.code. Generic server failures use service_unavailable without internal codes."},"status":{"type":"string","deprecated":true,"description":"Legacy compatibility field; inspect HTTP status and error.code instead."},"request_id":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.request_id, matching the x-request-id response header."},"message":{"type":"string","deprecated":true,"description":"Legacy compatibility field; use error.message."},"retryable":{"type":"boolean","description":"Whether retrying this rejected/read request may help. Never automatically retry a write with unknown outcome."},"outcome":{"type":"string","enum":["rejected","unknown"],"description":"unknown means a write may already have completed; inspect status and reuse the exact retry key."},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Wait at least this long; Retry-After header is authoritative."},"field_errors":{"type":"array","deprecated":true,"description":"Legacy compatibility field; use error.field_errors.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"details":{"deprecated":true,"description":"Legacy validation details; use error.field_errors. Do not log whole responses that may contain sensitive data."}},"required":["ok","error"]},"example":{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"00000000-0000-4000-8000-000000000001","field_errors":[]}}}},"headers":{"x-request-id":{"description":"Server correlation UUID; matches request_id in API error bodies.","schema":{"type":"string","format":"uuid"}},"RateLimit-Limit":{"description":"Credential budget when authenticated rate accounting is available.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in this budget.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until this rate budget resets. Legacy X-RateLimit-Reset remains a Unix timestamp.","schema":{"type":"integer"}}}}},"security":[{"SignedAuth":["storage.write"]},{"BearerAuth":["storage.write"]}],"operationId":"storageVolumeRename"}}}}