{ "openapi": "3.1.0", "info": { "title": "cdn.pizza Customer API", "version": "1.0.0", "description": "Public customer API. Internal control-plane, node telemetry, mail-routing, and administrative interfaces are deliberately excluded.", "contact": { "name": "cdn.pizza support", "email": "support@cdn.pizza" } }, "servers": [ { "url": "https://api.cdn.pizza", "description": "Production" } ], "tags": [ { "name": "Authentication" }, { "name": "Zones" }, { "name": "Cache" }, { "name": "Analytics" }, { "name": "Files" }, { "name": "Nodes" }, { "name": "Private networks" }, { "name": "Status agents" }, { "name": "Partner POPs" }, { "name": "Privacy" }, { "name": "Billing" }, { "name": "Webhooks" }, { "name": "GraphQL" }, { "name": "WebDAV" } ], "paths": { "/api/auth/login": { "post": { "tags": [ "Authentication" ], "operationId": "login", "summary": "Create an API session token", "description": "With 2FA, create a personal token in the dashboard and use it directly.", "security": [], "x-cdn-pizza-auth": "none", "x-cdn-pizza-roles": [], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "dev@example.com", "description": "Verified email address." }, "password": { "type": "string", "format": "password", "description": "Account password. Not accepted when 2FA is enabled." }, "device_name": { "type": "string", "example": "ci-production", "description": "Human-readable token name." } } } } } } } }, "/api/auth/me": { "get": { "tags": [ "Authentication" ], "operationId": "getCurrentUser", "summary": "Read the current profile", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/auth/logout": { "post": { "tags": [ "Authentication" ], "operationId": "logout", "summary": "Revoke the current token", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/zones": { "get": { "tags": [ "Zones" ], "operationId": "listZones", "summary": "List zones", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Zones" ], "operationId": "createZone", "summary": "Create, register, or transfer a zone", "description": "Registration and transfer are asynchronous and may return 202 with task_id.", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "assets.example.com", "description": "Fully qualified domain name." }, "name": { "type": "string", "example": "Assets production", "maxLength": 255, "description": "Dashboard display name." }, "type": { "type": "string", "enum": [ "cname", "ns" ], "example": "ns", "description": "cname or ns mode; defaults to ns." }, "registrar_action": { "type": "string", "enum": [ "connect", "register", "transfer" ], "example": "connect", "description": "connect, register, or transfer." }, "transfer_auth_code": { "type": "string", "minLength": 4, "maxLength": 255, "description": "Required for a transfer." }, "registrant_name": { "type": "string", "maxLength": 255, "description": "Required for registration/transfer." }, "registrant_email": { "type": "string", "format": "email", "maxLength": 255, "description": "Registrant email." }, "registrant_phone": { "type": "string", "maxLength": 40, "description": "Registrant international phone number." }, "registrant_organization": { "type": "string", "maxLength": 255, "description": "Registrant organization." }, "registrant_street": { "type": "string", "maxLength": 255, "description": "Registrant street address." }, "registrant_city": { "type": "string", "maxLength": 120, "description": "Registrant city." }, "registrant_postal_code": { "type": "string", "maxLength": 30, "description": "Registrant postal code." }, "registrant_country_code": { "type": "string", "example": "CH", "minLength": 2, "maxLength": 2, "description": "Two-letter ISO country code." }, "private_whois": { "type": "string", "enum": [ "FULL", "PARTIAL", "DISABLED" ], "description": "WHOIS privacy level." } } } } } } } }, "/api/zones/{id}": { "get": { "tags": [ "Zones" ], "operationId": "getZone", "summary": "Read a zone", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Zone identifier.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/zones/{id}/purge": { "post": { "tags": [ "Cache" ], "operationId": "purgeZonePath", "summary": "Purge a path", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Zone identifier.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "path": { "type": "string", "example": "/assets/app.css", "description": "Path to purge; when omitted, /* is used." } } } } } } } }, "/api/zones/{id}/purge-all": { "post": { "tags": [ "Cache" ], "operationId": "purgeEntireZone", "summary": "Purge an entire zone", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Zone identifier.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/zones/{id}/stats": { "get": { "tags": [ "Analytics" ], "operationId": "getZoneStats", "summary": "Read zone statistics", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Zone identifier.", "schema": { "type": "integer", "example": 42 } }, { "name": "period", "in": "query", "required": false, "description": "24h, 7d, or 30d window; defaults to 24h.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ], "example": "24h", "default": "24h" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/files": { "get": { "tags": [ "Files" ], "operationId": "listFiles", "summary": "List files", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [ { "name": "zone_id", "in": "query", "required": false, "description": "Filter by zone.", "schema": { "type": "integer", "example": 42 } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size; defaults to 25.", "schema": { "type": "integer", "example": 25, "minimum": 1 } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "example": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Files" ], "operationId": "uploadFile", "summary": "Upload a file", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "zone_id" ], "properties": { "file": { "type": "string", "format": "binary", "description": "File, up to 100 MB." }, "zone_id": { "type": "integer", "example": 42, "description": "Publishing zone." }, "storage_nodes": { "type": "array", "items": { "type": "integer" }, "description": "Up to three storage-node IDs." }, "cache_ttl": { "type": "integer", "example": 3600, "minimum": 0, "description": "Cache TTL in seconds; 0 is allowed." }, "direct_public_link": { "type": "boolean", "example": false, "description": "Enable the direct storage link." } } } } } } } }, "/api/files/{uuid}": { "get": { "tags": [ "Files" ], "operationId": "getFile", "summary": "Read a file", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Public file UUID.", "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Files" ], "operationId": "deleteFile", "summary": "Delete a file", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Public file UUID.", "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/nodes": { "get": { "tags": [ "Nodes" ], "operationId": "listNodes", "summary": "List available nodes", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Nodes" ], "operationId": "createNode", "summary": "Create a customer node", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "node_id", "hostname", "ip_address", "region_id", "country" ], "properties": { "node_id": { "type": "string", "example": "edge-zurich-01", "description": "Unique node identifier." }, "hostname": { "type": "string", "example": "edge-zurich-01.example.net", "description": "Node DNS hostname." }, "ip_address": { "type": "string", "example": "203.0.113.42", "description": "Node IPv4 or IPv6 address." }, "region_id": { "type": "integer", "example": 1, "description": "Existing region identifier." }, "country": { "type": "string", "example": "CH", "minLength": 2, "maxLength": 2, "description": "Two-letter ISO country code." } } } } } } } }, "/api/nodes/tokens": { "get": { "tags": [ "Nodes" ], "operationId": "listNodeTokens", "summary": "List BYOC tokens", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Nodes" ], "operationId": "createNodeToken", "summary": "Create a BYOC token", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin" ], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "example": "edge-installation", "maxLength": 100, "description": "Token name." }, "max_nodes": { "type": "integer", "example": 1, "default": 1, "minimum": 1, "maximum": 10, "description": "Maximum number of nodes; defaults to 1." }, "expires_days": { "type": "integer", "example": 30, "default": 30, "minimum": 1, "maximum": 365, "description": "Validity in days; defaults to 30." } } } } } } } }, "/api/nodes/tokens/{id}": { "delete": { "tags": [ "Nodes" ], "operationId": "deleteNodeToken", "summary": "Revoke a BYOC token", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Token identifier.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/networks": { "get": { "tags": [ "Private networks" ], "operationId": "listNetworks", "summary": "List private networks", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Private networks" ], "operationId": "createNetwork", "summary": "Create a private network", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "private_cidr" ], "properties": { "name": { "type": "string", "example": "backoffice", "maxLength": 120, "description": "Network name." }, "private_cidr": { "type": "string", "example": "10.42.0.0/24", "maxLength": 32, "description": "Private IPv4 range." }, "description": { "type": "string", "maxLength": 1000, "description": "Operational description." }, "routes": { "type": "array", "example": [ "10.50.0.0/16" ], "maxItems": 50, "items": { "type": "string", "maxLength": 32 }, "description": "Advertised private routes." }, "vpn_type": { "type": "string", "enum": [ "wireguard" ], "example": "wireguard", "description": "wireguard." } } } } } } } }, "/api/networks/{network}": { "get": { "tags": [ "Private networks" ], "operationId": "getNetwork", "summary": "Read a private network", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [ { "name": "network", "in": "path", "required": true, "description": "Network identifier.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/networks/{network}/enrollment-keys": { "post": { "tags": [ "Private networks" ], "operationId": "createNetworkEnrollmentKey", "summary": "Create a network enrollment key", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [ { "name": "network", "in": "path", "required": true, "description": "Network identifier.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "first-device", "maxLength": 120, "description": "Key name." }, "max_uses": { "type": "integer", "example": 1, "default": 1, "minimum": 1, "maximum": 10, "description": "Maximum number of uses." }, "expires_in_hours": { "type": "integer", "example": 24, "default": 24, "minimum": 1, "maximum": 168, "description": "Validity duration." } } } } } } } }, "/api/networks/enroll": { "post": { "tags": [ "Private networks" ], "operationId": "enrollNetworkPeer", "summary": "Enroll a WireGuard peer", "security": [], "x-cdn-pizza-auth": "enrollment-token", "x-cdn-pizza-roles": [], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enrollment_token", "name", "public_key" ], "properties": { "enrollment_token": { "type": "string", "example": "ENROLLMENT_TOKEN", "maxLength": 128, "description": "Short-lived cpn_… network key." }, "name": { "type": "string", "example": "origin-geneva", "maxLength": 120, "description": "Peer name." }, "peer_type": { "type": "string", "enum": [ "connector", "admin_device", "origin" ], "description": "connector, admin_device, or origin." }, "public_key": { "type": "string", "example": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "maxLength": 120, "pattern": "^[A-Za-z0-9+/]{43}=$", "description": "WireGuard public key." }, "endpoint": { "type": "string", "maxLength": 255, "description": "Peer public endpoint." } } } } } } } }, "/api/status-agents/enrollment-keys": { "post": { "tags": [ "Status agents" ], "operationId": "createStatusAgentEnrollmentKey", "summary": "Create an agent enrollment key", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status_page_id", "name" ], "properties": { "status_page_id": { "type": "integer", "description": "Target status page." }, "name": { "type": "string", "example": "branch-geneva", "maxLength": 120, "description": "Key or agent name." }, "max_uses": { "type": "integer", "example": 1, "default": 1, "minimum": 1, "maximum": 10, "description": "Maximum number of uses." }, "expires_in_hours": { "type": "integer", "example": 24, "default": 24, "minimum": 1, "maximum": 168, "description": "Validity duration." } } } } } } } }, "/api/status-agents/enroll": { "post": { "tags": [ "Status agents" ], "operationId": "enrollStatusAgent", "summary": "Enroll a status agent", "security": [], "x-cdn-pizza-auth": "enrollment-token", "x-cdn-pizza-roles": [], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enrollment_token", "name" ], "properties": { "enrollment_token": { "type": "string", "example": "STATUS_ENROLLMENT_TOKEN", "maxLength": 128, "description": "Short-lived cps_… key." }, "name": { "type": "string", "example": "branch-geneva", "maxLength": 120, "description": "Agent name." }, "hostname": { "type": "string", "example": "branch-geneva.example.net", "maxLength": 255, "description": "Machine hostname." }, "version": { "type": "string", "example": "1.0.0", "maxLength": 80, "description": "Agent version." }, "capabilities": { "type": "array", "example": [ "heartbeat", "http", "tcp", "process", "monitor_generation_v1" ], "maxItems": 20, "items": { "type": "string", "maxLength": 40 }, "description": "Supported check types." } } } } } } } }, "/api/status-agents/config": { "get": { "tags": [ "Status agents" ], "operationId": "getStatusAgentConfig", "summary": "Read agent configuration", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "status-agent", "x-cdn-pizza-roles": [], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/status-agents/heartbeat": { "post": { "tags": [ "Status agents" ], "operationId": "sendStatusAgentHeartbeat", "summary": "Send an agent heartbeat", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "status-agent", "x-cdn-pizza-roles": [], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "hostname": { "type": "string", "maxLength": 255, "description": "Current hostname." }, "version": { "type": "string", "maxLength": 80, "description": "Current version." }, "capabilities": { "type": "array", "example": [ "heartbeat", "http", "tcp", "process", "monitor_generation_v1" ], "maxItems": 20, "items": { "type": "string" }, "description": "Supported capabilities, up to twenty." }, "metrics": { "type": "object", "example": { "load1": 0.2, "memory_used_percent": 41 }, "additionalProperties": true, "description": "Safe local metrics such as load and used memory." } } } } } } } }, "/api/status-agents/results": { "post": { "tags": [ "Status agents" ], "operationId": "submitStatusAgentResults", "summary": "Submit check results", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "status-agent", "x-cdn-pizza-roles": [], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "example": [ { "monitor_id": 17, "configuration_version": 2, "healthy": true, "latency_ms": 42.5 } ], "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "monitor_id", "healthy" ], "properties": { "monitor_id": { "type": "integer" }, "configuration_version": { "type": "integer", "minimum": 1 }, "healthy": { "type": "boolean" }, "latency_ms": { "type": "number", "minimum": 0, "maximum": 600000 }, "checked_at": { "type": "string", "format": "date-time" }, "details": { "type": "object", "additionalProperties": true }, "error_message": { "type": "string", "maxLength": 1000 } } }, "description": "One to one hundred results with monitor_id and healthy; configuration_version, latency_ms, checked_at, details, and error_message are optional." } } } } } } } }, "/api/partner-pops": { "get": { "tags": [ "Partner POPs" ], "operationId": "listPartnerPops", "summary": "List partner POPs", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Partner POPs" ], "operationId": "createPartnerPop", "summary": "Create a partner POP", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_name", "display_name", "contact_email", "city", "country", "capacity_mbps", "requirements_accepted" ], "properties": { "company_name": { "type": "string", "example": "Example Networks AG", "maxLength": 160, "description": "Operator legal or trading name." }, "display_name": { "type": "string", "example": "Zurich IX", "maxLength": 180, "description": "Proposed public POP name." }, "contact_email": { "type": "string", "format": "email", "example": "noc@example.net", "maxLength": 180, "description": "Partner operational email." }, "website_url": { "type": "string", "format": "uri", "example": "https://example.net", "maxLength": 255, "description": "Operator public website." }, "logo_url": { "type": "string", "format": "uri", "example": "https://example.net/logo.svg", "maxLength": 2048, "description": "HTTPS URL of the public logo." }, "provider_name": { "type": "string", "maxLength": 160, "description": "Infrastructure provider name." }, "city": { "type": "string", "example": "Zürich", "maxLength": 120, "description": "POP city." }, "country": { "type": "string", "example": "CH", "minLength": 2, "maxLength": 2, "description": "Two-letter ISO country code." }, "submitted_ipv4": { "type": "string", "format": "ipv4", "example": "203.0.113.10", "description": "Proposed IPv4 address." }, "submitted_ipv6": { "type": "string", "format": "ipv6", "example": "2001:db8::10", "description": "Proposed IPv6 address." }, "capacity_mbps": { "type": "integer", "example": 10000, "minimum": 100, "maximum": 1000000, "description": "Network capacity in Mbit/s." }, "notes": { "type": "string", "maxLength": 5000, "description": "Technical or operational notes." }, "requirements_accepted": { "type": "boolean", "example": true, "description": "Confirms acceptance of the Partner POP requirements." } } } } } } } }, "/api/partner-pops/{partnerPop}/enrollment-token": { "post": { "tags": [ "Partner POPs" ], "operationId": "createPartnerPopEnrollmentToken", "summary": "Create a POP installation token", "description": "The POP must belong to the organization. The application creator may also create the token.", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member" ], "parameters": [ { "name": "partnerPop", "in": "path", "required": true, "description": "POP identifier.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "example": "first-installation", "maxLength": 120, "description": "Installation token name." } } } } } } } }, "/api/gdpr/export": { "get": { "tags": [ "Privacy" ], "operationId": "exportAccountData", "summary": "Export account data", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/gdpr/account": { "delete": { "tags": [ "Privacy" ], "operationId": "deleteAccount", "summary": "Delete the account", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string", "format": "password", "example": "ACCOUNT_PASSWORD", "description": "Current password, required for confirmation." } } } } } } } }, "/api/gdpr/consent": { "get": { "tags": [ "Privacy" ], "operationId": "getConsent", "summary": "Read consent settings", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Privacy" ], "operationId": "updateConsent", "summary": "Update consent settings", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "analytics": { "type": "boolean", "description": "Allow non-essential analytics." }, "marketing": { "type": "boolean", "description": "Allow marketing communications." } } } } } } } }, "/api/billing/plans": { "get": { "tags": [ "Billing" ], "operationId": "listBillingPlans", "summary": "List plans", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/billing": { "get": { "tags": [ "Billing" ], "operationId": "getBilling", "summary": "Read the current subscription", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/billing/checkout": { "post": { "tags": [ "Billing" ], "operationId": "createCheckout", "summary": "Create a checkout session", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "string", "enum": [ "starter", "pro", "enterprise" ], "example": "pro", "description": "Public plan code." } } } } } } } }, "/api/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List webhooks", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Create a webhook", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin" ], "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://hooks.example.com/cdn-pizza", "maxLength": 500, "description": "Public HTTP(S) receiver URL; HTTPS is recommended." }, "events": { "type": "array", "example": [ "file.uploaded", "file.deleted" ], "items": { "type": "string", "enum": [ "file.uploaded", "file.deleted", "domain.created", "zone.created", "zone.updated", "zone.deleted", "cache.purged", "node.online", "node.offline", "node.deployed", "billing.updated", "invoice.paid", "mail.accepted", "mail.rejected", "mail.deferred" ] }, "description": "Subscribed events." }, "secret": { "type": "string", "maxLength": 255, "description": "Customer-selected signing secret." } } } } } } } }, "/api/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete a webhook", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook identifier.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/graphql": { "post": { "tags": [ "GraphQL" ], "operationId": "executeGraphql", "summary": "Execute a GraphQL query", "security": [ { "bearerAuth": [] } ], "x-cdn-pizza-auth": "bearer", "x-cdn-pizza-roles": [ "owner", "admin", "member", "viewer" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "example": "query { zones { id domain } }", "description": "Query document; only four root fields are available." }, "variables": { "type": "object", "example": {}, "additionalProperties": true, "description": "Query variables." } } } } } } } }, "/api/files/webdav/{path}": { "parameters": [ { "name": "path", "in": "path", "required": true, "description": "Object or collection path.", "schema": { "type": "string" } } ], "x-webdav-methods": [ "OPTIONS", "PROPFIND", "GET", "HEAD", "PUT", "DELETE", "MKCOL" ], "x-webdav-authentication": "HTTP Basic authentication: verified account email as username and personal API token as password. OPTIONS is public.", "x-webdav-token-abilities": { "read": [ "*", "files:read" ], "write": [ "*", "files:write" ] }, "x-webdav-operations": { "PROPFIND": { "summary": "List a collection and its WebDAV properties.", "requestHeaders": { "Depth": [ "0", "1" ] }, "responses": { "207": "Multi-Status XML", "404": "Object or collection not found" } }, "MKCOL": { "summary": "Create a collection inside a zone.", "responses": { "201": "Collection accepted", "405": "A file already exists at this path", "409": "The collection path is not inside a zone" } } }, "get": { "tags": [ "WebDAV" ], "operationId": "webdavGet", "summary": "Download an object through WebDAV", "security": [ { "webDavBasic": [] } ], "responses": { "200": { "description": "Object contents" }, "404": { "description": "Object not found" } } }, "head": { "tags": [ "WebDAV" ], "operationId": "webdavHead", "summary": "Read object metadata", "security": [ { "webDavBasic": [] } ], "responses": { "200": { "description": "Object metadata headers" }, "404": { "description": "Object not found" } } }, "put": { "tags": [ "WebDAV" ], "operationId": "webdavPut", "summary": "Create or replace an object", "security": [ { "webDavBasic": [] } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "201": { "description": "Object created" }, "204": { "description": "Object replaced" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "WebDAV" ], "operationId": "webdavDelete", "summary": "Delete an object or collection", "security": [ { "webDavBasic": [] } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Object not found" } } }, "options": { "tags": [ "WebDAV" ], "operationId": "webdavOptions", "summary": "Discover supported WebDAV capabilities", "security": [], "responses": { "204": { "description": "DAV and Allow headers" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Personal access token" }, "webDavBasic": { "type": "http", "scheme": "basic", "description": "Verified account email as username; personal API token as password." } }, "responses": { "Unauthenticated": { "description": "Missing, invalid, or expired credential." }, "Forbidden": { "description": "Authenticated but not authorized for this organization or role." }, "ValidationError": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "RateLimited": { "description": "Rate limit exceeded. Retry after the response Retry-After delay." } }, "schemas": { "ValidationError": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message" ] } } } }