{ "openapi": "3.1.0", "info": { "title": "DanubeData API Documentation", "version": "1.0.0", "description": "DanubeData API v1 provides programmatic access to manage VPS instances, databases, cache servers, firewalls, SSH keys, snapshots, and webhooks. All endpoints require Sanctum authentication via bearer token." }, "servers": [ { "url": "https://danubedata.ro/api/v1", "description": "Production" } ], "security": [ { "http": [] } ], "paths": { "/user/teams": { "get": { "operationId": "v1.user.teams", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "personal_team": { "type": "boolean" }, "registry_namespace": { "type": [ "string", "null" ], "description": "The registry path segment, and the Kubernetes tenant slug.\nIt is NOT derivable from `name`: a team called \"Safi\" can own\nthe namespace `safi4`, because the slug is uniquified at\nassignment. Without this field a client has to guess the\nfirst segment of `cr.danubedata.ro/{ns}/...`, and a wrong\nguess fails as an opaque authorization error." } }, "required": [ "id", "name", "personal_team", "registry_namespace" ] } }, "current_team_id": { "type": "integer" } }, "required": [ "data", "current_team_id" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{cacheInstance}/logs": { "get": { "operationId": "v1.cache.logs", "description": "Returns bounded, cursor-paged log entries from the platform log store.", "summary": "Fetch cache instance logs", "tags": [ "Cache Diagnostics", "CacheDiagnostics" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "An opaque cursor from a previous response. It is a Loki\nnanosecond timestamp, so digits-only: rejecting everything else\nkeeps a hand-crafted value from reaching the upstream query.", "schema": { "type": "string", "pattern": "^\\d{1,25}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "level", "in": "query", "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceLogEntryResource" } } }, "required": [ "available", "entries" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "entries" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "The log store did not respond. This says nothing about the workload itself \u2014 retry shortly." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/cache/{cacheInstance}/events": { "get": { "operationId": "v1.cache.events", "description": "Returns curated platform events for the instance's pods, workloads and\nvolumes.", "summary": "List Kubernetes events", "tags": [ "Cache Diagnostics", "CacheDiagnostics" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosticEventResource" } } }, "required": [ "available", "events" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "events" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "Platform events could not be read for this resource." }, "retryable": { "type": "boolean", "description": "A missing RBAC grant will not fix itself on retry; a\ntransient API-server failure will." } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{cacheInstance}/diagnose": { "get": { "operationId": "v1.cache.diagnose", "description": "Correlates status, events and log availability into ranked findings\nwith remediation.", "summary": "Diagnose the instance", "tags": [ "Cache Diagnostics", "CacheDiagnostics" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache": { "get": { "operationId": "v1.cache.index", "description": "Retrieves a paginated list of all Redis cache instances belonging to the authenticated user's team.", "summary": "List all cache instances", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CacheInstanceResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.cache.store", "summary": "Store a new cache instance", "tags": [ "Cache Management", "CacheManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreApiCacheInstanceRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache instance created successfully" }, "instance": { "allOf": [ { "$ref": "#/components/schemas/CacheInstanceResource" }, { "type": "object", "required": [ "provider" ] } ] } }, "required": [ "message", "instance" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/cache/plans": { "get": { "operationId": "v1.cache.plans", "summary": "List available cache plans with current pricing", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "provider", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "redis", "valkey", "dragonfly", null ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" }, "provider": { "type": "string" }, "cpu_cores": { "type": "string" }, "memory_mb": { "type": "string" }, "storage_gb": { "type": "string" }, "monthly_cost": { "type": "number" } }, "required": [ "slug", "display_name", "provider", "cpu_cores", "memory_mb", "storage_gb", "monthly_cost" ] } } ] } }, "required": [ "plans" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{cacheInstance}": { "get": { "operationId": "v1.cache.show", "summary": "Show a specific cache instance", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "allOf": [ { "$ref": "#/components/schemas/CacheInstanceResource" }, { "type": "object", "required": [ "provider" ] } ] }, "connection_info": { "type": [ "string", "null" ] }, "monthly_cost": { "type": "number" } }, "required": [ "instance", "connection_info", "monthly_cost" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.cache.update", "summary": "Update a cache instance", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiCacheInstanceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache instance update initiated" }, "instance": { "allOf": [ { "$ref": "#/components/schemas/CacheInstanceResource" }, { "type": "object", "required": [ "provider" ] } ] } }, "required": [ "message", "instance" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "delete": { "operationId": "v1.cache.destroy", "summary": "Delete a cache instance", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache instance deletion initiated" }, "status": { "type": "string", "const": "destroying" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Cache instance cannot be destroyed in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{cacheInstance}/start": { "post": { "operationId": "v1.cache.start", "summary": "Start a cache instance", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache instance start initiated" }, "status": { "type": "string", "const": "starting" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Cache instance cannot be started in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{cacheInstance}/stop": { "post": { "operationId": "v1.cache.stop", "summary": "Stop a cache instance", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache instance stop initiated" }, "status": { "type": "string", "const": "stopping" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Cache instance cannot be stopped in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{cacheInstance}/force-stop": { "post": { "operationId": "v1.cache.force-stop", "description": "Recovery path for an instance stuck in a transitional state. Unlike stop(),\nwhich requires Running, this accepts any status except Stopped and\nDestroying. It writes the status directly rather than queueing work,\nmatching CacheInstanceController::forceStop().", "summary": "Force-stop a cache instance", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache instance force stopped successfully" }, "status": { "type": "string", "const": "stopped" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Cache instance cannot be force stopped in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{cacheInstance}/connection-info": { "get": { "operationId": "v1.cache.connection-info", "description": "Returns the effective connection endpoint and the auth token for the\ncache instance. `host`/`port` are the values to connect to: when public\nDNS is enabled they are the DNS hostname and the port allocated for it on\nthe shared load balancer, otherwise the in-cluster hostname and the\nengine port. They are not always equal to the instance's `port` field,\nwhich always reports the engine port.", "summary": "Get cache instance connection information", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string", "description": "RESP has no per-user auth on these instances; `default` is the\nimplicit user every Redis/Valkey/Dragonfly client authenticates as.", "const": "default" }, "password": { "type": [ "string", "null" ] }, "connection_info": { "type": "string" } }, "required": [ "host", "port", "username", "password", "connection_info" ] } } } }, "503": { "description": "Already logged with structured identifiers by the model. Never\necho the exception message \u2014 return a customer-safe one instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{cacheInstance}/credentials": { "get": { "operationId": "v1.cache.credentials", "description": "Compatibility alias for `GET /api/v1/cache/{id}/connection-info`, which\nremains the canonical route. Named for symmetry with\n`GET /api/v1/database/{id}/credentials`; returns an identical payload\nunder identical authorization, token-permission and rate-limit rules.", "summary": "Get cache instance credentials", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string", "description": "RESP has no per-user auth on these instances; `default` is the\nimplicit user every Redis/Valkey/Dragonfly client authenticates as.", "const": "default" }, "password": { "type": [ "string", "null" ] }, "connection_info": { "type": "string" } }, "required": [ "host", "port", "username", "password", "connection_info" ] } } } }, "503": { "description": "Already logged with structured identifiers by the model. Never\necho the exception message \u2014 return a customer-safe one instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{cacheInstance}/metrics": { "get": { "operationId": "v1.cache.metrics", "description": "Returns a summary (not time-series) suitable for CLI/dashboard consumption.", "summary": "Get cache instance summary metrics", "tags": [ "Cache Management", "CacheManagement" ], "parameters": [ { "name": "cacheInstance", "in": "path", "required": true, "description": "The cache instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "memory_used_bytes": { "type": "string" }, "memory_used_mb": { "type": "number" }, "connected_clients": { "type": "string" }, "total_commands_processed": { "type": "string" }, "keyspace_hits": { "type": "string" }, "keyspace_misses": { "type": "string" }, "hit_ratio_percentage": { "type": "number" }, "retrieved_at": { "type": [ "string", "null" ] } }, "required": [ "memory_used_bytes", "memory_used_mb", "connected_clients", "total_commands_processed", "keyspace_hits", "keyspace_misses", "hit_ratio_percentage", "retrieved_at" ] }, "health": { "type": "object", "properties": { "is_healthy": { "type": "string" }, "up_status": { "type": "string" }, "redis_up": { "type": "string" }, "checked_at": { "type": [ "string", "null" ] } }, "required": [ "is_healthy", "up_status", "redis_up", "checked_at" ] }, "instance": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "summary", "health", "instance" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/registry/usage": { "get": { "operationId": "v1.registry.usage", "description": "An agent about to push wants to know whether it will fit. A limit of 0\nmeans unlimited, matching the dashboard.", "summary": "Show registry usage against the team's limits", "tags": [ "Container Registry", "RegistryManagement" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "bytes_used": { "type": "integer" }, "repository_count": { "type": "integer" }, "max_bytes": { "type": "integer" }, "max_repositories": { "type": "integer" } }, "required": [ "bytes_used", "repository_count", "max_bytes", "max_repositories" ] }, "meta": { "type": "object", "properties": { "unlimited_is_zero": { "type": "boolean" } }, "required": [ "unlimited_is_zero" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/registry/repositories": { "get": { "operationId": "v1.registry.repositories.index", "summary": "List repositories", "tags": [ "Container Registry", "RegistryManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryRepositoryResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/registry/repositories/{repo}": { "get": { "operationId": "v1.registry.repositories.show", "summary": "Show a repository", "tags": [ "Container Registry", "RegistryManagement" ], "parameters": [ { "name": "repo", "in": "path", "required": true, "description": "The repo ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "repository": { "$ref": "#/components/schemas/RegistryRepositoryResource" } }, "required": [ "repository" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.registry.repositories.destroy", "summary": "Delete a repository and every tag in it", "tags": [ "Container Registry", "RegistryManagement" ], "parameters": [ { "name": "repo", "in": "path", "required": true, "description": "The repo ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "The registry did not confirm every delete, so the repository was left intact." }, "retryable": { "type": "boolean" } }, "required": [ "error", "retryable" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/registry/repositories/{repo}/tags": { "get": { "operationId": "v1.registry.repositories.tags", "summary": "List a repository's tags", "tags": [ "Container Registry", "RegistryManagement" ], "parameters": [ { "name": "repo", "in": "path", "required": true, "description": "The repo ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryRepositoryTagResource" } } }, "required": [ "data" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/registry/repositories/{repo}/tags/{tag}": { "delete": { "operationId": "v1.registry.repositories.tags.destroy", "description": "Removes the manifest from the registry and the local record. The\nrepository row survives even if this was its last tag \u2014 removing it is\na separate, explicit call.", "summary": "Delete a tag", "tags": [ "Container Registry", "RegistryManagement" ], "parameters": [ { "name": "repo", "in": "path", "required": true, "description": "The repo ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "The registry did not confirm the delete, so nothing was removed." }, "retryable": { "type": "boolean" } }, "required": [ "error", "retryable" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}/logs": { "get": { "operationId": "v1.database.logs", "description": "Returns bounded, cursor-paged log entries from the platform log store.", "summary": "Fetch database instance logs", "tags": [ "Database Diagnostics", "DatabaseDiagnostics" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "An opaque cursor from a previous response. It is a Loki\nnanosecond timestamp, so digits-only: rejecting everything else\nkeeps a hand-crafted value from reaching the upstream query.", "schema": { "type": "string", "pattern": "^\\d{1,25}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "level", "in": "query", "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceLogEntryResource" } } }, "required": [ "available", "entries" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "entries" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "The log store did not respond. This says nothing about the workload itself \u2014 retry shortly." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/database/{databaseInstance}/events": { "get": { "operationId": "v1.database.events", "description": "Returns curated platform events for the instance's pods, workloads and\nvolumes.", "summary": "List Kubernetes events", "tags": [ "Database Diagnostics", "DatabaseDiagnostics" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosticEventResource" } } }, "required": [ "available", "events" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "events" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "Platform events could not be read for this resource." }, "retryable": { "type": "boolean", "description": "A missing RBAC grant will not fix itself on retry; a\ntransient API-server failure will." } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}/diagnose": { "get": { "operationId": "v1.database.diagnose", "description": "Correlates status, events and log availability into ranked findings\nwith remediation.", "summary": "Diagnose the instance", "tags": [ "Database Diagnostics", "DatabaseDiagnostics" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database": { "get": { "operationId": "v1.database.index", "description": "Retrieves a paginated list of all database instances (PostgreSQL/MySQL) belonging to the authenticated user's team.", "summary": "List all database instances", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DatabaseInstanceResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.database.store", "summary": "Store a new database instance", "tags": [ "Database Management", "DatabaseManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreApiDatabaseInstanceRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database instance created successfully" }, "instance": { "allOf": [ { "$ref": "#/components/schemas/DatabaseInstanceResource" }, { "type": "object", "required": [ "provider", "engine", "storage_autoscale_policy" ] } ] } }, "required": [ "message", "instance" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/database/plans": { "get": { "operationId": "v1.database.plans", "summary": "List available database plans with current pricing", "tags": [ "Database Management", "DatabaseManagement" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" }, "cpu_cores": { "type": "string" }, "memory_mb": { "type": "string" }, "storage_gb": { "type": "string" }, "monthly_cost": { "type": "number" } }, "required": [ "slug", "display_name", "cpu_cores", "memory_mb", "storage_gb", "monthly_cost" ] } } }, "required": [ "plans" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}": { "get": { "operationId": "v1.database.show", "summary": "Show a specific database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "allOf": [ { "$ref": "#/components/schemas/DatabaseInstanceResource" }, { "type": "object", "required": [ "provider", "engine", "storage_autoscale_policy" ] } ] }, "connection_info": { "type": [ "string", "null" ] }, "monthly_cost": { "type": "number" } }, "required": [ "instance", "connection_info", "monthly_cost" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.database.update", "summary": "Update a database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiDatabaseInstanceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database instance update initiated" }, "instance": { "allOf": [ { "$ref": "#/components/schemas/DatabaseInstanceResource" }, { "type": "object", "required": [ "provider", "engine", "storage_autoscale_policy" ] } ] } }, "required": [ "message", "instance" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "delete": { "operationId": "v1.database.destroy", "summary": "Delete a database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database instance deletion initiated" }, "status": { "type": "string", "const": "destroying" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Database instance cannot be destroyed in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}/start": { "post": { "operationId": "v1.database.start", "summary": "Start a database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database instance start initiated" }, "status": { "type": "string", "const": "starting" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Database instance cannot be started in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}/stop": { "post": { "operationId": "v1.database.stop", "summary": "Stop a database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database instance stop initiated" }, "status": { "type": "string", "const": "stopping" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Database instance cannot be stopped in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}/force-stop": { "post": { "operationId": "v1.database.force-stop", "description": "Recovery path for an instance stuck in a transitional state. Unlike stop(),\nwhich requires Running or Starting, this accepts any status except\nStopped, Destroying and Stopping. It writes the status directly rather\nthan queueing work, matching DatabaseInstanceController::forceStop().", "summary": "Force-stop a database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database instance force stopped successfully" }, "status": { "type": "string", "const": "stopped" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Database instance cannot be force stopped in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}/credentials": { "get": { "operationId": "v1.database.credentials", "description": "Returns the effective connection endpoint and the administrative\ncredentials for the database instance.\n\n`host`/`port` are the values to connect to: when public DNS is enabled\nthey are the DNS hostname and the port allocated for it on the shared\nload balancer, otherwise the in-cluster hostname and the engine port.\nThey are not always equal to the instance's `port` field, which always\nreports the engine port.\n\n`username`/`password` are the superuser (`postgres` on PostgreSQL, `root`\non MySQL/MariaDB) where the platform can resolve them, so the credentials\nreturned here can create roles, extensions and databases. Instances whose\nsuperuser is not resolvable fall back to the provisioned application user.", "summary": "Get database instance credentials", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string" }, "database": { "type": [ "string", "null" ] }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connection_info": { "type": "string" } }, "required": [ "host", "port", "username", "database", "password", "connection_info" ] } } } }, "503": { "description": "Already logged with structured identifiers by the model. Never\necho the exception message \u2014 return a customer-safe one instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}/metrics": { "get": { "operationId": "v1.database.metrics", "summary": "Get replication status for a database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "memory_used_bytes": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "memory_used_mb": { "type": "number" }, "connected_clients": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "total_queries": { "type": "string" }, "slow_queries": { "type": "string" }, "retrieved_at": { "type": [ "string", "null" ] } }, "required": [ "memory_used_bytes", "memory_used_mb", "connected_clients", "total_queries", "slow_queries", "retrieved_at" ] }, "health": { "type": "object", "properties": { "is_healthy": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] }, "up_status": { "type": "string" }, "checked_at": { "type": [ "string", "null" ] } }, "required": [ "is_healthy", "up_status", "checked_at" ] }, "instance": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "summary", "health", "instance" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}/replicas": { "get": { "operationId": "v1.database.replicas.index", "description": "Returns master node, replica nodes, and billing information.", "summary": "List replicas for a database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to list replicas" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "An unexpected error occurred." ] } ] } }, "required": [ "error", "message" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "replicas": { "type": "array", "items": {} }, "master": { "type": "object", "properties": { "name": { "type": "string" }, "node_id": { "type": "string" }, "endpoint": { "type": "string" }, "status": { "type": "string" }, "ready": { "type": "boolean" } }, "required": [ "name", "node_id", "endpoint", "status", "ready" ] }, "billing": { "type": "object", "properties": { "hourly_cost_cents": { "type": "number", "description": "Priority 3: Calculate from resources using fallback rates" }, "monthly_cost_cents": { "type": "integer" } }, "required": [ "hourly_cost_cents", "monthly_cost_cents" ] } }, "required": [ "replicas", "master", "billing" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.database.replicas.store", "summary": "Add replicas to a database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddApiDatabaseReplicasRequest" } } } }, "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to add replica" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "An unexpected error occurred." ] } ] } }, "required": [ "error", "message" ] } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Replica added successfully" ] } ] }, "replicas": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "replica_name": { "type": "string" }, "replica_index": { "type": "integer" }, "message": { "type": "string", "const": "Replica StatefulSet, Service, and ConfigMap created via GitOps. ArgoCD will sync changes in ~3 minutes." } }, "required": [ "status", "replica_name", "replica_index", "message" ] } } }, "required": [ "message", "replicas" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/database/{databaseInstance}/replicas/{index}": { "delete": { "operationId": "v1.database.replicas.destroy", "summary": "Remove a replica from a database instance", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "index", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to remove replica" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "An unexpected error occurred." ] } ] } }, "required": [ "error", "message" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Replica removed successfully" }, "status": { "type": "string", "const": "success" } }, "required": [ "message", "status" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{databaseInstance}/replicas/status": { "get": { "operationId": "v1.database.replicas.status", "tags": [ "Database Management", "DatabaseManagement" ], "parameters": [ { "name": "databaseInstance", "in": "path", "required": true, "description": "The database instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to get replication status" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "An unexpected error occurred." ] } ] } }, "required": [ "error", "message" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "is_replicating": { "type": "boolean" }, "replica_count": { "type": "integer", "minimum": 0 }, "replicas": { "type": "array", "items": {} } }, "required": [ "is_replicating", "replica_count", "replicas" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/cache/{id}/dns": { "post": { "operationId": "v1.cache.dns.enable", "summary": "Enable DNS for a cache instance", "tags": [ "DnsManagement" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Failed to enable DNS" }, "error": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "An unexpected error occurred." ] } ] } }, "required": [ "message", "error" ] } } } }, "200": { "description": "DNS records carry no port, so the allocated load-balancer port is\nonly discoverable through this response (or a follow-up GET). An\nAPI-only client that got just the hostname back would have to\nguess, and the engine port is the wrong guess.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "DNS enabled successfully" }, "dns_hostname": { "type": "string" }, "dns_port": { "type": [ "integer", "null" ] } }, "required": [ "message", "dns_hostname", "dns_port" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "DNS is already enabled for this cache instance" }, "dns_hostname": { "type": [ "string", "null" ] }, "dns_port": { "type": [ "integer", "null" ] } }, "required": [ "message", "dns_hostname", "dns_port" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache instance must be deployed to a node before DNS can be enabled" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.cache.dns.disable", "summary": "Disable DNS for a cache instance", "tags": [ "DnsManagement" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Failed to disable DNS" }, "error": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "An unexpected error occurred." ] } ] } }, "required": [ "message", "error" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "DNS disabled successfully" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/database/{id}/dns": { "post": { "operationId": "v1.database.dns.enable", "summary": "Enable DNS for a database instance", "tags": [ "DnsManagement" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Failed to enable DNS" }, "error": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "An unexpected error occurred." ] } ] } }, "required": [ "message", "error" ] } } } }, "200": { "description": "See enableCacheDns(): the allocated port is not derivable from\nthe hostname, so it must come back with it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "DNS enabled successfully" }, "dns_hostname": { "type": "string" }, "dns_port": { "type": [ "integer", "null" ] } }, "required": [ "message", "dns_hostname", "dns_port" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "DNS is already enabled for this database instance" }, "dns_hostname": { "type": [ "string", "null" ] }, "dns_port": { "type": [ "integer", "null" ] } }, "required": [ "message", "dns_hostname", "dns_port" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "CNPG primary pod is not ready \u2014 wait for the cluster to come up before enabling DNS", "Database instance must be deployed to a node before DNS can be enabled" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.database.dns.disable", "summary": "Disable DNS for a database instance", "tags": [ "DnsManagement" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Failed to disable DNS" }, "error": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "An unexpected error occurred." ] } ] } }, "required": [ "message", "error" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "DNS disabled successfully" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/firewalls": { "get": { "operationId": "v1.firewalls.index", "description": "Retrieves a paginated list of all firewalls with their rules belonging to the authenticated user's team.", "summary": "List all firewalls", "tags": [ "Firewall Management", "FirewallManagement" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.firewalls.store", "summary": "Store a new firewall", "tags": [ "Firewall Management", "FirewallManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFirewallRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Firewall created successfully" }, "firewall": { "allOf": [ { "$ref": "#/components/schemas/FirewallResource" }, { "type": "object", "required": [ "rules" ] } ] } }, "required": [ "message", "firewall" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/firewalls/{firewall}": { "get": { "operationId": "v1.firewalls.show", "summary": "Show a specific firewall", "tags": [ "Firewall Management", "FirewallManagement" ], "parameters": [ { "name": "firewall", "in": "path", "required": true, "description": "The firewall ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "firewall": { "allOf": [ { "$ref": "#/components/schemas/FirewallResource" }, { "type": "object", "required": [ "rules" ] } ] } }, "required": [ "firewall" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.firewalls.update", "summary": "Update a firewall", "tags": [ "Firewall Management", "FirewallManagement" ], "parameters": [ { "name": "firewall", "in": "path", "required": true, "description": "The firewall ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFirewallRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Firewall updated successfully" }, "firewall": { "allOf": [ { "$ref": "#/components/schemas/FirewallResource" }, { "type": "object", "required": [ "rules" ] } ] } }, "required": [ "message", "firewall" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "delete": { "operationId": "v1.firewalls.destroy", "summary": "Delete a firewall", "tags": [ "Firewall Management", "FirewallManagement" ], "parameters": [ { "name": "firewall", "in": "path", "required": true, "description": "The firewall ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Firewall deleted successfully" } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/firewalls/{firewall}/attach": { "post": { "operationId": "v1.firewalls.attach", "description": "Attaches the firewall to a VPS, cache, or database instance. The firewall rules will be deployed asynchronously.", "summary": "Attach firewall to an instance", "tags": [ "Firewall Management", "FirewallManagement" ], "parameters": [ { "name": "firewall", "in": "path", "required": true, "description": "The firewall ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Firewall" }, { "type": "object", "properties": { "instance_type": { "type": "string", "enum": [ "vps", "cache", "database", "queue", "serverless" ] }, "instance_id": { "type": "string" } }, "required": [ "instance_type", "instance_id" ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Firewall attachment initiated" } }, "required": [ "message" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/firewalls/{firewall}/detach": { "post": { "operationId": "v1.firewalls.detach", "description": "Removes the firewall from a VPS, cache, or database instance.", "summary": "Detach firewall from an instance", "tags": [ "Firewall Management", "FirewallManagement" ], "parameters": [ { "name": "firewall", "in": "path", "required": true, "description": "The firewall ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Firewall" }, { "type": "object", "properties": { "instance_type": { "type": "string", "enum": [ "vps", "cache", "database", "queue", "serverless" ] }, "instance_id": { "type": "string" } }, "required": [ "instance_type", "instance_id" ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Firewall detached successfully" } }, "required": [ "message" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/firewalls/{firewall}/deploy": { "post": { "operationId": "v1.firewalls.deploy", "summary": "Deploy firewall to instances", "tags": [ "Firewall Management", "FirewallManagement" ], "parameters": [ { "name": "firewall", "in": "path", "required": true, "description": "The firewall ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Firewall deployment initiated" } }, "required": [ "message" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/health": { "get": { "operationId": "v1.health", "summary": "Check the health of the API v1 endpoints", "tags": [ "Health" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to access health check" ] } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/apps/catalog": { "get": { "operationId": "v1.apps.catalog", "description": "What can be created, with the resource profiles and published versions\neach type offers. An agent needs this before it can call store().", "summary": "List the app catalog", "tags": [ "Managed Apps", "AppManagement" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "app_type": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "versions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "default": { "type": "boolean" } }, "required": [ "default" ] } }, "resource_profiles": { "type": "array", "items": {} } }, "required": [ "app_type", "display_name", "description", "versions", "resource_profiles" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/apps": { "get": { "operationId": "v1.apps.index", "summary": "List app instances", "tags": [ "Managed Apps", "AppManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppInstanceResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.apps.store", "description": "Provisioning is asynchronous: poll the returned resource's\n`status_details.operation.terminal` rather than assuming the app is\nreachable on return. Send an Idempotency-Key header to make a retry\nsafe.", "summary": "Create an app instance", "tags": [ "Managed Apps", "AppManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreAppInstanceApiRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "App instance created" }, "instance": { "$ref": "#/components/schemas/AppInstanceResource" } }, "required": [ "message", "instance" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/apps/{appInstance}": { "get": { "operationId": "v1.apps.show", "summary": "Show an app instance", "tags": [ "Managed Apps", "AppManagement" ], "parameters": [ { "name": "appInstance", "in": "path", "required": true, "description": "The app instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "$ref": "#/components/schemas/AppInstanceResource" } }, "required": [ "instance" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.apps.update", "description": "Changes the resource profile. Scaling down is rejected because the\nunderlying volume cannot shrink.", "summary": "Resize an app instance", "tags": [ "Managed Apps", "AppManagement" ], "parameters": [ { "name": "appInstance", "in": "path", "required": true, "description": "The app instance ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAppInstanceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "App instance update initiated" }, "instance": { "$ref": "#/components/schemas/AppInstanceResource" } }, "required": [ "message", "instance" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } }, "delete": { "operationId": "v1.apps.destroy", "summary": "Delete an app instance", "tags": [ "Managed Apps", "AppManagement" ], "parameters": [ { "name": "appInstance", "in": "path", "required": true, "description": "The app instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "App deletion initiated" }, "status": { "type": "string", "const": "destroying" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "App cannot be destroyed in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/apps/{appInstance}/restart": { "post": { "operationId": "v1.apps.restart", "description": "The only lifecycle verb managed apps have \u2014 there is no start or stop.", "summary": "Restart an app instance", "tags": [ "Managed Apps", "AppManagement" ], "parameters": [ { "name": "appInstance", "in": "path", "required": true, "description": "The app instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "App restart initiated" }, "status": { "type": "string", "const": "restarting" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "App cannot be restarted in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/apps/{appInstance}/metrics": { "get": { "operationId": "v1.apps.metrics", "summary": "Read resource metrics", "tags": [ "Managed Apps", "AppManagement" ], "parameters": [ { "name": "appInstance", "in": "path", "required": true, "description": "The app instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "hours", "in": "query", "schema": { "type": "integer", "default": 24 } }, { "name": "step", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "metrics": { "anyOf": [ { "type": "object", "properties": { "cpu_usage": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "memory_usage": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "network": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "cpu_usage", "memory_usage", "network" ] }, { "type": "object", "properties": { "cpu_usage": { "type": "object", "properties": { "cpu_total_percentage": {}, "cpu_app_percentage": {}, "cpu_db_percentage": {} }, "required": [ "cpu_total_percentage", "cpu_app_percentage", "cpu_db_percentage" ] }, "memory_usage": { "type": "object", "properties": { "memory_total": {}, "memory_app": {}, "memory_db": {} }, "required": [ "memory_total", "memory_app", "memory_db" ] }, "network": { "type": "object", "properties": { "bytes_received_per_sec": {}, "bytes_sent_per_sec": {} }, "required": [ "bytes_received_per_sec", "bytes_sent_per_sec" ] } }, "required": [ "cpu_usage", "memory_usage", "network" ] } ] }, "summary": { "type": "object", "properties": { "cpu_percentage": { "type": "number" }, "memory_bytes": { "type": "string" }, "memory_mb": { "type": "number" }, "retrieved_at": { "type": [ "string", "null" ] } }, "required": [ "cpu_percentage", "memory_bytes", "memory_mb", "retrieved_at" ] } }, "required": [ "metrics", "summary" ] }, "meta": { "type": "object", "properties": { "hours": { "type": [ "object", "null" ] }, "step": { "type": "string" } }, "required": [ "hours", "step" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/apps/{appInstance}/credentials": { "get": { "operationId": "v1.apps.credentials", "description": "Behind its own ability rather than app:read: this returns a working\npassword, and a token that merely lists apps must not come away with\nthe credentials to every one of them.", "summary": "Read the admin credentials", "tags": [ "Managed Apps", "AppManagement" ], "parameters": [ { "name": "appInstance", "in": "path", "required": true, "description": "The app instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "admin_user": { "type": "string" }, "admin_password": { "type": "string" }, "url": { "type": "string" } }, "required": [ "admin_user", "admin_password", "url" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/apps/{appInstance}/logs": { "get": { "operationId": "v1.apps.logs", "description": "Returns the app container's output. Sidecar containers (database,\ncache) are excluded \u2014 they are platform components, not the app.", "summary": "Read application logs", "tags": [ "Managed Apps", "AppDiagnostics" ], "parameters": [ { "name": "appInstance", "in": "path", "required": true, "description": "The app instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "An opaque cursor from a previous response. It is a Loki\nnanosecond timestamp, so digits-only: rejecting everything else\nkeeps a hand-crafted value from reaching the upstream query.", "schema": { "type": "string", "pattern": "^\\d{1,25}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "level", "in": "query", "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceLogEntryResource" } } }, "required": [ "available", "entries" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "entries" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "The log store did not respond. This says nothing about the workload itself \u2014 retry shortly." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/apps/{appInstance}/events": { "get": { "operationId": "v1.apps.events", "description": "Returns platform events for the app's StatefulSet, pod and volumes.", "summary": "List Kubernetes events", "tags": [ "Managed Apps", "AppDiagnostics" ], "parameters": [ { "name": "appInstance", "in": "path", "required": true, "description": "The app instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosticEventResource" } } }, "required": [ "available", "events" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "events" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "Platform events could not be read for this resource." }, "retryable": { "type": "boolean", "description": "A missing RBAC grant will not fix itself on retry; a\ntransient API-server failure will." } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/apps/{appInstance}/diagnose": { "get": { "operationId": "v1.apps.diagnose", "description": "Correlates status, platform events, error logs and upgrade history\ninto ranked findings with remediation.", "summary": "Diagnose the app", "tags": [ "Managed Apps", "AppDiagnostics" ], "parameters": [ { "name": "appInstance", "in": "path", "required": true, "description": "The app instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/kubernetes": { "get": { "operationId": "v1.kubernetes.index", "tags": [ "Managed Kubernetes", "KubernetesManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KubernetesClusterResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.kubernetes.store", "tags": [ "Managed Kubernetes", "KubernetesManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreKubernetesClusterRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KubernetesClusterResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/kubernetes/{cluster}": { "get": { "operationId": "v1.kubernetes.show", "tags": [ "Managed Kubernetes", "KubernetesManagement" ], "parameters": [ { "name": "cluster", "in": "path", "required": true, "description": "The cluster ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KubernetesClusterResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.kubernetes.destroy", "tags": [ "Managed Kubernetes", "KubernetesManagement" ], "parameters": [ { "name": "cluster", "in": "path", "required": true, "description": "The cluster ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Kubernetes cluster deletion initiated." }, "data": { "$ref": "#/components/schemas/KubernetesClusterResource" } }, "required": [ "message", "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/kubernetes/{cluster}/scale": { "post": { "operationId": "v1.kubernetes.scale", "tags": [ "Managed Kubernetes", "KubernetesManagement" ], "parameters": [ { "name": "cluster", "in": "path", "required": true, "description": "The cluster ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 10 }, "pool": { "type": "string", "description": "Optional pool name; omitted \u2192 the cluster's first pool, which\nkeeps pre-#215 single-pool API clients working unchanged." } }, "required": [ "count" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cluster scale request submitted." }, "pool": { "type": "string" }, "target_count": { "type": "string" } }, "required": [ "message", "pool", "target_count" ] } } } }, "409": { "description": "An error\n\nAn error", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "The cluster must finish provisioning before it can be scaled." ] } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "This node pool is being removed and can no longer be scaled." ] } }, "required": [ "message" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/kubernetes/{cluster}/pools": { "post": { "operationId": "v1.kubernetes.pools.store", "tags": [ "Managed Kubernetes", "KubernetesManagement" ], "parameters": [ { "name": "cluster", "in": "path", "required": true, "description": "The cluster ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "minLength": 2, "maxLength": 20 }, "plan": { "type": "string", "enum": [ "nano", "micro", "small", "medium", "large", "xlarge" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 10 } }, "required": [ "name", "plan", "count" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KubernetesClusterResource" } }, "required": [ "data" ] } } } }, "409": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "The cluster must finish provisioning before node pools can change." ] } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/kubernetes/{cluster}/pools/{poolName}": { "delete": { "operationId": "v1.kubernetes.pools.destroy", "tags": [ "Managed Kubernetes", "KubernetesManagement" ], "parameters": [ { "name": "cluster", "in": "path", "required": true, "description": "The cluster ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "poolName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "409": { "description": "An error\n\nAn error", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "The cluster must finish provisioning before node pools can change." ] } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "This node pool is already being removed." ] } }, "required": [ "message" ] } ] } } } }, "422": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "A cluster needs at least one node pool \u2014 delete the cluster instead." ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/metric-alerts": { "get": { "operationId": "v1.metric-alerts.index", "description": "Filterable by the resource being watched, which is how an agent asks\n\"what am I already alerting on for this instance?\".", "summary": "List metric alerts", "tags": [ "Metric Alerts", "MetricAlertManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetricAlertResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.metric-alerts.store", "summary": "Create a metric alert", "tags": [ "Metric Alerts", "MetricAlertManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreMetricAlertApiRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Metric alert created" }, "alert": { "$ref": "#/components/schemas/MetricAlertResource" } }, "required": [ "message", "alert" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/metric-alerts/available-metrics/{resourceType}": { "get": { "operationId": "v1.metric-alerts.available-metrics", "description": "An agent needs this before it can call store(): the legal\n`metric_type` values differ per resource type, and each carries a\nsensible default threshold and duration.", "summary": "List the metrics available for a resource type", "tags": [ "Metric Alerts", "MetricAlertManagement" ], "parameters": [ { "name": "resourceType", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "resource_type": { "type": "string" }, "alertable": { "type": "boolean", "description": "A type can have metrics listed and still have no evaluator,\nin which case an alert on it would never fire. Say so here\nrather than letting store() be the first hint." }, "alertable_resource_types": { "type": "array", "items": {} } }, "required": [ "resource_type", "alertable", "alertable_resource_types" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/metric-alerts/{metricAlert}": { "get": { "operationId": "v1.metric-alerts.show", "summary": "Show a metric alert", "tags": [ "Metric Alerts", "MetricAlertManagement" ], "parameters": [ { "name": "metricAlert", "in": "path", "required": true, "description": "The metric alert ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "alert": { "$ref": "#/components/schemas/MetricAlertResource" } }, "required": [ "alert" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.metric-alerts.update", "description": "`metric_type` and the target are immutable \u2014 changing either makes the\nalert a different alert, and its history would no longer describe it.", "summary": "Update a metric alert", "tags": [ "Metric Alerts", "MetricAlertManagement" ], "parameters": [ { "name": "metricAlert", "in": "path", "required": true, "description": "The metric alert ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "comparison_operator": { "type": "string", "enum": [ "gt", "gte", "lt", "lte" ] }, "threshold_value": { "type": "number", "minimum": 0 }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 60 }, "name": { "type": [ "string", "null" ], "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "notification_channels": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "database", "mail", "webhook" ] } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Metric alert updated" }, "alert": { "$ref": "#/components/schemas/MetricAlertResource" } }, "required": [ "message", "alert" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.metric-alerts.destroy", "summary": "Delete a metric alert", "tags": [ "Metric Alerts", "MetricAlertManagement" ], "parameters": [ { "name": "metricAlert", "in": "path", "required": true, "description": "The metric alert ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Metric alert deleted" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/metric-alerts/{metricAlert}/toggle": { "patch": { "operationId": "v1.metric-alerts.toggle", "summary": "Enable or disable a metric alert", "tags": [ "Metric Alerts", "MetricAlertManagement" ], "parameters": [ { "name": "metricAlert", "in": "path", "required": true, "description": "The metric alert ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Metric alert enabled", "Metric alert disabled" ] }, "alert": { "$ref": "#/components/schemas/MetricAlertResource" } }, "required": [ "message", "alert" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/metric-alerts/{metricAlert}/history": { "get": { "operationId": "v1.metric-alerts.history", "description": "This is the alert's diagnosis: every threshold crossing, the value that\ncaused it, and the query that measured it.", "summary": "List an alert's trigger and resolve history", "tags": [ "Metric Alerts", "MetricAlertManagement" ], "parameters": [ { "name": "metricAlert", "in": "path", "required": true, "description": "The metric alert ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string" }, "metric_value": { "type": [ "number", "null" ] }, "threshold_value": { "type": [ "number", "null" ] }, "prometheus_query": { "type": [ "string", "null" ] }, "occurred_at": { "type": [ "string", "null" ] } }, "required": [ "event_type", "metric_value", "threshold_value", "prometheus_query", "occurred_at" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": [ "object", "null" ] } }, "required": [ "limit" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/notification-preferences": { "get": { "operationId": "v1.notification-preferences.show", "description": "Returns the notification preferences for the authenticated user's current team.", "summary": "Get notification preferences", "tags": [ "Notification Preferences", "NotificationPreference" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "preferences": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "channel": { "type": "string" }, "enabled": { "type": "string" }, "digest_frequency": { "type": "string" } }, "required": [ "category", "channel", "enabled", "digest_frequency" ] } }, "available_categories": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "string" }, "severity": { "type": "string" } }, "required": [ "value", "label", "group", "severity" ] } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "resource", "billing", "security", "snapshot", "team", "maintenance", "alert" ] }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "available_channels": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" } }, "required": [ "value", "label", "description", "icon" ] } }, "digest_options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label", "description" ] } } }, "required": [ "preferences", "available_categories", "groups", "available_channels", "digest_options" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.notification-preferences.update", "description": "Updates the notification preferences for the authenticated user's current team.", "summary": "Update notification preferences", "tags": [ "Notification Preferences", "NotificationPreference" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferences": { "type": "array", "items": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/NotificationCategory" }, "channel": { "$ref": "#/components/schemas/NotificationChannel" }, "enabled": { "type": "boolean" }, "digest_frequency": { "$ref": "#/components/schemas/DigestFrequency" } }, "required": [ "category", "channel", "enabled" ] }, "minItems": 1 } }, "required": [ "preferences" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Preferences updated successfully" }, "preferences": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "preferences" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/notification-preferences/reset": { "post": { "operationId": "v1.notification-preferences.reset", "description": "Resets notification preferences to team/system defaults.", "summary": "Reset preferences to defaults", "tags": [ "Notification Preferences", "NotificationPreference" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Preferences reset to defaults" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/notifications": { "get": { "operationId": "v1.notifications.index", "description": "Returns a paginated list of notifications for the authenticated user's current team.", "summary": "List notifications", "tags": [ "Notifications", "Notification" ], "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "pattern": "^[a-z_]+$", "maxLength": 50 } }, { "name": "unread", "in": "query", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DatabaseNotification" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "next_page_url": { "type": [ "string", "null" ] }, "unread_count": { "type": "integer", "minimum": 0 } }, "required": [ "data", "current_page", "last_page", "per_page", "total", "next_page_url", "unread_count" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/notifications/unread-count": { "get": { "operationId": "v1.notifications.unread-count", "description": "Returns the count of unread notifications for the authenticated user's current team.", "summary": "Get unread notification count", "tags": [ "Notifications", "Notification" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } }, "required": [ "count" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/notifications/{id}/read": { "patch": { "operationId": "v1.notifications.read", "description": "Marks a specific notification as read.", "summary": "Mark notification as read", "tags": [ "Notifications", "Notification" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Notification marked as read" }, "notification": { "type": "string" } }, "required": [ "message", "notification" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/notifications/mark-all-read": { "post": { "operationId": "v1.notifications.mark-all-read", "description": "Marks all notifications for the current team as read.", "summary": "Mark all notifications as read", "tags": [ "Notifications", "Notification" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "All notifications marked as read" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "message", "count" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/notifications/{id}": { "delete": { "operationId": "v1.notifications.destroy", "description": "Deletes a specific notification.", "summary": "Delete a notification", "tags": [ "Notifications", "Notification" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Notification deleted" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/storage/buckets": { "get": { "operationId": "v1.storage.buckets.index", "description": "Retrieves a paginated list of all S3-compatible storage buckets belonging to the authenticated user's team.", "summary": "List all storage buckets", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorageBucketResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.storage.buckets.store", "description": "Creates a new S3-compatible storage bucket for the authenticated user's team.", "summary": "Create a new storage bucket", "tags": [ "Object Storage", "StorageManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreStorageBucketRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Storage bucket created successfully" }, "bucket": { "$ref": "#/components/schemas/StorageBucketResource" } }, "required": [ "message", "bucket" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "A bucket with this name already exists. Please choose a different name." } }, "required": [ "error" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Your account is suspended for an unpaid invoice. Settle your balance to create storage." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/storage/buckets/{bucket}": { "get": { "operationId": "v1.storage.buckets.show", "description": "Retrieves details of a specific storage bucket.", "summary": "Get storage bucket details", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "description": "The bucket ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "bucket": { "$ref": "#/components/schemas/StorageBucketResource" }, "endpoint": { "type": "string" } }, "required": [ "bucket", "endpoint" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.storage.buckets.update", "description": "Updates settings for a storage bucket including tags, versioning, public access, CORS, and encryption.", "summary": "Update a storage bucket", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "description": "The bucket ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStorageBucketRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Bucket settings updated successfully" }, "bucket": { "$ref": "#/components/schemas/StorageBucketResource" } }, "required": [ "message", "bucket" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.storage.buckets.destroy", "description": "Deletes a storage bucket and all its contents.", "summary": "Delete a storage bucket", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "description": "The bucket ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Bucket deletion initiated" }, "status": { "type": "string", "const": "destroying" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Bucket cannot be deleted in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/storage/buckets/{bucket}/metrics": { "get": { "operationId": "v1.storage.buckets.metrics", "description": "Retrieves current metrics for a storage bucket including size and object count.", "summary": "Get storage bucket metrics", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "description": "The bucket ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "size_bytes": { "type": "integer" }, "size_human": { "type": "string" }, "object_count": { "type": "integer" }, "requests_24h": { "type": [ "integer", "null" ] }, "requests_24h_by_method": { "type": [ "array", "null" ], "items": {} }, "requests_24h_by_status": { "type": [ "string", "null" ] }, "error_rate_24h": { "type": [ "string", "null" ] }, "latency_24h_ms": { "type": [ "object", "null" ], "properties": { "p50": { "type": "string" }, "p95": { "type": "string" }, "mean": { "type": [ "number", "null" ] } }, "required": [ "p50", "p95", "mean" ] }, "egress_bytes_24h": { "type": "integer" }, "egress_human_24h": { "type": "string" }, "ingress_bytes_24h": { "type": "string" }, "ingress_human_24h": { "type": [ "string", "null" ] }, "monthly_cost_cents": { "type": "integer" }, "monthly_cost_dollars": { "type": "number" }, "source": { "type": "string", "enum": [ "deltas", "legacy" ] }, "freshness": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ] }, "metrics_precomputed_at": { "type": [ "string", "null" ] } }, "required": [ "size_bytes", "size_human", "object_count", "requests_24h", "requests_24h_by_method", "requests_24h_by_status", "error_rate_24h", "latency_24h_ms", "egress_bytes_24h", "egress_human_24h", "ingress_bytes_24h", "ingress_human_24h", "monthly_cost_cents", "monthly_cost_dollars", "source", "freshness", "last_sync_at", "metrics_precomputed_at" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/storage/buckets/{bucket}/metrics/trend": { "get": { "operationId": "v1.storage.buckets.metrics.trend", "description": "Query params:\n- window: 24h | 7d | 30d (default 24h)\n- resolution: 1m | 5m | 1h | 1d (default auto from window)", "summary": "Get storage bucket metrics trend (historical time-series)", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "description": "The bucket ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "window", "in": "query", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "bucket_id": { "type": "string" }, "window": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" }, { "type": "string" } ] }, "resolution": { "type": "string", "enum": [ "1d", "1h", "15m", "5m", "1m" ] }, "source": { "type": "string", "const": "deltas" }, "freshness": { "type": "string", "enum": [ "fresh", "lagging", "stale", "never" ] }, "generated_at": { "type": "string" }, "data": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "recorded_at": { "type": "string" }, "size_bytes": { "type": "integer" }, "object_count": { "type": "integer" }, "requests": { "type": "object", "properties": { "total": { "type": [ "integer", "null" ] }, "get": { "type": "integer" }, "put": { "type": "integer" }, "delete": { "type": "integer" }, "head": { "type": "integer" } }, "required": [ "total", "get", "put", "delete", "head" ] }, "status": { "type": "object", "properties": { "2xx": { "type": "integer" }, "4xx": { "type": "integer" }, "5xx": { "type": "integer" } }, "required": [ "2xx", "4xx", "5xx" ] }, "egress_bytes": { "type": "integer" }, "ingress_bytes": { "type": [ "integer", "null" ] }, "error_rate": { "type": [ "string", "null" ] }, "latency_ms": { "type": "object", "properties": { "mean": { "type": [ "string", "null" ] }, "p95_upper_bound": { "type": [ "integer", "null" ] } }, "required": [ "mean", "p95_upper_bound" ] }, "interval_seconds": { "type": [ "integer", "null" ] }, "requests_24h_total": { "type": [ "integer", "null" ] } }, "required": [ "recorded_at", "size_bytes", "object_count", "requests", "status", "egress_bytes", "ingress_bytes", "error_rate", "latency_ms", "interval_seconds", "requests_24h_total" ] } }, { "type": "array", "items": { "type": "object", "properties": { "recorded_at": { "type": "string" }, "size_bytes": { "type": "integer" }, "object_count": { "type": "integer" }, "requests": { "type": "object", "properties": { "total": { "type": [ "integer", "null" ] }, "get": { "type": "string" }, "put": { "type": "string" }, "delete": { "type": "string" }, "head": { "type": "string" } }, "required": [ "total", "get", "put", "delete", "head" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "2xx": { "type": "integer" }, "4xx": { "type": "integer" }, "5xx": { "type": "integer" } }, "required": [ "2xx", "4xx", "5xx" ] } ] }, "egress_bytes": { "type": "integer" }, "ingress_bytes": { "type": [ "integer", "null" ] }, "error_rate": { "type": [ "string", "null" ] }, "latency_ms": { "type": "object", "properties": { "mean": { "type": [ "string", "null" ] }, "p95_upper_bound": { "type": [ "integer", "null" ] } }, "required": [ "mean", "p95_upper_bound" ] }, "interval_seconds": { "type": "integer", "description": "Rollup rows don't carry `interval_seconds` since they're\nall hourly aggregates \u2014 callers can infer from resolution.", "const": 3600 }, "requests_24h_total": { "type": "null", "description": "Legacy compat: absent from rollup; emit null so clients can\ndistinguish \"rollup window, no legacy value\" from 0." } }, "required": [ "recorded_at", "size_bytes", "object_count", "requests", "status", "egress_bytes", "ingress_bytes", "error_rate", "latency_ms", "interval_seconds", "requests_24h_total" ] } } ] } }, "required": [ "bucket_id", "window", "resolution", "source", "freshness", "generated_at", "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/storage/buckets/{bucket}/metrics/top-objects": { "get": { "operationId": "v1.storage.buckets.metrics.top-objects", "description": "Params:\n- dimension: size | egress | requests (default 'size')\n- limit: 1..50 (default 10)\n\nRequires the hourly PrecomputeBucketHealthJob to have run at least once\nfor this bucket. Returns 428 if no top-objects snapshot exists yet.", "summary": "Top-N objects by size / egress / requests", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "description": "The bucket ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "dimension", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "bucket_id": { "type": "string" }, "dimension": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" }, { "type": "string" } ] }, "recorded_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "object_key": { "type": "string" }, "value": { "type": "integer" } }, "required": [ "rank", "object_key", "value" ] } } }, "required": [ "bucket_id", "dimension", "recorded_at", "items" ] }, { "type": "object", "properties": { "bucket_id": { "type": "string" }, "dimension": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" }, { "type": "string" } ] }, "recorded_at": { "type": "null" }, "items": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "bucket_id", "dimension", "recorded_at", "items" ] } ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/storage/buckets/{bucket}/metrics/health": { "get": { "operationId": "v1.storage.buckets.metrics.health", "description": "Returns whatever we have; nulls are expected until the hourly health\njob has visited this bucket.", "summary": "Bucket-level health: pending multipart uploads, deleted-version size,\nmetric freshness, last-shard check time", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "description": "The bucket ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "bucket_id": { "type": "string" }, "pending_multipart_count": { "type": [ "integer", "null" ] }, "pending_multipart_bytes": { "type": [ "integer", "null" ] }, "deleted_size_bytes": { "type": [ "integer", "null" ] }, "freshness": { "type": "string" }, "metrics_precomputed_at": { "type": [ "string", "null" ] }, "last_health_check_at": { "type": [ "string", "null" ] }, "health_check_status": { "type": [ "string", "null" ] } }, "required": [ "bucket_id", "pending_multipart_count", "pending_multipart_bytes", "deleted_size_bytes", "freshness", "metrics_precomputed_at", "last_health_check_at", "health_check_status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/storage/buckets/{bucket}/diagnose": { "get": { "operationId": "v1.storage.buckets.diagnose", "description": "Correlates provisioning status, quota headroom and usage freshness into\nranked findings with remediation. Most importantly it answers \"why are\n * my writes failing?\" \u2014 a bucket at its size limit has every PUT rejected\nby the storage backend, which is otherwise visible only in access logs.", "summary": "Diagnose the bucket", "tags": [ "Object Storage", "StorageDiagnostics" ], "parameters": [ { "name": "bucket", "in": "path", "required": true, "description": "The bucket ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/storage/access-keys": { "get": { "operationId": "v1.storage.access-keys.index", "description": "Retrieves a paginated list of all S3 access keys belonging to the authenticated user's team.", "summary": "List all storage access keys", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorageAccessKeyResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.storage.access-keys.store", "description": "Creates a new S3 access key for the authenticated user's team.\nThe secret access key is only returned once in this response.\nKeys have full access to all team buckets.", "summary": "Create a new storage access key", "tags": [ "Object Storage", "StorageManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 32 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "scope": { "type": [ "string", "null" ], "enum": [ "team", "buckets", null ] }, "bucket_permissions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "bucket_id": { "type": "string" }, "level": { "type": "string", "enum": [ "read", "readwrite", "full" ] } } }, "minItems": 1, "maxItems": 50 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Return credentials (secret only shown once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "access_key_id": { "type": "string" }, "secret_access_key": { "type": "string" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "team" ] } ] }, "bucket_permissions": { "type": "array", "items": { "type": "object", "properties": { "bucket_id": { "type": "string" }, "level": { "type": "string" } }, "required": [ "bucket_id", "level" ] } }, "expires_at": { "type": [ "string", "null" ] }, "message": { "type": "string", "const": "Access key created. Make sure to save the secret key - it will not be shown again." } }, "required": [ "id", "name", "access_key_id", "secret_access_key", "scope", "bucket_permissions", "expires_at", "message" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Failed to create access key in storage backend." } }, "required": [ "error" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Your account is suspended for an unpaid invoice. Settle your balance to create access keys." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/storage/access-keys/{accessKey}": { "get": { "operationId": "v1.storage.access-keys.show", "description": "Retrieves details of a specific storage access key. The secret key is not returned.", "summary": "Get storage access key details", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "accessKey", "in": "path", "required": true, "description": "The access key ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_key": { "$ref": "#/components/schemas/StorageAccessKeyResource" } }, "required": [ "access_key" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.storage.access-keys.destroy", "description": "Revokes a storage access key, preventing it from being used for future requests.", "summary": "Revoke a storage access key", "tags": [ "Object Storage", "StorageManagement" ], "parameters": [ { "name": "accessKey", "in": "path", "required": true, "description": "The access key ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Access key has been revoked" } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Access key is already revoked" } }, "required": [ "error" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/operations/{operation}": { "get": { "operationId": "v1.operations.show", "description": "`terminal` is the stop condition. Do not infer it from `state` \u2014 a state\nyou do not recognise must be treated as still running, not as finished.", "summary": "Show an operation", "tags": [ "Operation" ], "parameters": [ { "name": "operation", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "operation_id": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string", "const": "serverless_container" }, "kind": { "type": "string", "const": "deploy" }, "state": { "type": "string" }, "terminal": { "type": "boolean", "description": "Cast is redundant at runtime and load-bearing in the spec: the\ngenerator cannot infer through the local, and published this \u2014\nTHE stop condition for polling \u2014 as `\"type\": \"string\"`." }, "poll_after_ms": { "type": [ "integer", "null" ], "enum": [ 3000, null ] }, "revision": { "type": "string" }, "knative_revision": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "retryable": { "type": "boolean", "description": "Whether a retry can possibly help. A rejected registry credential\nnever clears on its own; a node eviction does." }, "reason": { "type": "null" } }, "required": [ "code", "message", "retryable", "reason" ] } }, "required": [ "operation_id", "resource_id", "resource_type", "kind", "state", "terminal", "poll_after_ms", "revision", "knative_revision", "image", "started_at", "finished_at", "error" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "operation_id": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string", "const": "serverless_container" }, "kind": { "type": "string", "const": "deploy" }, "state": { "type": "string", "const": "queued" }, "terminal": { "type": "boolean" }, "poll_after_ms": { "type": "integer", "const": 3000 }, "revision": { "type": "null" }, "knative_revision": { "type": "null" }, "image": { "type": "null" }, "started_at": { "type": "string" }, "finished_at": { "type": "null" }, "error": { "type": "null" } }, "required": [ "operation_id", "resource_id", "resource_type", "kind", "state", "terminal", "poll_after_ms", "revision", "knative_revision", "image", "started_at", "finished_at", "error" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } ] } } } }, "404": { "description": "A 404 rather than a 403: whether an id exists is itself\ninformation, and an id is guessable in a way a name is not.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "operation.not_found" }, "message": { "type": "string", "const": "No such operation." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/parameter-groups": { "get": { "operationId": "v1.parameter-groups.index", "description": "Supports `?type=cache|database|queue` and `?provider_type=redis` filters.", "summary": "List parameter groups for the current team (includes system groups)", "tags": [ "Parameter Groups", "ParameterGroup" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ParameterGroupResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.parameter-groups.store", "tags": [ "Parameter Groups", "ParameterGroup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "cache", "database", "queue" ] }, "provider_type": { "type": "string", "maxLength": 50 }, "family": { "type": [ "string", "null" ], "maxLength": 50 }, "description": { "type": [ "string", "null" ] }, "parameters": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "locked_parameters": { "type": [ "array", "null" ], "items": { "type": "string" } }, "is_default": { "type": "boolean" } }, "required": [ "name", "type", "provider_type", "parameters" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Parameter group created" }, "parameter_group": { "$ref": "#/components/schemas/ParameterGroupResource" } }, "required": [ "message", "parameter_group" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/parameter-groups/{parameterGroup}": { "get": { "operationId": "v1.parameter-groups.show", "tags": [ "Parameter Groups", "ParameterGroup" ], "parameters": [ { "name": "parameterGroup", "in": "path", "required": true, "description": "The parameter group ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "parameter_group": { "$ref": "#/components/schemas/ParameterGroupResource" } }, "required": [ "parameter_group" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.parameter-groups.update", "tags": [ "Parameter Groups", "ParameterGroup" ], "parameters": [ { "name": "parameterGroup", "in": "path", "required": true, "description": "The parameter group ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "parameters": { "type": "array", "items": { "type": "string" } }, "locked_parameters": { "type": [ "array", "null" ], "items": { "type": "string" } }, "is_default": { "type": "boolean" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Parameter group updated" }, "parameter_group": { "$ref": "#/components/schemas/ParameterGroupResource" } }, "required": [ "message", "parameter_group" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.parameter-groups.destroy", "tags": [ "Parameter Groups", "ParameterGroup" ], "parameters": [ { "name": "parameterGroup", "in": "path", "required": true, "description": "The parameter group ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Parameter group deleted" } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "System parameter groups cannot be deleted." } }, "required": [ "error" ] } ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/parameter-groups/{parameterGroup}/clone": { "post": { "operationId": "v1.parameter-groups.clone", "tags": [ "Parameter Groups", "ParameterGroup" ], "parameters": [ { "name": "parameterGroup", "in": "path", "required": true, "description": "The parameter group ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Parameter group cloned" }, "parameter_group": { "$ref": "#/components/schemas/ParameterGroupResource" } }, "required": [ "message", "parameter_group" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/admin/partner/tier": { "get": { "operationId": "v1.partner.tier", "description": "Returns the partner's current volume tier, discount rate, and progress to next tier.", "summary": "Get current partner tier and discount information", "tags": [ "Partner Management", "PartnerTeam" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "discount": { "type": "string" }, "discount_percentage": { "type": "string" }, "min_spend_cents": { "type": "string" }, "current_spend_cents": { "type": "integer" }, "current_spend": { "type": "string" }, "next_tier": { "type": "null" } }, "required": [ "name", "discount", "discount_percentage", "min_spend_cents", "current_spend_cents", "current_spend", "next_tier" ] }, { "type": "object", "properties": { "name": { "type": "string", "const": "fixed" }, "discount": { "type": "number" }, "discount_percentage": { "type": "string" }, "min_spend_cents": { "type": "integer" }, "current_spend_cents": { "type": "integer" }, "current_spend": { "type": "string" }, "next_tier": { "type": "null" } }, "required": [ "name", "discount", "discount_percentage", "min_spend_cents", "current_spend_cents", "current_spend", "next_tier" ] }, { "type": "object", "properties": { "name": { "type": "string", "const": "none" }, "discount": { "type": "integer" }, "discount_percentage": { "type": "string" }, "min_spend_cents": { "type": "integer" }, "current_spend_cents": { "type": "integer" }, "current_spend": { "type": "string" }, "next_tier": { "type": "null" } }, "required": [ "name", "discount", "discount_percentage", "min_spend_cents", "current_spend_cents", "current_spend", "next_tier" ] } ] }, "available_tiers": { "type": "array", "items": {} } }, "required": [ "tier", "available_tiers" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/admin/partner/sub-teams": { "get": { "operationId": "v1.partner.sub-teams.index", "description": "Returns a paginated list of all sub-customer teams managed by the partner.", "summary": "List partner's sub-customer teams", "tags": [ "Partner Management", "PartnerTeam" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tenant_name": { "type": "string" }, "created_at": { "type": "string" }, "owner": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, "has_api_key": { "type": "boolean" } }, "required": [ "id", "name", "tenant_name", "created_at", "owner", "has_api_key" ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.partner.sub-teams.store", "description": "Creates a new team linked to the partner. The team owner will be created if they don't exist.", "summary": "Create a sub-customer team", "tags": [ "Partner Management", "PartnerTeam" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartnerSubTeamRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Sub-customer team created successfully" }, "team": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "tenant_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "tenant_name", "created_at" ] }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, "api_key": { "type": "string" }, "user_created": { "type": "boolean" } }, "required": [ "message", "team", "owner", "api_key", "user_created" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/admin/partner/sub-teams/{team}": { "get": { "operationId": "v1.partner.sub-teams.show", "description": "Returns details of a specific sub-customer team.", "summary": "Get a specific sub-customer team", "tags": [ "Partner Management", "PartnerTeam" ], "parameters": [ { "name": "team", "in": "path", "required": true, "description": "The team ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/admin/partner/sub-teams/{team}/usage": { "get": { "operationId": "v1.partner.sub-teams.usage", "description": "Returns billing usage for a sub-customer team for the specified period.", "summary": "Get usage for a specific sub-customer team", "tags": [ "Partner Management", "PartnerTeam" ], "parameters": [ { "name": "team", "in": "path", "required": true, "description": "The team ID", "schema": { "type": "integer" } }, { "name": "period", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/admin/partner/sub-teams/{team}/regenerate-api-key": { "post": { "operationId": "v1.partner.sub-teams.regenerate-api-key", "description": "Generates a new API key for the specified sub-customer team.\nThe previous key will be immediately invalidated.", "summary": "Regenerate API key for a sub-customer team", "tags": [ "Partner Management", "PartnerTeam" ], "parameters": [ { "name": "team", "in": "path", "required": true, "description": "The team ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/admin/partner/usage": { "get": { "operationId": "v1.partner.usage", "description": "Returns aggregated billing usage for all sub-customer teams for the specified period.", "summary": "Get aggregated usage across all sub-customer teams", "tags": [ "Partner Management", "PartnerTeam" ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "partner_team_id": { "type": "integer" }, "partner_team_name": { "type": "string" }, "billing_period": {}, "sub_team_count": { "type": "integer", "minimum": 0 }, "total_cost_cents": { "type": "string" }, "total_cost": { "type": "number" }, "partner_discount": { "type": "string" }, "breakdown_by_team": { "type": "array", "items": {} }, "breakdown_by_resource": { "type": "array", "items": {} } }, "required": [ "partner_team_id", "partner_team_name", "billing_period", "sub_team_count", "total_cost_cents", "total_cost", "partner_discount", "breakdown_by_team", "breakdown_by_resource" ] }, { "type": "object", "properties": { "partner_team_id": { "type": "integer" }, "partner_team_name": { "type": "string" }, "billing_period": {}, "sub_team_count": { "type": "integer" }, "total_cost_cents": { "type": "integer" }, "total_cost": { "type": "number" }, "breakdown_by_team": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "breakdown_by_resource": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "partner_team_id", "partner_team_name", "billing_period", "sub_team_count", "total_cost_cents", "total_cost", "breakdown_by_team", "breakdown_by_resource" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/queue/{queueInstance}/logs": { "get": { "operationId": "v1.queue.logs", "description": "Returns bounded, cursor-paged broker logs from the platform log store.", "summary": "Fetch queue instance logs", "tags": [ "Queue Diagnostics", "QueueDiagnostics" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "An opaque cursor from a previous response. It is a Loki\nnanosecond timestamp, so digits-only: rejecting everything else\nkeeps a hand-crafted value from reaching the upstream query.", "schema": { "type": "string", "pattern": "^\\d{1,25}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "level", "in": "query", "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceLogEntryResource" } } }, "required": [ "available", "entries" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "entries" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "The log store did not respond. This says nothing about the workload itself \u2014 retry shortly." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/queue/{queueInstance}/events": { "get": { "operationId": "v1.queue.events", "description": "Returns curated platform events for the broker's pods, workload and\nvolumes.", "summary": "List Kubernetes events", "tags": [ "Queue Diagnostics", "QueueDiagnostics" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosticEventResource" } } }, "required": [ "available", "events" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "events" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "Platform events could not be read for this resource." }, "retryable": { "type": "boolean", "description": "A missing RBAC grant will not fix itself on retry; a\ntransient API-server failure will." } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/queue/{queueInstance}/diagnose": { "get": { "operationId": "v1.queue.diagnose", "description": "Correlates status, events and log availability into ranked findings\nwith remediation.", "summary": "Diagnose the instance", "tags": [ "Queue Diagnostics", "QueueDiagnostics" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/queue": { "get": { "operationId": "v1.queue.index", "tags": [ "Queue Management", "QueueManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/QueueInstance" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.queue.store", "tags": [ "Queue Management", "QueueManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreApiQueueInstanceRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Queue instance created successfully" }, "instance": { "$ref": "#/components/schemas/QueueInstance" } }, "required": [ "message", "instance" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/queue/{queueInstance}": { "get": { "operationId": "v1.queue.show", "tags": [ "Queue Management", "QueueManagement" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "$ref": "#/components/schemas/QueueInstance" }, "connection_info": { "type": "string" }, "management_url": { "type": "string" }, "monthly_cost": { "type": "number" }, "status_details": { "description": "Poll operation.terminal, never the status string. Wrapped in the\nshared resources so the generated spec describes the shape \u2014\na bare array publishes as `\"type\": \"string\"`.", "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "$ref": "#/components/schemas/CapabilitiesResource" } }, "required": [ "instance", "connection_info", "management_url", "monthly_cost", "status_details", "capabilities" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.queue.update", "tags": [ "Queue Management", "QueueManagement" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiQueueInstanceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Queue instance update initiated" }, "instance": { "anyOf": [ { "$ref": "#/components/schemas/QueueInstance" }, { "type": "null" } ] } }, "required": [ "message", "instance" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } }, "delete": { "operationId": "v1.queue.destroy", "tags": [ "Queue Management", "QueueManagement" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Queue instance destruction initiated." } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Cannot destroy instance in current status. Please stop the instance first." } }, "required": [ "error" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/queue/{queueInstance}/start": { "post": { "operationId": "v1.queue.start", "tags": [ "Queue Management", "QueueManagement" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Queue instance start initiated." }, "instance": { "anyOf": [ { "$ref": "#/components/schemas/QueueInstance" }, { "type": "null" } ] } }, "required": [ "message", "instance" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Cannot start instance in current status." } }, "required": [ "error" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/queue/{queueInstance}/stop": { "post": { "operationId": "v1.queue.stop", "tags": [ "Queue Management", "QueueManagement" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Queue instance stop initiated." }, "instance": { "anyOf": [ { "$ref": "#/components/schemas/QueueInstance" }, { "type": "null" } ] } }, "required": [ "message", "instance" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Cannot stop instance in current status." } }, "required": [ "error" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/queue/{queueInstance}/connection-info": { "get": { "operationId": "v1.queue.connection-info", "tags": [ "Queue Management", "QueueManagement" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "amqp_url": { "type": "string" }, "management_url": { "type": "string" }, "host": { "type": [ "string", "null" ] }, "port": { "type": "integer" }, "management_port": { "type": "integer" }, "vhost": { "type": "string" }, "username": { "type": "string", "const": "admin" }, "password": { "type": [ "string", "null" ] } }, "required": [ "amqp_url", "management_url", "host", "port", "management_port", "vhost", "username", "password" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/queue/{queueInstance}/metrics": { "get": { "operationId": "v1.queue.metrics", "description": "Mirrors the cache and database metrics endpoints; the service behind it\nalready powered the dashboard and was simply never exposed to the API.", "summary": "Broker metrics", "tags": [ "Queue Management", "QueueManagement" ], "parameters": [ { "name": "queueInstance", "in": "path", "required": true, "description": "The queue instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "connections": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "channels": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "queues": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "memory_percent": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "health_status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "unknown" ] } ] } }, "required": [ "connections", "channels", "queues", "memory_percent", "health_status" ] }, "health": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "unknown" }, "issues": { "type": "array", "prefixItems": [ { "type": "string", "const": "Unable to fetch metrics" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "issues" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "critical", "warning" ] }, "issues": { "type": "array", "items": { "type": "string", "enum": [ "Memory usage above 80%", "Memory usage critical (>95%)", "File descriptor usage above 80%" ] } }, "memory_percent": { "type": "number" }, "connections": { "type": "integer" }, "channels": { "type": "integer" }, "queues": { "type": "integer" }, "fd_percent": { "type": "number" }, "disk_free_bytes": { "type": "integer" } }, "required": [ "status", "issues", "memory_percent", "connections", "channels", "queues", "fd_percent", "disk_free_bytes" ] } ] }, "instance": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "summary", "health", "instance" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/registry/context": { "get": { "operationId": "v1.registry.context", "description": "Where this project may push, and how much room is left. Use\n`push_prefix` verbatim rather than deriving it from the project name.", "summary": "Registry context for the current project", "tags": [ "RegistryContext" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "registry_host": { "type": "string" }, "namespace": { "type": "string" }, "push_prefix": { "type": "string", "description": "Given verbatim so a client never has to build it. Concatenate a\nrepository and tag onto this and the push is correctly scoped." }, "repositories": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "limit": { "type": [ "integer", "null" ], "description": "0 is the unlimited sentinel in account_limits; null is\nclearer over the wire than a magic zero." }, "can_create": { "type": "boolean" } }, "required": [ "used", "limit", "can_create" ] }, "storage": { "type": "object", "properties": { "used_bytes": { "type": "integer" }, "limit_bytes": { "type": [ "integer", "null" ] }, "can_push": { "type": "boolean" } }, "required": [ "used_bytes", "limit_bytes", "can_push" ] } }, "required": [ "registry_host", "namespace", "push_prefix", "repositories", "storage" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "registry.no_project" }, "message": { "type": "string", "const": "No project resolved for this token. Send X-Team-Id." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/registry/verify-push": { "get": { "operationId": "v1.registry.verify-push", "description": "Answers before the push what Distribution would only tell you afterwards,\nand never in terms you could act on. `permitted: false` always carries a\nmachine-readable `code` and a concrete `hint`.", "summary": "Check whether a push would be permitted", "tags": [ "RegistryContext" ], "parameters": [ { "name": "repository", "in": "query", "required": true, "description": "Accept a bare repository path, with or without the host and tag.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "repository": { "type": "string" }, "permitted": { "type": "boolean" }, "namespace": { "type": "string" }, "provided_namespace": {}, "push_reference": { "type": "string" } }, "required": [ "repository", "permitted", "namespace", "provided_namespace", "push_reference" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "repository": { "type": "string" }, "permitted": { "type": "boolean" }, "namespace": { "type": "string" }, "provided_namespace": {}, "push_reference": { "type": "null" } }, "required": [ "repository", "permitted", "namespace", "provided_namespace", "push_reference" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "registry.quota_exceeded" }, "message": { "type": [ "string", "null" ] }, "retryable": { "type": "boolean", "description": "Freeing space or deleting a repository makes the identical\nrequest succeed, so this is retryable \u2014 after you act." }, "hint": { "type": "string", "const": "Delete unused tags or repositories, or upgrade the plan, then retry." } }, "required": [ "code", "message", "retryable", "hint" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "repository": { "type": "string" }, "permitted": { "type": "boolean" }, "namespace": { "type": "string" }, "provided_namespace": {}, "push_reference": { "type": "null" } }, "required": [ "repository", "permitted", "namespace", "provided_namespace", "push_reference" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "registry.namespace_mismatch" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "hint": { "type": "string" } }, "required": [ "code", "message", "retryable", "hint" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "registry.no_project" }, "message": { "type": "string", "const": "No project resolved for this token. Send X-Team-Id." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/registry/preflight": { "get": { "operationId": "v1.registry.preflight", "description": "Answers in one call everything a deploy needs to be true: the image is in\na namespace this project owns, a credential with pull rights exists, the\ntag is actually present, and it was built for an architecture the cluster\ncan run. Each answer that is `false` carries the code and remediation for\nthat specific cause.", "summary": "Check whether an image can be deployed, before deploying it", "tags": [ "RegistryContext" ], "parameters": [ { "name": "image", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "image": { "type": "string" }, "registry_host": { "type": [ "string", "null" ] }, "namespace": { "type": "string" }, "repository": { "type": [ "string", "null" ] }, "reference": { "type": "string" }, "in_namespace": { "type": [ "boolean", "null" ] }, "external": { "type": "boolean" }, "credential": { "anyOf": [ { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "push_pull", "pull" ] }, "keys": { "type": "integer", "minimum": 0 }, "push_capable": { "type": "boolean" } }, "required": [ "scope", "keys", "push_capable" ] }, { "type": "object", "properties": { "scope": { "type": "string", "const": "none" }, "keys": { "type": "integer" }, "push_capable": { "type": "boolean" } }, "required": [ "scope", "keys", "push_capable" ] } ] }, "manifest": { "anyOf": [ { "type": "object", "properties": { "exists": { "type": "boolean" }, "digest": { "type": "null" }, "media_type": { "type": "null" }, "size_bytes": { "type": "null" }, "architectures": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "reachable": { "type": "boolean" }, "error": { "type": "null" } }, "required": [ "exists", "digest", "media_type", "size_bytes", "architectures", "reachable", "error" ] }, { "type": "object", "properties": { "exists": { "type": "boolean" }, "digest": { "type": [ "string", "null" ], "description": "The header is authoritative: it is the digest the registry will\nserve this reference by, which is what a pull pins to." }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size_bytes": { "type": [ "integer", "null" ], "enum": [ 0, null ] }, "architectures": { "anyOf": [ { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, { "type": "array", "items": {} } ] }, "reachable": { "type": "boolean" }, "error": { "type": "null" } }, "required": [ "exists", "digest", "media_type", "size_bytes", "architectures", "reachable", "error" ] }, { "type": "object", "properties": { "exists": { "type": "boolean" }, "digest": { "type": "null" }, "media_type": { "type": "null" }, "size_bytes": { "type": "null" }, "architectures": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "reachable": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "exists", "digest", "media_type", "size_bytes", "architectures", "reachable", "error" ] }, { "type": "object", "properties": { "exists": { "type": "boolean" }, "digest": { "type": "null" }, "media_type": { "type": "null" }, "size_bytes": { "type": "null" }, "architectures": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "reachable": { "type": "boolean" }, "error": { "type": "string", "const": "The registry could not be reached." } }, "required": [ "exists", "digest", "media_type", "size_bytes", "architectures", "reachable", "error" ] } ] }, "quota": { "type": "object", "properties": { "repositories_used": { "type": "integer", "minimum": 0 }, "repositories_limit": { "type": [ "integer", "null" ] }, "can_create_repository": { "type": "boolean" }, "storage_used_bytes": { "type": "integer" }, "storage_limit_bytes": { "type": [ "integer", "null" ] } }, "required": [ "repositories_used", "repositories_limit", "can_create_repository", "storage_used_bytes", "storage_limit_bytes" ] }, "can_pull": { "type": [ "boolean", "null" ] }, "findings": { "type": "array", "items": {} } }, "required": [ "image", "registry_host", "namespace", "repository", "reference", "in_namespace", "external", "credential", "manifest", "quota", "can_pull", "findings" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "registry.no_project" }, "message": { "type": "string", "const": "No project resolved for this token. Send X-Team-Id." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/registry/events": { "post": { "operationId": "v1.registryEvent", "tags": [ "RegistryEvent" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "integer" } }, "required": [ "accepted" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "invalid envelope" } }, "required": [ "error" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "unauthorized" } }, "required": [ "error" ] } } } } } } }, "/resources/search": { "get": { "operationId": "v1.resources.search", "tags": [ "ResourceSearch" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "string" } } }, "required": [ "results" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/ssh-keys": { "get": { "operationId": "v1.ssh-keys.index", "description": "Retrieves a paginated list of all SSH public keys belonging to the authenticated user.", "summary": "List all SSH keys", "tags": [ "SSH Key Management", "SshKeyManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SshKeyResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.ssh-keys.store", "description": "Adds a new SSH public key to the authenticated user's account. The key must be in OpenSSH format.", "summary": "Store a new SSH key", "tags": [ "SSH Key Management", "SshKeyManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreSshKeyRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "SSH key created successfully" }, "key": { "$ref": "#/components/schemas/SshKeyResource" } }, "required": [ "message", "key" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/ssh-keys/{sshKey}": { "get": { "operationId": "v1.ssh-keys.show", "summary": "Show a specific SSH key", "tags": [ "SSH Key Management", "SshKeyManagement" ], "parameters": [ { "name": "sshKey", "in": "path", "required": true, "description": "The ssh key ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/SshKeyResource" } }, "required": [ "key" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.ssh-keys.destroy", "summary": "Delete an SSH key", "tags": [ "SSH Key Management", "SshKeyManagement" ], "parameters": [ { "name": "sshKey", "in": "path", "required": true, "description": "The ssh key ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "SSH key deleted successfully" } }, "required": [ "message" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless/{serverlessContainer}/diagnose": { "get": { "operationId": "v1.serverless.diagnose", "description": "Correlates status, classified cluster events and log availability into\nranked findings. `degraded` is terminal but not an outage \u2014 a new\nrevision failed while an older one keeps serving traffic \u2014 so read\n`findings[].severity` rather than assuming the site is down.", "summary": "Diagnose the container", "tags": [ "Serverless Containers", "ServerlessDiagnose" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless/{serverlessContainer}/logs": { "get": { "operationId": "v1.serverless.logs", "description": "Returns bounded, cursor-paged log entries from the platform log store.", "summary": "Fetch container logs", "tags": [ "Serverless Diagnostics", "ServerlessDiagnostics" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "An opaque cursor from a previous response. It is a Loki\nnanosecond timestamp, so digits-only: rejecting everything else\nkeeps a hand-crafted value from reaching the upstream query.", "schema": { "type": "string", "pattern": "^\\d{1,25}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "level", "in": "query", "schema": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, { "name": "container", "in": "query", "schema": { "type": "string", "enum": [ "user-container", "queue-proxy", "all" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessLogEntryResource" } } }, "required": [ "available", "entries" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "entries" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "serverless.logs_unavailable" }, "message": { "type": "string", "const": "The log store did not respond. This says nothing about the container itself \u2014 retry shortly." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/serverless/{serverlessContainer}/revisions": { "get": { "operationId": "v1.serverless.revisions", "description": "Returns every revision owned by the container's Knative Service with its\nconditions, plus Service and Route readiness.", "summary": "List Knative revisions", "tags": [ "Serverless Diagnostics", "ServerlessDiagnostics" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessRevisionResource" } }, "service": { "anyOf": [ { "$ref": "#/components/schemas/ServerlessServiceStatusResource" }, { "type": "null" } ] }, "route": { "anyOf": [ { "$ref": "#/components/schemas/ServerlessRouteStatusResource" }, { "type": "null" } ] } }, "required": [ "available", "revisions", "service", "route" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "revisions": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "service": { "type": "null" }, "route": { "type": "null" } }, "required": [ "available", "revisions", "service", "route" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "const": "serverless.revisions_unavailable" }, "message": { "type": "string", "const": "The platform could not read this container's revisions. Retry shortly." }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless/{serverlessContainer}/events": { "get": { "operationId": "v1.serverless.events", "description": "Returns curated platform events for the container's Service, revisions\nand pods.", "summary": "List Kubernetes events", "tags": [ "Serverless Diagnostics", "ServerlessDiagnostics" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessEventResource" } } }, "required": [ "available", "events" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "events" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "serverless.events_not_permitted", "serverless.events_unavailable" ] }, "message": { "type": "string", "const": "Platform events could not be read for this container. Revision conditions remain available and are the more reliable signal." }, "retryable": { "type": "boolean", "description": "A missing RBAC grant will not fix itself on retry; a\ntransient API-server failure will." } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless": { "get": { "operationId": "v1.serverless.index", "description": "Retrieves a paginated list of all serverless containers belonging to the authenticated user's team.", "summary": "List all serverless containers", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.serverless.store", "description": "Creates a new serverless container with the specified configuration.\n\nWhich fields are required depends on `deployment_type`: `docker_image`\nneeds `image` and `image_tag`; `git_repository` needs `repository_url`,\n`source_type` and `git_auth_type`; `zip_upload` builds from code you\nupload afterwards with the deploy endpoint.", "summary": "Create a new serverless container", "tags": [ "Serverless Management", "ServerlessManagement" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StoreServerlessContainerRequest" }, { "type": "object", "properties": { "name": { "type": "string", "description": "Display name." }, "slug": { "type": "string", "description": "DNS label, unique per project. Lowercase alphanumeric and hyphens, max 63 chars." }, "description": { "type": "string", "description": "Free-text description." }, "deployment_type": { "type": "string", "description": "One of `docker_image`, `git_repository`, `zip_upload`. Determines which fields below are required." }, "port": { "type": "integer", "description": "Port your process listens on. Some platform ports are reserved and rejected." }, "resource_profile": { "type": "string", "description": "CPU/memory profile slug." }, "min_scale": { "type": "integer", "description": "Minimum replicas. 0 enables scale-to-zero." }, "max_scale": { "type": "integer", "description": "Maximum replicas. Must be >= min_scale." }, "image": { "type": "string", "description": "Image reference, e.g. `cr.danubedata.ro/{team-slug}/api`. Required for `docker_image`. Must be amd64." }, "image_tag": { "type": "string", "description": "Tag to deploy. Required for `docker_image`. Prefer an immutable tag over `latest`." }, "registry_credential_id": { "type": "string", "description": "Registry credential UUID. Omit for images in your own team namespace \u2014 those authenticate automatically." }, "source_type": { "type": "string", "description": "Build strategy for `git_repository` and `zip_upload`: `dockerfile` or `buildpack`." }, "repository_url": { "type": "string", "description": "Git remote. Required for `git_repository`." }, "repository_branch": { "type": "string", "description": "Branch to build. Defaults to the repository default." }, "build_context_path": { "type": "string", "description": "Build context within the repository." }, "git_auth_type": { "type": "string", "description": "One of `none`, `ssh_key`, `access_token`. Required for `git_repository`." }, "git_credentials": { "type": "string", "description": "Deploy key or token. Required unless `git_auth_type` is `none`. Write-only \u2014 never returned." }, "auto_build_on_push": { "type": "boolean", "description": "Rebuild automatically on push to the tracked branch." }, "auto_deploy": { "type": "boolean", "description": "Deploy automatically once a build succeeds." }, "environment_variables": { "type": "object", "description": "Object of string key/value pairs injected into the container." }, "concurrency_target": { "type": "integer", "description": "Requests handled concurrently per replica before scaling out." }, "scaling_metric": { "type": "string", "description": "Autoscaling signal: `rps` or `concurrency`." }, "scaling_target": { "type": "integer", "description": "Target value for the chosen scaling metric." }, "timeout_seconds": { "type": "integer", "description": "Per-request timeout, 1-3600." }, "progress_deadline_seconds": { "type": "integer", "description": "How long a rollout may take before it is failed, 30-1800." }, "health_check_path": { "type": "string", "description": "Absolute path probed for readiness, e.g. `/healthz`." }, "cpu_request": { "type": "string", "description": "CPU request override, e.g. `250m`." }, "cpu_limit": { "type": "string", "description": "CPU limit override." }, "memory_request": { "type": "string", "description": "Memory request override, e.g. `256Mi`." }, "memory_limit": { "type": "string", "description": "Memory limit override." } }, "required": [ "name", "slug", "deployment_type", "port", "resource_profile", "min_scale", "max_scale" ] } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Serverless container created successfully" }, "container": { "allOf": [ { "$ref": "#/components/schemas/ServerlessContainerResource" }, { "type": "object", "required": [ "team", "user" ] } ] }, "operation": { "type": "object", "properties": { "operation_id": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string", "const": "serverless_container" }, "state": { "type": "string", "const": "queued" }, "terminal": { "type": "boolean" }, "poll_after_ms": { "type": "integer", "const": 3000 }, "poll_url": { "type": "string" } }, "required": [ "operation_id", "resource_id", "resource_type", "state", "terminal", "poll_after_ms", "poll_url" ] } }, "required": [ "message", "container", "operation" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/serverless/{serverlessContainer}": { "get": { "operationId": "v1.serverless.show", "summary": "Show a specific serverless container", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "container": { "allOf": [ { "$ref": "#/components/schemas/ServerlessContainerResource" }, { "type": "object", "required": [ "team", "user", "deployments" ] } ] }, "metrics": { "type": "array", "items": {} }, "url": { "type": "string" }, "monthly_cost": { "type": "string" } }, "required": [ "container", "metrics", "url", "monthly_cost" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.serverless.update", "summary": "Update a serverless container", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServerlessContainerRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "Serverless container update initiated" }, "container": { "allOf": [ { "$ref": "#/components/schemas/ServerlessContainerResource" }, { "type": "object", "required": [ "team", "user" ] } ] } }, "required": [ "message", "container" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Serverless container deployment source changed" }, "container": { "allOf": [ { "$ref": "#/components/schemas/ServerlessContainerResource" }, { "type": "object", "required": [ "team", "user" ] } ] } }, "required": [ "message", "container" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.serverless.destroy", "summary": "Delete a serverless container", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless/{serverlessContainer}/deployments": { "get": { "operationId": "v1.serverless.deployments", "summary": "Get deployments for a serverless container", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless/{serverlessContainer}/usage": { "get": { "operationId": "v1.serverless.usage", "summary": "Get usage records for a serverless container", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": {}, "usage": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessUsageRecord" } }, "summary": { "type": "object", "properties": { "total_requests": { "type": "string" }, "total_compute_seconds": { "type": "string" }, "total_cost_cents": { "type": "number" }, "total_cost_dollars": { "type": "number" } }, "required": [ "total_requests", "total_compute_seconds", "total_cost_cents", "total_cost_dollars" ] } }, "required": [ "period", "usage", "summary" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless/{serverlessContainer}/deploy": { "post": { "operationId": "v1.serverless.deploy", "summary": "Deploy a serverless container from uploaded ZIP file", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 512000 kilobytes." } }, "required": [ "file" ] } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Deployment initiated." }, "container_id": { "type": "string" }, "status": { "type": "string", "const": "building" }, "operation": { "type": "object", "properties": { "operation_id": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string", "const": "serverless_container" }, "state": { "type": "string", "const": "queued" }, "terminal": { "type": "boolean" }, "poll_after_ms": { "type": "integer", "const": 3000 }, "poll_url": { "type": "string" } }, "required": [ "operation_id", "resource_id", "resource_type", "state", "terminal", "poll_after_ms", "poll_url" ] } }, "required": [ "message", "container_id", "status", "operation" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless/{serverlessContainer}/redeploy": { "post": { "operationId": "v1.serverless.redeploy", "description": "Rolls out a new revision using the container's current image. For\ndocker_image containers this re-pulls the configured tag, so a CI/CD\npipeline can push a new image and then call this to deploy it. Knative\nshifts traffic only once the new revision is healthy, so the rollout is\nzero-downtime.", "summary": "Redeploy a serverless container", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Redeployment initiated. A new revision will be created with the latest image." }, "container_id": { "type": "string" }, "status": { "type": "string", "const": "provisioning" } }, "required": [ "message", "container_id", "status" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Container cannot be redeployed in its current state." } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "A deployment is already in progress. Cancel it first if you want to retry." } }, "required": [ "error" ] } ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless/{serverlessContainer}/builds/latest": { "get": { "operationId": "v1.serverless.builds.latest", "summary": "Get the latest build for a serverless container", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "array", "null" ], "items": {} } }, "required": [ "data" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/serverless/{serverlessContainer}/builds/{build}/cancel": { "post": { "operationId": "v1.serverless.builds.cancel", "summary": "Cancel an in-progress build for a serverless container", "tags": [ "Serverless Management", "ServerlessManagement" ], "parameters": [ { "name": "serverlessContainer", "in": "path", "required": true, "description": "The serverless container ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "build", "in": "path", "required": true, "description": "The build ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Build cancelled." } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Build is not in progress." } }, "required": [ "error" ] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/snapshots/vps": { "get": { "operationId": "v1.snapshots.vps.index", "description": "Retrieves a paginated list of all VPS snapshots for the authenticated user's team.", "summary": "List VPS snapshots", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/VpsSnapshotResource" }, { "type": "object", "required": [ "vps_instance" ] } ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to read snapshots" ] } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.snapshots.vps.store", "summary": "Create VPS snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vps_instance_id": { "type": "string" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "vps_instance_id", "name" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS snapshot creation initiated" }, "snapshot": { "$ref": "#/components/schemas/VpsSnapshotResource" } }, "required": [ "message", "snapshot" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to create snapshots" ] } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/snapshots/vps/{vpsSnapshot}/restore": { "post": { "operationId": "v1.snapshots.vps.restore", "summary": "Restore VPS snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "vpsSnapshot", "in": "path", "required": true, "description": "The vps snapshot ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS snapshot restore initiated" } }, "required": [ "message" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to restore snapshots" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/snapshots/vps/{vpsSnapshot}": { "delete": { "operationId": "v1.snapshots.vps.destroy", "summary": "Delete VPS snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "vpsSnapshot", "in": "path", "required": true, "description": "The vps snapshot ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS snapshot deletion initiated" } }, "required": [ "message" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to delete snapshots" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/snapshots/cache": { "get": { "operationId": "v1.snapshots.cache.index", "summary": "List cache snapshots", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/CacheSnapshotResource" }, { "type": "object", "required": [ "cache_instance" ] } ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to read snapshots" ] } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.snapshots.cache.store", "summary": "Create cache snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cache_instance_id": { "type": "string" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "cache_instance_id", "name" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache snapshot creation initiated" }, "snapshot": { "$ref": "#/components/schemas/CacheSnapshotResource" } }, "required": [ "message", "snapshot" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to create snapshots" ] } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/snapshots/cache/{cacheSnapshot}/restore": { "post": { "operationId": "v1.snapshots.cache.restore", "summary": "Restore cache snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "cacheSnapshot", "in": "path", "required": true, "description": "The cache snapshot ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache snapshot restore initiated" } }, "required": [ "message" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to restore snapshots" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/snapshots/cache/{cacheSnapshot}/clone": { "post": { "operationId": "v1.snapshots.cache.clone", "description": "Creates a new cache instance using data from an existing snapshot.\nSupports both local VolumeSnapshot and Velero offsite backup sources.", "summary": "Clone cache instance from snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "cacheSnapshot", "in": "path", "required": true, "description": "The cache snapshot ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneApiCacheInstanceRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache clone initiated" }, "instance": { "allOf": [ { "$ref": "#/components/schemas/CacheInstanceResource" }, { "type": "object", "required": [ "provider" ] } ] } }, "required": [ "message", "instance" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "properties": { "name": { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "name" ] } }, "required": [ "message", "errors" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/snapshots/cache/{cacheSnapshot}": { "delete": { "operationId": "v1.snapshots.cache.destroy", "summary": "Delete cache snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "cacheSnapshot", "in": "path", "required": true, "description": "The cache snapshot ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cache snapshot deletion initiated" } }, "required": [ "message" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to delete snapshots" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/snapshots/database": { "get": { "operationId": "v1.snapshots.database.index", "summary": "List database snapshots", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/DatabaseSnapshotResource" }, { "type": "object", "required": [ "database_instance" ] } ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to read snapshots" ] } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.snapshots.database.store", "summary": "Create database snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "database_instance_id": { "type": "string" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "database_instance_id", "name" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database snapshot creation initiated" }, "snapshot": { "$ref": "#/components/schemas/DatabaseSnapshotResource" } }, "required": [ "message", "snapshot" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to create snapshots" ] } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/snapshots/database/{databaseSnapshot}/restore": { "post": { "operationId": "v1.snapshots.database.restore", "summary": "Restore database snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "databaseSnapshot", "in": "path", "required": true, "description": "The database snapshot ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database snapshot restore initiated" } }, "required": [ "message" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to restore snapshots" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/snapshots/database/{databaseSnapshot}/clone": { "post": { "operationId": "v1.snapshots.database.clone", "description": "Creates a new database instance using data from an existing snapshot.\nSupports both local VolumeSnapshot and Velero offsite backup sources.", "summary": "Clone database instance from snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "databaseSnapshot", "in": "path", "required": true, "description": "The database snapshot ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneApiDatabaseInstanceRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database clone initiated" }, "instance": { "allOf": [ { "$ref": "#/components/schemas/DatabaseInstanceResource" }, { "type": "object", "required": [ "provider", "engine" ] } ] } }, "required": [ "message", "instance" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/snapshots/database/{databaseSnapshot}": { "delete": { "operationId": "v1.snapshots.database.destroy", "summary": "Delete database snapshot", "tags": [ "Snapshot Management", "SnapshotManagement" ], "parameters": [ { "name": "databaseSnapshot", "in": "path", "required": true, "description": "The database snapshot ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Database snapshot deletion initiated" } }, "required": [ "message" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to delete snapshots" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}/diagnose": { "get": { "operationId": "v1.static-sites.diagnose", "description": "Correlates status, the latest build and custom-domain verification into\nranked findings with remediation.", "summary": "Diagnose the site", "tags": [ "Static Site Diagnostics", "StaticSiteDiagnostics" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/teams/{team}/static-sites": { "get": { "operationId": "v1.teams.static-sites.index", "summary": "List static sites for a specific team (CLI team selection)", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "team", "in": "path", "required": true, "description": "The team ID", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaticSiteResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.teams.static-sites.store", "summary": "Create a static site under a specific team (CLI team selection)", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "team", "in": "path", "required": true, "description": "The team ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreApiStaticSiteRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Static site created successfully." }, "data": { "$ref": "#/components/schemas/StaticSiteResource" } }, "required": [ "message", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/static-sites": { "post": { "operationId": "v1.static-sites.store", "summary": "Create a new static site (cli_push deploy method)", "tags": [ "StaticSiteApi" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreApiStaticSiteRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Static site created successfully." }, "data": { "$ref": "#/components/schemas/StaticSiteResource" } }, "required": [ "message", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } }, "get": { "operationId": "v1.static-sites.index", "summary": "List all static sites for the current team", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaticSiteResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}": { "get": { "operationId": "v1.static-sites.show", "summary": "Show a specific static site", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaticSiteResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.static-sites.destroy", "summary": "Delete a static site", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Static site deletion initiated." } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Site cannot be deleted in its current state." }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}/deploy": { "post": { "operationId": "v1.static-sites.deploy", "summary": "Deploy a static site via file upload (tar.gz or zip)", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: kilobytes." } }, "required": [ "file" ] } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Deployment initiated." }, "site_id": { "type": "string" }, "status": { "type": "string", "const": "building" } }, "required": [ "message", "site_id", "status" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}/builds/latest": { "get": { "operationId": "v1.static-sites.builds.latest", "summary": "Get the latest build for a static site", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaticSiteBuildResource" } }, "required": [ "data" ] }, { "type": "object", "properties": { "data": { "type": "null" } }, "required": [ "data" ] } ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}/builds/{build}/cancel": { "post": { "operationId": "v1.static-sites.builds.cancel", "summary": "Cancel an in-progress build for a static site", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "build", "in": "path", "required": true, "description": "The build ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Build cancelled." } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Build is not in progress." } }, "required": [ "error" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}/deployments": { "get": { "operationId": "v1.static-sites.deployments", "summary": "List deployments for a static site", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "per_page", "in": "query", "schema": { "type": "string", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaticSiteDeploymentResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}/deployments/{deployment}/activate": { "post": { "operationId": "v1.static-sites.deployments.activate", "summary": "Activate a specific deployment (rollback)", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "deployment", "in": "path", "required": true, "description": "The deployment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "This deployment cannot be activated because it has no image." } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "This site is suspended and cannot be rolled back." } }, "required": [ "error" ] } ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}/domains": { "get": { "operationId": "v1.static-sites.domains.index", "summary": "List custom domains for a static site", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaticSiteDomainResource" } } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.static-sites.domains.store", "summary": "Add a custom domain to a static site", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "maxLength": 253 } }, "required": [ "domain" ] } } } }, "responses": { "422": { "$ref": "#/components/responses/ValidationException" }, "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Domain added. Configure the DNS TXT record to verify ownership." }, "data": { "$ref": "#/components/schemas/StaticSiteDomainResource" } }, "required": [ "message", "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}/domains/{domain}/verify": { "post": { "operationId": "v1.static-sites.domains.verify", "summary": "Trigger verification for a domain", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "domain", "in": "path", "required": true, "description": "The domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Verification started. This may take a few moments." } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/static-sites/{staticSite}/domains/{domain}": { "delete": { "operationId": "v1.static-sites.domains.destroy", "summary": "Remove a custom domain", "tags": [ "StaticSiteApi" ], "parameters": [ { "name": "staticSite", "in": "path", "required": true, "description": "The static site ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "domain", "in": "path", "required": true, "description": "The domain ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Domain removed successfully." } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/uptime-checks": { "get": { "operationId": "v1.uptime-checks.index", "summary": "List uptime checks", "tags": [ "Uptime Checks", "UptimeCheckManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UptimeCheckResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.uptime-checks.store", "description": "The check starts in `unknown` and reports nothing until its first probe\nlands \u2014 poll `status_details.operation.terminal` rather than treating\nthe create response as a verdict on the target.", "summary": "Create an uptime check", "tags": [ "Uptime Checks", "UptimeCheckManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreUptimeCheckApiRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Uptime check created" }, "check": { "$ref": "#/components/schemas/UptimeCheckResource" } }, "required": [ "message", "check" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/uptime-checks/{uptimeCheck}": { "get": { "operationId": "v1.uptime-checks.show", "summary": "Show an uptime check", "tags": [ "Uptime Checks", "UptimeCheckManagement" ], "parameters": [ { "name": "uptimeCheck", "in": "path", "required": true, "description": "The uptime check ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "check": { "$ref": "#/components/schemas/UptimeCheckResource" } }, "required": [ "check" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.uptime-checks.update", "description": "`enabled` is not settable here \u2014 use the toggle endpoint, which also\ncloses any open incident.", "summary": "Update an uptime check", "tags": [ "Uptime Checks", "UptimeCheckManagement" ], "parameters": [ { "name": "uptimeCheck", "in": "path", "required": true, "description": "The uptime check ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUptimeCheckRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Uptime check updated" }, "check": { "$ref": "#/components/schemas/UptimeCheckResource" } }, "required": [ "message", "check" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } }, "delete": { "operationId": "v1.uptime-checks.destroy", "summary": "Delete an uptime check", "tags": [ "Uptime Checks", "UptimeCheckManagement" ], "parameters": [ { "name": "uptimeCheck", "in": "path", "required": true, "description": "The uptime check ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Uptime check deleted" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/uptime-checks/{uptimeCheck}/toggle": { "patch": { "operationId": "v1.uptime-checks.toggle", "description": "Pausing closes any open incident so a resumed check does not report an\noutage that ended while it was asleep. Resuming clears the streak\ncounters and schedules an immediate probe.", "summary": "Pause or resume an uptime check", "tags": [ "Uptime Checks", "UptimeCheckManagement" ], "parameters": [ { "name": "uptimeCheck", "in": "path", "required": true, "description": "The uptime check ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Uptime check resumed", "Uptime check paused" ] }, "check": { "$ref": "#/components/schemas/UptimeCheckResource" } }, "required": [ "message", "check" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/uptime-checks/{uptimeCheck}/results": { "get": { "operationId": "v1.uptime-checks.results", "summary": "List recent probe results", "tags": [ "Uptime Checks", "UptimeCheckManagement" ], "parameters": [ { "name": "uptimeCheck", "in": "path", "required": true, "description": "The uptime check ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "checked_at": { "type": [ "string", "null" ] }, "ok": { "type": "boolean" }, "status_code": { "type": [ "integer", "null" ] }, "response_time_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "checked_at", "ok", "status_code", "response_time_ms", "error" ] } }, "meta": { "type": "object", "description": "Raw results are pruned; the caller should not read an empty\npage as \"nothing ever failed\".", "properties": { "limit": { "type": [ "object", "null" ] }, "retention_days": { "type": "integer" } }, "required": [ "limit", "retention_days" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/uptime-checks/{uptimeCheck}/incidents": { "get": { "operationId": "v1.uptime-checks.incidents", "description": "Incidents are never pruned, so this is the durable outage history \u2014\nunlike raw results.", "summary": "List outage incidents", "tags": [ "Uptime Checks", "UptimeCheckManagement" ], "parameters": [ { "name": "uptimeCheck", "in": "path", "required": true, "description": "The uptime check ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "started_at": { "type": [ "string", "null" ] }, "ended_at": { "type": [ "string", "null" ] }, "ongoing": { "type": "boolean" }, "first_error": { "type": [ "string", "null" ] } }, "required": [ "id", "started_at", "ended_at", "ongoing", "first_error" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": [ "object", "null" ] } }, "required": [ "limit" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/uptime-checks/{uptimeCheck}/test": { "post": { "operationId": "v1.uptime-checks.test", "description": "Runs synchronously and records nothing \u2014 it does not create a result,\nmove the status, or open an incident. Use it to validate a target\nbefore relying on a check.", "summary": "Probe the target once, right now", "tags": [ "Uptime Checks", "UptimeCheckManagement" ], "parameters": [ { "name": "uptimeCheck", "in": "path", "required": true, "description": "The uptime check ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status_code": { "type": [ "integer", "null" ] }, "response_time_ms": { "type": "integer" }, "error": { "type": [ "string", "null" ], "enum": [ "too_many_redirects", "keyword_missing", "status_mismatch", "http_error", "timeout", "tls", "refused", "dns", "redirect_blocked", "blocked_target", null ] } }, "required": [ "ok", "status_code", "response_time_ms", "error" ] }, "meta": { "type": "object", "properties": { "recorded": { "type": "boolean" } }, "required": [ "recorded" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/uptime-checks/{uptimeCheck}/diagnose": { "get": { "operationId": "v1.uptime-checks.diagnose", "description": "Separates \"your target is down\" from \"your monitor stopped running\",\nand surfaces the things a status alone hides: an expiring certificate,\nand repeated short outages that read as healthy in between.", "summary": "Diagnose the check", "tags": [ "Uptime Checks", "UptimeDiagnostics" ], "parameters": [ { "name": "uptimeCheck", "in": "path", "required": true, "description": "The uptime check ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/events": { "get": { "operationId": "v1.vps.events", "description": "Returns curated platform events for the VM, its instance, launcher pod\nand disks.", "summary": "List Kubernetes events", "tags": [ "VPS Diagnostics", "VpsDiagnostics" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosticEventResource" } } }, "required": [ "available", "events" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "events" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "Platform events could not be read for this resource." }, "retryable": { "type": "boolean", "description": "A missing RBAC grant will not fix itself on retry; a\ntransient API-server failure will." } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/diagnose": { "get": { "operationId": "v1.vps.diagnose", "description": "Correlates status and platform events into ranked findings with\nremediation. Guest-side problems are out of scope.", "summary": "Diagnose the instance", "tags": [ "VPS Diagnostics", "VpsDiagnostics" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps": { "get": { "operationId": "v1.vps.index", "description": "Retrieves a paginated list of all VPS instances belonging to the authenticated user's team.", "summary": "List all VPS instances", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VpsInstanceResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.vps.store", "description": "Creates a new VPS instance with the specified configuration. A default deny firewall is automatically created for security.", "summary": "Create a new VPS instance", "tags": [ "VPS Management", "VpsManagement" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreVpsInstanceRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS instance created successfully with default firewall" }, "instance": { "$ref": "#/components/schemas/VpsInstanceResource" }, "firewall_created": { "type": "boolean" } }, "required": [ "message", "instance", "firewall_created" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Security policy could not be applied" }, "message": { "type": "string", "const": "The required default firewall could not be created, so the instance was not started." }, "instance_id": { "type": "string" } }, "required": [ "error", "message", "instance_id" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/vps/images": { "get": { "operationId": "v1.vps.images", "description": "Returns a flat list of all available operating system images for VPS deployment.", "summary": "Get available VPS images", "tags": [ "VPS Management", "VpsManagement" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "image": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "distro": { "type": "string" }, "version": { "type": "string" }, "family": { "type": [ "string", "null" ] }, "default_user": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "root" ] } ] } }, "required": [ "id", "image", "label", "description", "distro", "version", "family", "default_user" ] } } }, "required": [ "images" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/images/grouped": { "get": { "operationId": "v1.vps.images.grouped", "description": "Returns available operating system images grouped by distribution for easier navigation.", "summary": "Get grouped VPS images", "tags": [ "VPS Management", "VpsManagement" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "distro": { "type": "string" }, "name": { "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "image": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "family": { "type": [ "string", "null" ] }, "default_user": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "root" ] } ] } }, "required": [ "id", "image", "label", "description", "version", "family", "default_user" ] } } }, "required": [ "distro", "name", "images" ] } } }, "required": [ "groups" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/plans": { "get": { "operationId": "v1.vps.plans", "description": "Returns every offered VPS plan with specs and the current monthly price in EUR.", "summary": "List available VPS plans with current pricing", "tags": [ "VPS Management", "VpsManagement" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" }, "type": { "type": "string" }, "cpu_cores": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "memory_gb": { "type": "number" }, "storage_gb": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "monthly_cost": { "type": "number" } }, "required": [ "slug", "display_name", "type", "cpu_cores", "memory_gb", "storage_gb", "monthly_cost" ] } } }, "required": [ "plans" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}": { "get": { "operationId": "v1.vps.show", "summary": "Show a specific VPS instance", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "$ref": "#/components/schemas/VpsInstanceResource" }, "connection_info": { "type": "object", "properties": { "public_ip": { "type": [ "string", "null" ] }, "private_ip": { "type": [ "string", "null" ] }, "ipv6_address": { "type": [ "string", "null" ] }, "vnc_access_url": { "type": [ "string", "null" ] }, "internal_dns": { "type": "string" }, "internal_fqdn": { "type": "string" } }, "required": [ "public_ip", "private_ip", "ipv6_address", "vnc_access_url", "internal_dns", "internal_fqdn" ] }, "monthly_cost": { "type": "number" } }, "required": [ "instance", "connection_info", "monthly_cost" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.vps.update", "summary": "Update a VPS instance", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVpsInstanceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS instance update initiated" }, "instance": { "$ref": "#/components/schemas/VpsInstanceResource" } }, "required": [ "message", "instance" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.vps.destroy", "summary": "Delete a VPS instance", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS instance deletion initiated" }, "status": { "type": "string", "const": "destroying" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "VPS cannot be destroyed in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/start": { "post": { "operationId": "v1.vps.start", "summary": "Start a VPS instance", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS start initiated" }, "status": { "type": "string", "const": "starting" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "VPS cannot be started in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/stop": { "post": { "operationId": "v1.vps.stop", "summary": "Stop a VPS instance", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS stop initiated" }, "status": { "type": "string", "const": "stopping" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "VPS cannot be stopped in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/reboot": { "post": { "operationId": "v1.vps.reboot", "summary": "Reboot a VPS instance", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS reboot initiated" }, "status": { "type": "string", "const": "rebooting" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "VPS cannot be rebooted in its current state" }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/reinstall": { "post": { "operationId": "v1.vps.reinstall", "description": "Reinstalls the VPS with a new OS image. This will destroy all data on the instance.", "summary": "Reinstall a VPS instance with a new operating system", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "string", "maxLength": 500 }, "custom_cloud_init": { "type": [ "string", "null" ], "maxLength": 10000 } }, "required": [ "image" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "VPS reinstall initiated. All data will be destroyed and a fresh OS will be installed." }, "status": { "type": "string", "const": "reinstalling" } }, "required": [ "message", "status" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/status": { "get": { "operationId": "v1.vps.status", "summary": "Get VPS status", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "status_label": { "type": "string", "enum": [ "Pending", "Provisioning", "Starting", "Running", "Stopping", "Stopped", "Rebooting", "Restoring", "Reinstalling", "Error", "Destroying", "Recreating" ] }, "status_color": { "type": "string", "enum": [ "yellow", "blue", "green", "orange", "gray", "red" ] }, "can_be_started": { "type": "boolean" }, "can_be_stopped": { "type": "boolean" }, "can_be_rebooted": { "type": "boolean" }, "can_be_destroyed": { "type": "boolean" }, "is_transitional": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "status", "status_label", "status_color", "can_be_started", "can_be_stopped", "can_be_rebooted", "can_be_destroyed", "is_transitional", "updated_at" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/metrics": { "get": { "operationId": "v1.vps.metrics", "summary": "Get VPS metrics from Prometheus", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Failed to retrieve metrics. The instance may not be running." }, "error": { "type": "string", "const": "metrics_unavailable" } }, "required": [ "message", "error" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "cpu": { "type": "object", "properties": { "usage_percent": { "type": "number" }, "cores": { "type": "integer" }, "sockets": { "type": "integer" }, "threads": { "type": "integer" } }, "required": [ "usage_percent", "cores", "sockets", "threads" ] }, "memory": { "type": "object", "properties": { "used_gb": { "type": "number" }, "total_gb": { "type": "integer" }, "usage_percent": { "type": "number" } }, "required": [ "used_gb", "total_gb", "usage_percent" ] }, "storage": { "type": "object", "properties": { "used_gb": { "type": "number" }, "total_gb": { "type": "integer" }, "usage_percent": { "type": "number" } }, "required": [ "used_gb", "total_gb", "usage_percent" ] }, "network": { "type": "object", "properties": { "rx_bytes_per_sec": { "type": "number", "description": "Network throughput" }, "tx_bytes_per_sec": { "type": "number" }, "error_rate": { "type": "number", "description": "Network health metrics" }, "status": { "type": "string", "enum": [ "Healthy", "Warning", "Critical" ] } }, "required": [ "rx_bytes_per_sec", "tx_bytes_per_sec", "error_rate", "status" ] }, "uptime_seconds": { "type": "integer" }, "timestamp": { "type": [ "string", "null" ] } }, "required": [ "cpu", "memory", "storage", "network", "uptime_seconds", "timestamp" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/password": { "get": { "operationId": "v1.vps.password", "description": "Returns the console master password for a VPS instance.\nThis password is always set (auto-generated or matches the SSH password).", "summary": "Get VPS console/SSH password", "tags": [ "VPS Management", "VpsManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": [ "string", "null" ] }, "username": { "type": "string", "const": "root" }, "public_ip": { "type": [ "string", "null" ] }, "auth_method": { "type": "string" } }, "required": [ "password", "username", "public_ip", "auth_method" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "This VPS uses SSH key authentication. No password is stored." } }, "required": [ "error" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/volumes": { "get": { "operationId": "v1.vps.volumes.index", "summary": "List volumes on an instance", "tags": [ "VPS Volumes", "VpsVolumeManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VpsVolumeResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "v1.vps.volumes.store", "description": "The volume is provisioned asynchronously: poll the returned resource's\n`status_details.operation.terminal` rather than assuming it is usable\non return.", "summary": "Create and attach a volume", "tags": [ "VPS Volumes", "VpsVolumeManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "minLength": 2, "maxLength": 30 }, "size_gb": { "type": "integer", "minimum": 10, "maximum": 500 } }, "required": [ "name", "size_gb" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Volume creation initiated" }, "volume": { "allOf": [ { "$ref": "#/components/schemas/VpsVolumeResource" }, { "type": "object", "required": [ "vps_instance" ] } ] } }, "required": [ "message", "volume" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/volumes/{vpsVolume}": { "get": { "operationId": "v1.vps.volumes.show", "summary": "Show a volume", "tags": [ "VPS Volumes", "VpsVolumeManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "vpsVolume", "in": "path", "required": true, "description": "The vps volume ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "volume": { "allOf": [ { "$ref": "#/components/schemas/VpsVolumeResource" }, { "type": "object", "required": [ "vps_instance" ] } ] } }, "required": [ "volume" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.vps.volumes.update", "description": "Expansion only \u2014 Longhorn grows a volume online but cannot shrink one.", "summary": "Resize a volume", "tags": [ "VPS Volumes", "VpsVolumeManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "vpsVolume", "in": "path", "required": true, "description": "The vps volume ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "size_gb": { "type": "integer", "minimum": 1, "maximum": 500 } }, "required": [ "size_gb" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Volume resize initiated" }, "volume": { "allOf": [ { "$ref": "#/components/schemas/VpsVolumeResource" }, { "type": "object", "required": [ "vps_instance" ] } ] } }, "required": [ "message", "volume" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.vps.volumes.destroy", "description": "Detaching destroys the volume and its data \u2014 there is no detached-but-kept\nstate in this product.", "summary": "Detach and delete a volume", "tags": [ "VPS Volumes", "VpsVolumeManagement" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "vpsVolume", "in": "path", "required": true, "description": "The vps volume ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Volume detach initiated" }, "status": { "type": "string", "const": "detaching" } }, "required": [ "message", "status" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Volume cannot be detached in its current state." }, "status": { "type": "string" } }, "required": [ "error", "status" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/volumes/{vpsVolume}/events": { "get": { "operationId": "v1.vps.volumes.events", "description": "Returns platform events for the volume's PersistentVolumeClaim \u2014\nprovisioning, binding and expansion.", "summary": "List Kubernetes events", "tags": [ "VPS Volumes", "VpsVolumeDiagnostics" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "vpsVolume", "in": "path", "required": true, "description": "The vps volume ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosticEventResource" } } }, "required": [ "available", "events" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "available", "events" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string", "const": "Platform events could not be read for this resource." }, "retryable": { "type": "boolean", "description": "A missing RBAC grant will not fix itself on retry; a\ntransient API-server failure will." } }, "required": [ "code", "message", "retryable" ] }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/vps/{vpsInstance}/volumes/{vpsVolume}/diagnose": { "get": { "operationId": "v1.vps.volumes.diagnose", "description": "Correlates the volume's status, its claim's events and the state of the\nVPS it belongs to into ranked findings with remediation.", "summary": "Diagnose the volume", "tags": [ "VPS Volumes", "VpsVolumeDiagnostics" ], "parameters": [ { "name": "vpsInstance", "in": "path", "required": true, "description": "The vps instance ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "vpsVolume", "in": "path", "required": true, "description": "The vps volume ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "verdict": { "type": "string" }, "status": { "type": "object", "properties": { "summary": { "type": "string" }, "health": { "type": "string" }, "observed_at": { "type": "string" }, "stale": { "type": "boolean" }, "operation": { "type": "object", "properties": { "state": { "type": "string" }, "terminal": { "type": "boolean" } }, "required": [ "state", "terminal" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "source": { "type": "string" }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "observed_at": { "type": "string" } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FindingResource" } }, "sections": { "type": "object", "properties": { "events": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "available", "count", "truncated" ] }, "logs": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "sampled_lines": { "type": "integer" } }, "required": [ "available", "sampled_lines" ] } }, "required": [ "events", "logs" ] } }, "required": [ "verdict", "status", "findings", "sections" ] }, "error": { "type": "null" }, "meta": { "type": "object", "description": "Free-form per endpoint. Cast to an object so an empty meta\nserialises as `{}` rather than `[]` \u2014 a client typing it as\na map breaks on the array form. The `@var` is what the spec\ngenerator reads: it cannot infer through the cast, and\nwithout it publishes `meta` as `\"type\": \"string\"`." } }, "required": [ "success", "data", "error", "meta" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/volumes": { "get": { "operationId": "v1.volumes.index", "description": "The instance-scoped listing needs an instance ID; this one does not,\nwhich is what an agent taking stock of a team's storage actually wants.", "summary": "List every volume in the team", "tags": [ "VPS Volumes", "VpsVolumeManagement" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VpsVolumeResource" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/webhooks/config": { "get": { "operationId": "v1.webhooks.config.show", "description": "Returns the current webhook configuration for the authenticated user's team.", "summary": "Show webhook configuration", "tags": [ "Webhook Configuration", "WebhookConfig" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": [ "string", "null" ] }, "webhook_enabled": { "type": "boolean" }, "has_secret": { "type": "boolean" } }, "required": [ "webhook_url", "webhook_enabled", "has_secret" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to read webhook configuration" ] } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "v1.webhooks.config.update", "description": "Updates the webhook URL and enabled status. A secret is automatically generated if not already set.", "summary": "Update webhook configuration", "tags": [ "Webhook Configuration", "WebhookConfig" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string", "format": "uri" }, "webhook_enabled": { "type": "boolean" } }, "required": [ "webhook_url" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Webhook configuration updated successfully" }, "webhook_url": { "type": [ "string", "null" ] }, "webhook_enabled": { "type": "boolean" }, "webhook_secret": { "type": [ "string", "null" ] } }, "required": [ "message", "webhook_url", "webhook_enabled", "webhook_secret" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to update webhook configuration" ] } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/webhooks/config/regenerate-secret": { "post": { "operationId": "v1.webhooks.config.regenerate-secret", "description": "Generates a new webhook signing secret. The old secret will be invalidated immediately.", "summary": "Regenerate webhook secret", "tags": [ "Webhook Configuration", "WebhookConfig" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Webhook secret regenerated successfully" }, "webhook_secret": { "type": "string" } }, "required": [ "message", "webhook_secret" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to regenerate webhook secret" ] } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/webhooks/deliveries": { "get": { "operationId": "v1.webhooks.deliveries", "summary": "List webhook deliveries", "tags": [ "Webhook Configuration", "WebhookConfig" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "pagination" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Insufficient permissions to read webhook deliveries" ] } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer", "bearerFormat": "sanctum" } }, "schemas": { "AddApiDatabaseReplicasRequest": { "type": "object", "properties": { "replica_count": { "type": "integer", "minimum": 1, "maximum": 10 } }, "required": [ "replica_count" ], "title": "AddApiDatabaseReplicasRequest" }, "AlertStatus": { "type": "string", "enum": [ "active", "triggered", "resolved", "disabled" ], "title": "AlertStatus" }, "AppInstanceResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "app_type": { "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/AppInstanceStatus" } ] }, "status_details": { "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "$ref": "#/components/schemas/CapabilitiesResource" }, "version": { "type": "string" }, "resource_profile": { "type": "string" }, "datacenter": { "type": "string" }, "subdomain": { "type": "string" }, "hostname": { "type": "string" }, "url": { "type": "string" }, "admin_user": { "type": "string", "description": "The admin USERNAME is not a secret and is needed to sign in;\nthe password is not here on purpose." }, "monthly_cost_cents": { "type": "integer" }, "monthly_cost_dollars": { "type": "number" }, "automated_snapshots_enabled": { "type": "boolean" }, "current_bundle_id": { "type": [ "string", "null" ] }, "rollback_available_until": { "type": [ "string", "null" ] }, "deployed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "can_be_restarted": { "type": "boolean" }, "can_be_destroyed": { "type": "boolean" } }, "required": [ "id", "name", "app_type", "status", "status_details", "capabilities", "version", "resource_profile", "datacenter", "subdomain", "hostname", "url", "admin_user", "monthly_cost_cents", "monthly_cost_dollars", "automated_snapshots_enabled", "current_bundle_id", "rollback_available_until", "deployed_at", "created_at", "updated_at", "team_id", "user_id", "can_be_restarted", "can_be_destroyed" ], "title": "AppInstanceResource" }, "AppInstanceStatus": { "type": "string", "enum": [ "pending", "provisioning", "running", "stopped", "error", "destroying", "updating", "restoring", "restarting", "upgrading", "rolling_back" ], "title": "AppInstanceStatus" }, "CacheInstanceResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string", "enum": [ "Pending", "Provisioning", "Running", "Stopped", "Restoring", "Updating", "Error", "Destroying" ] }, "status_details": { "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "description": "Which diagnostics this resource supports \u2014 derived, so an agent\nknows which endpoints are worth calling before calling them.", "$ref": "#/components/schemas/CapabilitiesResource" }, "resource_profile": { "type": [ "string", "null" ] }, "cpu_cores": { "type": "integer" }, "memory_size_mb": { "type": "integer" }, "version": { "type": [ "string", "null" ] }, "provider_id": { "type": "integer" }, "provider": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "type" ] }, "endpoint": { "type": "string" }, "port": { "type": "integer", "description": "The engine port, always. Existing clients (Terraform, CLI) read\nthis; it deliberately does NOT become the public port when DNS is\nenabled. Use connection_host/connection_port to connect." }, "dns_hostname": { "type": [ "string", "null" ] }, "dns_port": { "type": [ "integer", "null" ] }, "internal_host": { "type": "string", "description": "Private plane: the in-cluster Service, unaffected by public DNS." }, "internal_port": { "type": "integer" }, "internal_endpoint": { "type": "string" }, "public_endpoint": { "type": [ "string", "null" ], "description": "Public plane: the shared load balancer. Null when public DNS is off." }, "connection_host": { "type": [ "string", "null" ], "description": "Whichever of the two a client should use right now." }, "connection_port": { "type": [ "integer", "null" ] }, "monthly_cost_cents": { "type": "integer" }, "monthly_cost_dollars": { "type": "number" }, "deployed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "can_be_started": { "type": "boolean" }, "can_be_stopped": { "type": "boolean" }, "can_be_destroyed": { "type": "boolean" } }, "required": [ "id", "name", "status", "status_label", "status_details", "capabilities", "resource_profile", "cpu_cores", "memory_size_mb", "version", "provider_id", "endpoint", "port", "dns_hostname", "dns_port", "internal_host", "internal_port", "internal_endpoint", "public_endpoint", "connection_host", "connection_port", "monthly_cost_cents", "monthly_cost_dollars", "deployed_at", "created_at", "updated_at", "team_id", "user_id", "can_be_started", "can_be_stopped", "can_be_destroyed" ], "title": "CacheInstanceResource" }, "CacheSnapshotResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "size_mb": { "type": "string" }, "cache_instance_id": { "type": "string" }, "cache_instance": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "status", "size_mb", "cache_instance_id", "created_at", "updated_at" ], "title": "CacheSnapshotResource" }, "CapabilitiesResource": { "type": "object", "properties": { "logs": { "type": "boolean", "description": "Whether `/logs` serves workload output. False where there is no log surface, or where guest privacy excludes it (VPS)." }, "events": { "type": "boolean", "description": "Whether `/events` serves cluster events for this resource's objects." }, "diagnose": { "type": "boolean", "description": "Whether `/diagnose` is served. False where the product's own history is the better surface (metric alerts)." }, "build_logs": { "type": "boolean", "description": "Static sites only: whether this site's build logs are readable. Absent for every other product." } }, "required": [ "logs", "events", "diagnose" ], "title": "CapabilitiesResource" }, "CloneApiCacheInstanceRequest": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "maxLength": 255 }, "source_type": { "type": "string", "enum": [ "volume_snapshot", "velero_backup" ] } }, "required": [ "name", "source_type" ], "title": "CloneApiCacheInstanceRequest" }, "CloneApiDatabaseInstanceRequest": { "type": "object", "description": "API request for cloning database instances from snapshots.", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "maxLength": 255 }, "database_name": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$", "maxLength": 64 }, "source_type": { "type": "string", "enum": [ "volume_snapshot", "velero_backup" ] } }, "required": [ "name", "source_type" ], "title": "CloneApiDatabaseInstanceRequest" }, "ComparisonOperator": { "type": "string", "enum": [ "gt", "gte", "lt", "lte" ], "title": "ComparisonOperator" }, "CreatePartnerSubTeamRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "owner_email": { "type": "string", "format": "email", "maxLength": 255 }, "owner_name": { "type": "string", "maxLength": 255 } }, "required": [ "name", "owner_email", "owner_name" ], "title": "CreatePartnerSubTeamRequest" }, "DatabaseInstanceResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string", "enum": [ "Pending", "Starting", "Stopping", "Provisioning", "Running", "Stopped", "Restoring", "Updating", "Error", "Destroying" ] }, "status_details": { "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "description": "Which diagnostics this resource supports \u2014 derived, so an agent\nknows which endpoints are worth calling before calling them.", "$ref": "#/components/schemas/CapabilitiesResource" }, "resource_profile": { "type": "string" }, "cpu_cores": { "type": "integer" }, "memory_size_mb": { "type": "integer" }, "storage_size_gb": { "type": "integer" }, "version": { "type": [ "string", "null" ] }, "database_name": { "type": [ "string", "null" ], "description": "Deliberately the requested value, not getCreatedDatabaseName().\nThe Terraform provider marks database_name Optional + RequiresReplace,\nso echoing the effective name (`pgdb`) back to a config that omitted\nthe field would read as drift on a replace-forcing attribute and plan\na destroy/recreate of a live database. Returning exactly what was\nrequested matches config for everyone who set it, and stays null for\neveryone who did not." }, "datacenter": { "type": [ "string", "null" ] }, "provider_id": { "type": "integer" }, "provider": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "type" ] }, "engine": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "endpoint": { "type": "string" }, "port": { "type": "integer", "description": "The engine port, always. Existing clients (Terraform, CLI) read\nthis; it deliberately does NOT become the public port when DNS is\nenabled. Use connection_host/connection_port to connect." }, "dns_hostname": { "type": [ "string", "null" ] }, "dns_port": { "type": [ "integer", "null" ] }, "internal_host": { "type": "string", "description": "Private plane: the in-cluster Service, unaffected by public DNS." }, "internal_port": { "type": "integer" }, "internal_endpoint": { "type": "string" }, "public_endpoint": { "type": [ "string", "null" ], "description": "Public plane: the shared load balancer. Null when public DNS is off." }, "connection_host": { "type": [ "string", "null" ], "description": "Whichever of the two a client should use right now." }, "connection_port": { "type": [ "integer", "null" ] }, "username": { "type": "string" }, "monthly_cost_cents": { "type": "integer" }, "monthly_cost_dollars": { "type": "number" }, "storage_autoscale_policy": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "threshold_percent": { "type": "integer" }, "increment_gib": { "type": "integer" }, "max_storage_gib": { "type": "integer" }, "last_scaled_at": { "type": [ "string", "null" ] }, "last_checked_at": { "type": [ "string", "null" ] } }, "required": [ "enabled", "threshold_percent", "increment_gib", "max_storage_gib", "last_scaled_at", "last_checked_at" ] }, "deployed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "can_be_started": { "type": "boolean" }, "can_be_stopped": { "type": "boolean" }, "can_be_destroyed": { "type": "boolean" } }, "required": [ "id", "name", "status", "status_label", "status_details", "capabilities", "resource_profile", "cpu_cores", "memory_size_mb", "storage_size_gb", "version", "database_name", "datacenter", "provider_id", "endpoint", "port", "dns_hostname", "dns_port", "internal_host", "internal_port", "internal_endpoint", "public_endpoint", "connection_host", "connection_port", "username", "monthly_cost_cents", "monthly_cost_dollars", "deployed_at", "created_at", "updated_at", "team_id", "user_id", "can_be_started", "can_be_stopped", "can_be_destroyed" ], "title": "DatabaseInstanceResource" }, "DatabaseNotification": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "notifiable_type": { "type": "string" }, "notifiable_id": { "type": "integer" }, "data": { "type": "array", "items": {} }, "category": { "type": [ "string", "null" ] }, "severity": { "type": "string" }, "team_id": { "type": [ "integer", "null" ] }, "resource_type": { "type": [ "string", "null" ] }, "resource_id": { "type": [ "integer", "null" ] }, "read_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "notifiable_type", "notifiable_id", "data", "category", "severity", "team_id", "resource_type", "resource_id", "read_at", "created_at", "updated_at" ], "title": "DatabaseNotification" }, "DatabaseSnapshotResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "size_gb": { "type": "string" }, "database_instance_id": { "type": "string" }, "database_instance": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "status", "size_gb", "database_instance_id", "created_at", "updated_at" ], "title": "DatabaseSnapshotResource" }, "DiagnosticEventResource": { "type": "object", "properties": { "type": { "type": "string" }, "reason": { "type": "string" }, "message": { "type": "string" }, "resource": { "type": "string" }, "count": { "type": "string" }, "first_seen": { "type": "string" }, "last_seen": { "type": "string" } }, "required": [ "type", "reason", "message", "resource", "count", "first_seen", "last_seen" ], "title": "DiagnosticEventResource" }, "DigestFrequency": { "type": "string", "enum": [ "instant", "daily", "weekly", "disabled" ], "title": "DigestFrequency" }, "FindingResource": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable automation key, namespaced by product, e.g. `serverless.no_pod_scheduled`. Branch on this, never on the prose." }, "severity": { "type": "string", "description": "One of: fatal, action_required, transient_recovered, informational. `transient_recovered` is NOT a current problem." }, "summary": { "type": "string", "description": "Human-readable statement of the finding. Reworded freely; do not parse." }, "remediation": { "type": [ "string", "null" ], "description": "What to actually do. Null when there is nothing to do." }, "retryable": { "type": "boolean", "description": "Whether retrying the same operation can possibly help." } }, "required": [ "code", "severity", "summary", "remediation", "retryable" ], "title": "FindingResource" }, "Firewall": { "type": "object", "title": "Firewall" }, "FirewallResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/FirewallStatus" }, "is_default": { "type": "string" }, "default_action": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ], "description": "The API exposes a rule's label as `name`; it is persisted\nin the `description` column. `firewall_rules` has no\n`name` column, so reading $rule->name always yielded null." }, "action": { "type": "string" }, "direction": { "type": "string" }, "protocol": { "type": "string" }, "port_range_start": { "type": [ "integer", "null" ] }, "port_range_end": { "type": [ "integer", "null" ] }, "source_ips": { "type": [ "array", "null" ], "items": {} }, "order": { "type": "integer", "description": "Was `priority`, which is not a column on firewall_rules\nand therefore always serialized as null." } }, "required": [ "id", "name", "action", "direction", "protocol", "port_range_start", "port_range_end", "source_ips", "order" ] } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "team_id": { "type": "integer" } }, "required": [ "id", "name", "description", "status", "is_default", "default_action", "created_at", "updated_at", "team_id" ], "title": "FirewallResource" }, "FirewallStatus": { "type": "string", "enum": [ "draft", "active", "applying", "error" ], "title": "FirewallStatus" }, "InstanceLogEntryResource": { "type": "object", "properties": { "timestamp": { "type": "string" }, "message": { "type": "string" }, "level": { "type": "string" }, "pod": { "type": "string" }, "container": { "type": "string" }, "stream": { "type": "string" } }, "required": [ "timestamp", "message", "level", "pod", "container", "stream" ], "title": "InstanceLogEntryResource" }, "KubernetesClusterResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "short_id": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string", "enum": [ "Pending", "Provisioning", "Running", "Error", "Destroying" ] }, "k8s_version": { "type": "string" }, "ip_family": { "type": "string" }, "service_cidr": { "type": "string", "description": "Platform-assigned; surfaced read-only (AWS model \u2014 no CIDR input)." }, "endpoint": { "type": "string" }, "node_count": { "type": "integer" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "short_id", "status", "status_label", "k8s_version", "ip_family", "service_cidr", "endpoint", "node_count", "created_at" ], "title": "KubernetesClusterResource" }, "MetricAlertResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/AlertStatus" } ] }, "status_details": { "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "$ref": "#/components/schemas/CapabilitiesResource" }, "enabled": { "type": "boolean" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string" }, "resource_name": { "type": "string" }, "metric_type": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/MetricType" } ] }, "metric_label": { "type": [ "string", "null" ], "enum": [ "CPU Usage", "Memory Usage", "Disk Usage", "Network Receive Rate", "Network Transmit Rate", "CPU Steal", "Load Ratio", "Cache Connections", "Cache Hit Ratio", "Cache Ops/sec", "DB Connections", "DB Connection Usage", "DB Replication Lag", "DB Queries/sec", "Request Rate", "Request Latency (p99)", "Error Rate", null ] }, "metric_unit": { "type": [ "string", "null" ], "enum": [ "%", "bytes/s", "ratio", "connections", "ops/s", "seconds", "req/s", "ms", null ] }, "comparison_operator": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ComparisonOperator" } ] }, "comparison_symbol": { "type": [ "string", "null" ], "enum": [ ">", ">=", "<", "<=", null ] }, "threshold_value": { "type": "number" }, "last_metric_value": { "type": [ "number", "null" ] }, "duration_minutes": { "type": "integer", "description": "The evaluator runs every minute, so this doubles as the number\nof minutes a breach must persist before the alert fires." }, "consecutive_breaches": { "type": "integer" }, "trigger_count": { "type": "integer" }, "notification_channels": { "type": [ "array", "null" ], "items": {} }, "last_evaluated_at": { "type": [ "string", "null" ] }, "triggered_at": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ] }, "team_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "status", "status_details", "capabilities", "enabled", "resource_type", "resource_id", "resource_name", "metric_type", "metric_label", "metric_unit", "comparison_operator", "comparison_symbol", "threshold_value", "last_metric_value", "duration_minutes", "consecutive_breaches", "trigger_count", "notification_channels", "last_evaluated_at", "triggered_at", "resolved_at", "team_id", "created_at", "updated_at" ], "title": "MetricAlertResource" }, "MetricType": { "type": "string", "enum": [ "cpu_usage", "memory_usage", "disk_usage", "network_receive_rate", "network_transmit_rate", "cpu_steal", "load_ratio", "cache_connections", "cache_hit_ratio", "cache_ops_per_second", "db_connections", "db_connection_usage", "db_replication_lag", "db_queries_per_second", "request_rate", "request_latency_p99", "error_rate" ], "title": "MetricType" }, "NotificationCategory": { "type": "string", "enum": [ "resource_provisioned", "resource_failed", "resource_destroyed", "resource_status_changed", "invoice_generated", "payment_successful", "payment_failed", "credits_low", "credits_expiring", "pricing_contract_expiring_soon", "pricing_contract_expired", "budget_threshold_50", "budget_threshold_80", "budget_exceeded", "api_key_created", "api_key_revoked", "firewall_changed", "suspicious_activity", "new_login", "audit_finding_critical", "audit_security_digest", "snapshot_completed", "snapshot_failed", "restore_completed", "restore_failed", "team_member_added", "team_member_removed", "team_invitation_sent", "team_invitation_accepted", "maintenance_scheduled", "maintenance_started", "maintenance_completed", "incident_reported", "incident_resolved", "cpu_threshold_exceeded", "memory_threshold_exceeded", "disk_threshold_exceeded", "connections_threshold_exceeded", "uptime_check_down", "uptime_check_recovered", "ssl_certificate_expiring", "pod_health_issue" ], "title": "NotificationCategory" }, "NotificationChannel": { "type": "string", "enum": [ "database", "mail", "webhook", "slack", "sms" ], "title": "NotificationChannel" }, "ParameterGroupResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "provider_type": { "type": "string" }, "family": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "parameters": { "type": "array", "items": {} }, "locked_parameters": { "type": "array", "items": {} }, "team_id": { "type": [ "integer", "null" ] }, "is_default": { "type": "boolean" }, "is_active": { "type": "boolean" }, "is_system": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "type", "provider_type", "family", "description", "parameters", "locked_parameters", "team_id", "is_default", "is_active", "is_system", "created_at", "updated_at" ], "title": "ParameterGroupResource" }, "QueueInstance": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "user_id": { "type": "integer" }, "team_id": { "type": "integer" }, "status": { "$ref": "#/components/schemas/QueueInstanceStatus" }, "automated_snapshots_enabled": { "type": "boolean" }, "version": { "type": "string" }, "memory_size_mb": { "type": "integer" }, "cpu_cores": { "type": "integer" }, "storage_size_gb": { "type": "integer" }, "port": { "type": "integer" }, "management_port": { "type": "integer" }, "host": { "type": [ "string", "null" ] }, "vhost": { "type": "string" }, "configuration": { "type": [ "array", "null" ], "items": {} }, "parameter_group_id": { "type": [ "integer", "null" ] }, "resource_profile": { "type": [ "string", "null" ] }, "datacenter": { "type": "string" }, "node": { "type": [ "string", "null" ] }, "hardware_profile": { "type": [ "string", "null" ] }, "public_ip": { "type": [ "string", "null" ] }, "private_ip": { "type": [ "string", "null" ] }, "dns_hostname": { "type": [ "string", "null" ] }, "dns_port": { "type": [ "integer", "null" ] }, "argocd_data": { "type": [ "array", "null" ], "items": {} }, "monthly_cost_cents": { "type": "integer" }, "deployed_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_backup_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "desired_replicas": { "type": "integer" }, "mqtt_port": { "type": [ "integer", "null" ] }, "amqps_port": { "type": [ "integer", "null" ] }, "mqtts_port": { "type": [ "integer", "null" ] }, "stomp_port": { "type": [ "integer", "null" ] }, "stomps_port": { "type": [ "integer", "null" ] }, "status_observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_details": { "type": [ "array", "null" ], "items": {} } }, "required": [ "id", "name", "user_id", "team_id", "status", "automated_snapshots_enabled", "version", "memory_size_mb", "cpu_cores", "storage_size_gb", "port", "management_port", "host", "vhost", "configuration", "parameter_group_id", "resource_profile", "datacenter", "node", "hardware_profile", "public_ip", "private_ip", "dns_hostname", "dns_port", "argocd_data", "monthly_cost_cents", "deployed_at", "last_backup_at", "created_at", "updated_at", "deleted_at", "desired_replicas", "mqtt_port", "amqps_port", "mqtts_port", "stomp_port", "stomps_port", "status_observed_at", "failure_details" ], "title": "QueueInstance" }, "QueueInstanceStatus": { "type": "string", "enum": [ "pending", "provisioning", "running", "stopped", "restoring", "updating", "error", "destroying" ], "title": "QueueInstanceStatus" }, "RegistryRepositoryResource": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string", "description": "The pull path, e.g. `team-42/api`. Prefix with the registry\nhost to get a usable image reference." }, "bytes_used": { "type": "integer" }, "tag_count": { "type": "integer" }, "last_push_at": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryRepositoryTagResource" } }, "team_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "path", "bytes_used", "tag_count", "last_push_at", "team_id", "created_at" ], "title": "RegistryRepositoryResource" }, "RegistryRepositoryTagResource": { "type": "object", "properties": { "tag": { "type": "string" }, "digest": { "type": "string" }, "media_type": { "type": "string" }, "bytes_size": { "type": "integer" }, "pushed_at": { "type": [ "string", "null" ] } }, "required": [ "tag", "digest", "media_type", "bytes_size", "pushed_at" ], "title": "RegistryRepositoryTagResource" }, "ServerlessContainerResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "deployment_type": { "type": "string", "description": "--- deployment source -------------------------------------" }, "source_type": { "type": [ "string", "null" ] }, "repository_url": { "type": [ "string", "null" ] }, "repository_branch": { "type": "string" }, "repository_commit_sha": { "type": [ "string", "null" ] }, "build_context_path": { "type": "string" }, "dockerfile_path": { "type": "string" }, "git_auth_type": { "type": "string", "description": "The auth *mode* is safe to expose; the credential itself is not." }, "buildpack_builder": { "type": [ "string", "null" ] }, "detected_runtime": { "type": [ "string", "null" ] }, "auto_build_on_push": { "type": "boolean" }, "auto_deploy": { "type": "boolean" }, "image": { "type": [ "string", "null" ], "description": "--- image -------------------------------------------------" }, "image_tag": { "type": "string" }, "built_image_ref": { "type": [ "string", "null" ] }, "registry_credential_id": { "type": [ "string", "null" ] }, "uses_danube_registry": { "type": "boolean" }, "port": { "type": "integer", "description": "--- runtime configuration ---------------------------------" }, "min_scale": { "type": "integer" }, "max_scale": { "type": "integer" }, "concurrency_target": { "type": "integer" }, "container_concurrency": { "type": "integer" }, "target_concurrency": { "type": "string" }, "scaling_metric": { "type": "string" }, "scaling_target": { "type": "integer" }, "timeout_seconds": { "type": "integer" }, "progress_deadline_seconds": { "type": [ "integer", "null" ] }, "resource_profile": { "type": "string" }, "cpu_request": { "type": "string" }, "cpu_limit": { "type": "string" }, "memory_request": { "type": "string" }, "memory_limit": { "type": "string" }, "health_check_path": { "type": [ "string", "null" ] }, "scale_to_zero_enabled": { "type": "boolean" }, "environment_variables": { "type": [ "array", "null" ], "description": "Environment VALUES are still returned because `danube rapids env\nset` does a read-modify-write against this field and would wipe\nthe other variables without it. Removing them is gated on the\nCLI moving to server-side merge semantics (Ticket 5).", "items": {} }, "status": { "type": "string", "description": "--- state -------------------------------------------------" }, "status_details": { "description": "The truthful state of this container. Read this rather than `status`.", "$ref": "#/components/schemas/ServerlessStatusDetailsResource" }, "last_error": { "type": [ "string", "null" ] }, "error_category": { "type": [ "string", "null" ] }, "knative_service_name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "current_revision": { "type": [ "string", "null" ] }, "deployment_count": { "type": "integer" }, "deployed_at": { "type": [ "string", "null" ] }, "last_deployed_at": { "type": [ "string", "null" ] }, "last_stopped_at": { "type": [ "string", "null" ] }, "last_build_at": { "type": [ "string", "null" ] }, "total_requests": { "type": "integer", "description": "--- observed metrics --------------------------------------" }, "requests_per_minute": { "type": [ "integer", "null" ] }, "current_replicas": { "type": "integer" }, "avg_response_time_ms": { "type": [ "number", "null" ] }, "error_rate": { "type": [ "number", "null" ] }, "metrics_updated_at": { "type": [ "string", "null" ] }, "current_month_requests": { "type": "integer", "description": "--- billing -----------------------------------------------" }, "current_month_compute_seconds": { "type": "number" }, "current_month_cost_cents": { "type": "number" }, "billing_period": { "type": [ "string", "null" ] }, "capabilities": { "type": "object", "description": "Which diagnostic sub-resources this container can serve, so an\nagent can branch without probing and eating a 404/403.", "properties": { "logs": { "type": "boolean" }, "events": { "type": "boolean" }, "revisions": { "type": "boolean" } }, "required": [ "logs", "events", "revisions" ] }, "team": { "type": "object", "description": "Minimal relation shells. The full models carry team API keys and\nwebhook secrets, so only identity is exposed.", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessDeploymentResource" } }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "description", "deployment_type", "source_type", "repository_url", "repository_branch", "repository_commit_sha", "build_context_path", "dockerfile_path", "git_auth_type", "buildpack_builder", "detected_runtime", "auto_build_on_push", "auto_deploy", "image", "image_tag", "built_image_ref", "registry_credential_id", "uses_danube_registry", "port", "min_scale", "max_scale", "concurrency_target", "container_concurrency", "target_concurrency", "scaling_metric", "scaling_target", "timeout_seconds", "progress_deadline_seconds", "resource_profile", "cpu_request", "cpu_limit", "memory_request", "memory_limit", "health_check_path", "scale_to_zero_enabled", "environment_variables", "status", "status_details", "last_error", "error_category", "knative_service_name", "url", "current_revision", "deployment_count", "deployed_at", "last_deployed_at", "last_stopped_at", "last_build_at", "total_requests", "requests_per_minute", "current_replicas", "avg_response_time_ms", "error_rate", "metrics_updated_at", "current_month_requests", "current_month_compute_seconds", "current_month_cost_cents", "billing_period", "capabilities", "created_at", "updated_at" ], "title": "ServerlessContainerResource" }, "ServerlessDeploymentResource": { "type": "object", "properties": { "id": { "type": "string" }, "serverless_container_id": { "type": "string" }, "revision_number": { "type": "integer" }, "revision_name": { "type": "string" }, "knative_revision_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image": { "type": "string" }, "image_tag": { "type": "string" }, "port": { "type": "integer" }, "min_scale": { "type": "integer" }, "max_scale": { "type": "integer" }, "target_concurrency": { "type": "integer" }, "resource_profile": { "type": "string" }, "status": { "type": "string" }, "status_details": { "description": "Same documentation wrapper the container resource already uses.\nUnwrapped, a plain array publishes as `\"type\": \"string\"`.", "$ref": "#/components/schemas/ServerlessStatusDetailsResource" }, "is_current": { "type": "boolean" }, "traffic_percent": { "type": "integer" }, "error_message": { "type": [ "string", "null" ], "description": "The failure snapshot stays on the deployment row even after the\ncontainer recovers, so post-incident history survives." }, "error_category": { "type": [ "string", "null" ] }, "total_requests": { "type": "integer" }, "first_request_at": { "type": [ "string", "null" ] }, "last_request_at": { "type": [ "string", "null" ] }, "deployed_at": { "type": [ "string", "null" ] }, "activated_at": { "type": [ "string", "null" ] }, "deactivated_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "serverless_container_id", "revision_number", "revision_name", "knative_revision_name", "description", "image", "image_tag", "port", "min_scale", "max_scale", "target_concurrency", "resource_profile", "status", "status_details", "is_current", "traffic_percent", "error_message", "error_category", "total_requests", "first_request_at", "last_request_at", "deployed_at", "activated_at", "deactivated_at", "created_at", "updated_at" ], "title": "ServerlessDeploymentResource" }, "ServerlessEventResource": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "Normal or Warning." }, "reason": { "type": [ "string", "null" ], "description": "Short machine reason, e.g. Pulling, Failed, Started." }, "message": { "type": "string", "description": "Human-readable detail." }, "resource": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ], "description": "Kind of the object the event concerns, e.g. Revision or Pod." }, "name": { "type": [ "string", "null" ], "description": "Name of that object." } }, "required": [ "kind", "name" ] }, "count": { "type": "integer", "description": "How many times this event has repeated." }, "first_seen": { "type": [ "string", "null" ], "description": "ISO-8601 first occurrence." }, "last_seen": { "type": [ "string", "null" ], "description": "ISO-8601 most recent occurrence." } }, "required": [ "type", "reason", "message", "resource", "count", "first_seen", "last_seen" ], "title": "ServerlessEventResource" }, "ServerlessLogEntryResource": { "type": "object", "properties": { "timestamp": { "type": "string", "description": "ISO-8601 timestamp of the line." }, "message": { "type": "string", "description": "The log line itself, verbatim." }, "level": { "type": "string", "description": "Detected level: DEBUG, INFO, WARN or ERROR." }, "pod": { "type": [ "string", "null" ], "description": "Pod that emitted it, when known." }, "container": { "type": [ "string", "null" ], "description": "Container within the pod (user-container, queue-proxy)." }, "stream": { "type": "string", "description": "Output stream." } }, "required": [ "timestamp", "message", "level", "pod", "container", "stream" ], "title": "ServerlessLogEntryResource" }, "ServerlessRevisionConditionResource": { "type": "object", "properties": { "type": { "type": "string", "description": "Condition type, e.g. Ready, ContainerHealthy, IngressReady." }, "status": { "type": "string", "description": "Tri-state: True, False or Unknown. Unknown means still in progress." }, "reason": { "type": [ "string", "null" ], "description": "Provider-native reason, e.g. ContainerMissing. Correlates with kubectl describe." }, "message": { "type": [ "string", "null" ], "description": "Human-readable detail." }, "last_transition_time": { "type": [ "string", "null" ], "description": "ISO-8601 time the condition last changed." } }, "required": [ "type", "status", "reason", "message", "last_transition_time" ], "title": "ServerlessRevisionConditionResource" }, "ServerlessRevisionResource": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Revision name, e.g. my-api-00007." }, "created_at": { "type": [ "string", "null" ], "description": "ISO-8601 creation time." }, "generation": { "type": [ "integer", "null" ], "description": "Configuration generation this revision came from." }, "is_latest_created": { "type": "boolean", "description": "True when this is the newest revision Knative created." }, "is_latest_ready": { "type": "boolean", "description": "True when this is the newest revision that became ready \u2014 i.e. what is serving." }, "desired_replicas": { "type": [ "integer", "null" ], "description": "Replicas Knative wants." }, "actual_replicas": { "type": [ "integer", "null" ], "description": "Replicas actually running. Zero with a failed Ready condition means no pod was ever scheduled." }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessRevisionConditionResource" } } }, "required": [ "name", "created_at", "generation", "is_latest_created", "is_latest_ready", "desired_replicas", "actual_replicas", "conditions" ], "title": "ServerlessRevisionResource" }, "ServerlessRouteStatusResource": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Knative Route name." }, "url": { "type": [ "string", "null" ], "description": "Public URL the route serves." }, "traffic": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessTrafficTargetResource" } }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessRevisionConditionResource" } } }, "required": [ "name", "url", "traffic", "conditions" ], "title": "ServerlessRouteStatusResource" }, "ServerlessServiceStatusResource": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Knative Service name." }, "url": { "type": [ "string", "null" ], "description": "Public URL Knative assigned." }, "latest_created_revision": { "type": [ "string", "null" ], "description": "Newest revision Knative created." }, "latest_ready_revision": { "type": [ "string", "null" ], "description": "Newest revision that became ready \u2014 what is actually serving." }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ServerlessRevisionConditionResource" } } }, "required": [ "name", "url", "latest_created_revision", "latest_ready_revision", "conditions" ], "title": "ServerlessServiceStatusResource" }, "ServerlessStatusDetailsResource": { "type": "object", "properties": { "summary": { "type": "string", "description": "Overall state: pending, in_progress, ready, degraded, failed, stopped, deleting, unknown." }, "health": { "type": "string", "description": "What is CURRENTLY SERVING: healthy, degraded, unhealthy, unknown. `unknown` during a rollout is not a failure." }, "observed_at": { "type": [ "string", "null" ], "description": "ISO-8601 time this status was last confirmed. Falls back to the row's last write when the platform has never recorded a check." }, "stale": { "type": "boolean", "description": "True only when an IN-FLIGHT operation has gone unconfirmed for 15 minutes. A settled state never goes stale, so `false` with an old `observed_at` is correct and expected \u2014 an error established an hour ago is still an error." }, "operation": { "$ref": "#/components/schemas/ServerlessStatusOperationResource" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ServerlessStatusErrorResource" }, { "type": "null" } ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ], "title": "ServerlessStatusDetailsResource" }, "ServerlessStatusErrorResource": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable automation key, e.g. `serverless.image_pull_auth`. Branch on this, not on `message`." }, "source": { "type": [ "string", "null" ], "description": "Which subsystem observed it, e.g. `reconciler`." }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ], "description": "Kubernetes kind, e.g. Revision or Pod." }, "name": { "type": [ "string", "null" ], "description": "Name of that object." } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ], "description": "Provider-native reason, e.g. `ContainerMissing`. Correlates with kubectl describe." }, "message": { "type": [ "string", "null" ], "description": "Human-readable detail. Not a stable interface." }, "retryable": { "type": "boolean", "description": "Whether retrying can possibly help. Retrying a false here only consumes quota." }, "observed_at": { "type": [ "string", "null" ], "description": "ISO-8601 time this failure was observed." } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ], "title": "ServerlessStatusErrorResource" }, "ServerlessStatusOperationResource": { "type": "object", "properties": { "state": { "type": "string", "description": "queued, running, succeeded, failed or cancelled." }, "terminal": { "type": "boolean", "description": "THE STOP CONDITION FOR POLLING. Do not infer this from `summary`." } }, "required": [ "state", "terminal" ], "title": "ServerlessStatusOperationResource" }, "ServerlessTrafficTargetResource": { "type": "object", "properties": { "revision_name": { "type": [ "string", "null" ], "description": "Revision receiving this share of traffic." }, "percent": { "type": "integer", "description": "Percentage of requests routed here." }, "latest_revision": { "type": "boolean", "description": "Whether this target tracks the latest ready revision." } }, "required": [ "revision_name", "percent", "latest_revision" ], "title": "ServerlessTrafficTargetResource" }, "ServerlessUsageRecord": { "type": "object", "properties": { "id": { "type": "string" }, "serverless_container_id": { "type": "string" }, "team_id": { "type": "integer" }, "billing_period": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" }, "request_count": { "type": "integer" }, "total_duration_seconds": { "type": "number" }, "avg_memory_mb": { "type": [ "integer", "null" ] }, "avg_cpu_millicores": { "type": [ "integer", "null" ] }, "request_cost_cents": { "type": "number" }, "compute_cost_cents": { "type": "number" }, "total_cost_cents": { "type": "number" }, "max_replicas_reached": { "type": [ "integer", "null" ] }, "error_count": { "type": "integer" }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "vcpu_seconds": { "type": "number" }, "memory_gib_seconds": { "type": "number" } }, "required": [ "id", "serverless_container_id", "team_id", "billing_period", "recorded_at", "request_count", "total_duration_seconds", "avg_memory_mb", "avg_cpu_millicores", "request_cost_cents", "compute_cost_cents", "total_cost_cents", "max_replicas_reached", "error_count", "notes", "created_at", "updated_at", "vcpu_seconds", "memory_gib_seconds" ], "title": "ServerlessUsageRecord" }, "SshKeyResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "fingerprint": { "type": "string" }, "public_key": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "team_id": { "type": "string" }, "user_id": { "type": "integer" } }, "required": [ "id", "name", "fingerprint", "public_key", "created_at", "updated_at", "team_id", "user_id" ], "title": "SshKeyResource" }, "StaticSiteBuildResource": { "type": "object", "properties": { "id": { "type": "string" }, "build_number": { "type": "integer" }, "status": { "type": "string" }, "source_type": { "type": "string" }, "trigger_type": { "type": "string" }, "file_count": { "type": [ "integer", "null" ] }, "source_size_bytes": { "type": [ "integer", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "build_logs": { "type": "string", "description": "Build output is the one thing that actually explains a failed\nbuild, and it has been stored all along without ever being\nserved. It sits behind `static-site:diagnostics` rather than\nplain read: build output echoes the customer's build\nenvironment and can carry secrets that a read-scoped token has\nno business seeing." }, "commit_sha": { "type": [ "string", "null" ] }, "commit_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "build_number", "status", "source_type", "trigger_type", "file_count", "source_size_bytes", "duration_seconds", "error_message", "commit_sha", "commit_message", "created_at", "updated_at" ], "title": "StaticSiteBuildResource" }, "StaticSiteDeploymentResource": { "type": "object", "properties": { "id": { "type": "string" }, "revision_number": { "type": "integer" }, "status": { "type": "string" }, "image_ref": { "type": "string" }, "trigger_type": { "type": "string" }, "is_current": { "type": "boolean" }, "file_count": { "type": [ "integer", "null" ] }, "file_size_bytes": { "type": [ "integer", "null" ] }, "build_duration_seconds": { "type": [ "integer", "null" ] }, "commit_sha": { "type": [ "string", "null" ] }, "commit_message": { "type": [ "string", "null" ] }, "deployed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "revision_number", "status", "image_ref", "trigger_type", "is_current", "file_count", "file_size_bytes", "build_duration_seconds", "commit_sha", "commit_message", "deployed_at", "created_at" ], "title": "StaticSiteDeploymentResource" }, "StaticSiteDomainResource": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "verification_status": { "type": "string" }, "tls_status": { "type": "string" }, "deployment_status": { "type": "string" }, "is_primary": { "type": "boolean" }, "dns_instructions": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "domain", "verification_status", "tls_status", "deployment_status", "is_primary", "dns_instructions", "created_at" ], "title": "StaticSiteDomainResource" }, "StaticSitePlan": { "type": "string", "enum": [ "free", "starter", "pro" ], "title": "StaticSitePlan" }, "StaticSiteResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_label": { "type": "string", "enum": [ "Pending", "Building", "Deploying", "Active", "Stopped", "Error", "Suspended", "Pending Review" ] }, "status_details": { "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "description": "Which diagnostics this resource supports \u2014 derived, so an agent\nknows which endpoints are worth calling before calling them.", "$ref": "#/components/schemas/CapabilitiesResource" }, "last_error": { "type": [ "string", "null" ] }, "plan": { "type": "string" }, "deploy_method": { "type": "string" }, "url": { "type": "string" }, "deployment_count": { "type": "integer" }, "storage_bytes_used": { "type": "integer" }, "monthly_cost_cents": { "type": "integer" }, "deployed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "slug", "description", "status", "status_label", "status_details", "capabilities", "last_error", "plan", "deploy_method", "url", "deployment_count", "storage_bytes_used", "monthly_cost_cents", "deployed_at", "created_at", "updated_at" ], "title": "StaticSiteResource" }, "StatusDetailsResource": { "type": "object", "properties": { "summary": { "type": "string", "description": "Overall state: pending, in_progress, ready, degraded, failed, stopped, deleting, unknown." }, "health": { "type": "string", "description": "What is CURRENTLY SERVING: healthy, degraded, unhealthy, unknown. `unknown` during an operation is not a failure." }, "observed_at": { "type": [ "string", "null" ], "description": "ISO-8601 time this status was last confirmed. Falls back to the row's last write when the platform has never recorded a check." }, "stale": { "type": "boolean", "description": "True only when an IN-FLIGHT operation has gone unconfirmed for 15 minutes. A settled state never goes stale, so `false` with an old `observed_at` is correct and expected \u2014 an error established an hour ago is still an error." }, "operation": { "$ref": "#/components/schemas/StatusOperationResource" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/StatusErrorResource" }, { "type": "null" } ] } }, "required": [ "summary", "health", "observed_at", "stale", "operation", "error" ], "title": "StatusDetailsResource" }, "StatusErrorResource": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable automation key, e.g. `cache.oom_killed`. Branch on this, not on `message`." }, "source": { "type": [ "string", "null" ], "description": "Which subsystem observed it, e.g. `reconciler`." }, "resource": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ], "description": "Kubernetes kind, e.g. Pod or PersistentVolumeClaim." }, "name": { "type": [ "string", "null" ], "description": "Name of that object." } }, "required": [ "kind", "name" ] }, "reason": { "type": [ "string", "null" ], "description": "Provider-native reason, e.g. `CrashLoopBackOff`. Correlates with kubectl describe." }, "message": { "type": [ "string", "null" ], "description": "Human-readable detail. Not a stable interface." }, "retryable": { "type": "boolean", "description": "Whether retrying can possibly help. Retrying a false here only consumes quota." }, "observed_at": { "type": [ "string", "null" ], "description": "ISO-8601 time this failure was observed." } }, "required": [ "code", "source", "resource", "reason", "message", "retryable", "observed_at" ], "title": "StatusErrorResource" }, "StatusOperationResource": { "type": "object", "properties": { "state": { "type": "string", "description": "queued, running, succeeded, failed or cancelled." }, "terminal": { "type": "boolean", "description": "THE STOP CONDITION FOR POLLING. Do not infer this from `summary`." } }, "required": [ "state", "terminal" ], "title": "StatusOperationResource" }, "StorageAccessKeyResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "access_key_id": { "type": "string" }, "access_key_id_masked": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string", "enum": [ "Active", "Revoked", "Error" ] }, "access_type": { "type": "string", "enum": [ "restricted", "full" ] }, "is_prefix_scoped": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "buckets", "team" ] }, "bucket_permissions": { "type": "array", "items": { "type": "object", "properties": { "bucket_id": { "type": "string" }, "bucket_name": {}, "level": { "type": "string" } }, "required": [ "bucket_id", "bucket_name", "level" ] } }, "expires_at": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "is_expired": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" } }, "required": [ "id", "name", "access_key_id", "access_key_id_masked", "status", "status_label", "access_type", "is_prefix_scoped", "scope", "bucket_permissions", "expires_at", "last_used_at", "revoked_at", "is_expired", "created_at", "updated_at", "team_id", "user_id" ], "title": "StorageAccessKeyResource" }, "StorageBucketResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "status": { "description": "Defensive against a raw string: the model's canBeModified()\nand canBeDestroyed() already guard for it, and a serializer\nthat fatals is a worse answer than an unlabelled status.", "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StorageBucketStatus" } ] }, "status_label": { "type": [ "string", "null" ], "enum": [ "Pending", "Creating", "Active", "Updating", "Error", "Destroying", null ] }, "status_details": { "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "description": "Derived: a bucket has no workload and no cluster object, so it\noffers neither logs nor events \u2014 say so rather than making an\nagent find out by 404.", "$ref": "#/components/schemas/CapabilitiesResource" }, "region": { "type": "string" }, "provider": { "type": "string" }, "provider_label": { "type": "string", "enum": [ "MinIO", "Ceph RGW" ] }, "endpoint_url": { "type": "string" }, "endpoint": { "type": "string" }, "public_url": { "type": [ "string", "null" ] }, "public_access": { "type": "boolean" }, "versioning_enabled": { "type": "boolean" }, "object_lock_enabled": { "type": "boolean" }, "object_lock_default_retention_mode": { "type": [ "string", "null" ] }, "object_lock_default_retention_days": { "type": [ "integer", "null" ] }, "object_lock_default_retention_human": { "type": [ "string", "null" ] }, "has_object_lock": { "type": "boolean" }, "has_default_retention": { "type": "boolean" }, "is_compliance_mode": { "type": "boolean" }, "encryption_enabled": { "type": "boolean" }, "encryption_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "size_human": { "type": "string" }, "size_limit_bytes": { "type": [ "integer", "null" ] }, "size_limit_human": { "type": [ "string", "null" ] }, "quota_usage_percent": { "type": [ "number", "null" ] }, "is_near_quota_limit": { "type": "boolean" }, "has_exceeded_quota": { "type": "boolean" }, "object_count": { "type": "integer" }, "lifecycle_rules": { "type": [ "array", "null" ], "items": {} }, "cors_configuration": { "type": [ "array", "null" ], "items": {} }, "custom_policy_statements": { "type": [ "array", "null" ], "items": {} }, "bucket_arn": { "type": "string" }, "tags": { "type": [ "array", "null" ], "items": {} }, "monthly_cost_cents": { "type": "integer" }, "monthly_cost_dollars": { "type": "number" }, "requests_24h_total": { "type": [ "integer", "null" ] }, "requests_24h_by_method": { "type": [ "array", "null" ], "items": {} }, "egress_bytes_24h": { "type": [ "integer", "null" ] }, "metrics_precomputed_at": { "type": [ "string", "null" ] }, "last_metrics_sync_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "minio_bucket_name": { "type": "string" }, "can_be_modified": { "type": "boolean" }, "can_be_destroyed": { "type": "boolean" } }, "required": [ "id", "name", "display_name", "status", "status_label", "status_details", "capabilities", "region", "provider", "provider_label", "endpoint_url", "endpoint", "public_url", "public_access", "versioning_enabled", "object_lock_enabled", "object_lock_default_retention_mode", "object_lock_default_retention_days", "object_lock_default_retention_human", "has_object_lock", "has_default_retention", "is_compliance_mode", "encryption_enabled", "encryption_type", "size_bytes", "size_human", "size_limit_bytes", "size_limit_human", "quota_usage_percent", "is_near_quota_limit", "has_exceeded_quota", "object_count", "lifecycle_rules", "cors_configuration", "custom_policy_statements", "bucket_arn", "tags", "monthly_cost_cents", "monthly_cost_dollars", "requests_24h_total", "requests_24h_by_method", "egress_bytes_24h", "metrics_precomputed_at", "last_metrics_sync_at", "created_at", "updated_at", "team_id", "user_id", "minio_bucket_name", "can_be_modified", "can_be_destroyed" ], "title": "StorageBucketResource" }, "StorageBucketStatus": { "type": "string", "enum": [ "pending", "creating", "active", "updating", "error", "destroying" ], "title": "StorageBucketStatus" }, "StoreApiCacheInstanceRequest": { "type": "object", "description": "API request for creating cache instances.\n\nResources and cost are derived from the resource_profile, looked up against\nthe DB-backed CachePlan via PricingReader.", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "minLength": 2, "maxLength": 63 }, "provider": { "type": "string", "enum": [ "redis", "valkey", "dragonfly" ] }, "cache_provider_id": { "type": "integer" }, "version": { "type": [ "string", "null" ], "maxLength": 50 }, "configuration": { "type": [ "array", "null" ], "items": { "type": "string" } }, "parameter_group_id": { "type": [ "integer", "null" ] }, "datacenter": { "type": "string", "enum": [ "ash", "fsn1", "nbg1", "hel1" ] }, "resource_profile": { "type": "string" } }, "required": [ "name", "datacenter", "resource_profile" ], "title": "StoreApiCacheInstanceRequest" }, "StoreApiDatabaseInstanceRequest": { "type": "object", "description": "API request for creating database instances.\n\nResources and cost are derived from the resource_profile, looked up against\nthe DB-backed DatabasePlan via PricingReader.", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "minLength": 2, "maxLength": 63 }, "provider": { "type": "string", "enum": [ "mysql", "postgresql", "mariadb" ] }, "database_provider_id": { "type": "integer" }, "database_name": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$", "maxLength": 64 }, "version": { "type": [ "string", "null" ], "maxLength": 50 }, "configuration": { "type": [ "array", "null" ], "items": { "type": "string" } }, "parameter_group_id": { "type": [ "integer", "null" ] }, "datacenter": { "type": "string", "enum": [ "fsn1", "nbg1", "hel1" ] }, "resource_profile": { "type": "string" }, "storage_autoscaling_enabled": { "type": [ "boolean", "null" ] }, "storage_autoscale_threshold_percent": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "storage_autoscale_increment_gib": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1500 } }, "required": [ "name", "datacenter", "resource_profile" ], "title": "StoreApiDatabaseInstanceRequest" }, "StoreApiQueueInstanceRequest": { "type": "object", "description": "API request for creating queue instances.\n\nResources and cost are derived from the resource_profile via PricingReader\nagainst the DB-backed QueuePlan.", "properties": { "name": { "type": "string", "maxLength": 255 }, "resource_profile": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "datacenter": { "type": [ "string", "null" ], "enum": [ "fsn1", null ] } }, "required": [ "name", "resource_profile" ], "title": "StoreApiQueueInstanceRequest" }, "StoreApiStaticSiteRequest": { "type": "object", "description": "API request for creating static sites (both team-scoped and currentTeam paths).\n\nPlan enum is validated against the DB-backed StaticSitePlan via PricingReader\nso retired plans are rejected even if they remain as enum cases.", "properties": { "name": { "type": "string", "maxLength": 255 }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/StaticSitePlan" }, { "type": "null" } ] } }, "required": [ "name" ], "title": "StoreApiStaticSiteRequest" }, "StoreAppInstanceApiRequest": { "type": "object", "description": "The dashboard's create rules, with the token ability checked FIRST.\n\nA FormRequest validates before the controller body runs, so checking\n`app:write` in the controller would let an under-scoped token receive a 422\ninstead of a 403 \u2014 and subdomain uniqueness is enforced globally, so those\nvalidation messages would let it probe whether an arbitrary subdomain is\ntaken anywhere on the platform. Overriding authorize() moves the check in\nfront of the rules; every rule is inherited unchanged, so the two surfaces\ncannot validate differently.", "properties": { "app_type": { "type": "string", "enum": [ "n8n", "wordpress", "ghost" ] }, "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "minLength": 2, "maxLength": 63 }, "subdomain": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "minLength": 3, "maxLength": 63 }, "resource_profile": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "datacenter": { "type": "string", "enum": [ "fsn1" ] }, "admin_user": { "type": [ "string", "null" ], "pattern": "^[a-zA-Z0-9_\\-]+$", "maxLength": 255 } }, "required": [ "app_type", "name", "subdomain", "resource_profile", "datacenter" ], "title": "StoreAppInstanceApiRequest" }, "StoreFirewallRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "attached_instances": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "database", "cache", "vps", "queue", "serverless" ] } } } }, "rules": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "protocol": { "type": "string", "enum": [ "tcp", "udp", "icmp", "any", "gre", "esp" ] }, "port": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535 }, "port_range_start": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535 }, "port_range_end": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535 }, "source_ips": { "type": [ "array", "null" ], "items": { "type": "string" } }, "source_instance_ids": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "database", "cache", "vps", "queue", "serverless" ] } } } }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "action": { "type": [ "string", "null" ], "enum": [ "allow", "deny", null ] }, "order": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "direction", "protocol" ] } } }, "required": [ "name" ], "title": "StoreFirewallRequest" }, "StoreKubernetesClusterRequest": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "minLength": 2, "maxLength": 30 }, "k8s_version": { "type": "string", "enum": [ "1.35" ] }, "ip_family": { "type": "string", "description": "AWS model (#216): the IP family is chosen at creation and\nimmutable. `ipv6` is offered only behind the feature flag; the\nservice range is platform-assigned either way \u2014 there is\ndeliberately no CIDR input." }, "plan": { "type": "string", "description": "Legacy single-pool shape, kept for the API and older clients:\nequivalent to pools = [{name: default, plan, count: nodes}]." }, "nodes": { "type": "integer", "minimum": 1, "maximum": 0 }, "pools": { "type": "array", "description": "First-class node pools (#215). The first pool bootstraps the\ncluster; the rest are brought up once the cluster is Running.", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "minLength": 2, "maxLength": 20 }, "plan": { "type": "string" }, "count": { "type": "integer", "minimum": 1, "maximum": 0 } } }, "minItems": 1, "maxItems": 5 } }, "required": [ "name", "k8s_version" ], "title": "StoreKubernetesClusterRequest" }, "StoreMetricAlertApiRequest": { "type": "object", "description": "Creating an alert through the API, where the caller names the target.\n\nThe dashboard never does: its only create route is nested under a VPS and\nderives both `resource_type` and `resource_id` from the route binding. An\nAPI caller supplies them in the body, which introduces two problems the web\npath never had \u2014 an unowned `resource_id`, and a `resource_type` that no\nevaluator can actually handle. Both are rejected here.", "properties": { "resource_type": { "type": "string", "description": "Only types with a registered query resolver. The metric\ncatalogue lists more, but an alert on one of those would be\nstored and then never evaluated.", "enum": [ "vps" ] }, "resource_id": { "type": "string", "maxLength": 36 }, "metric_type": { "type": "string", "enum": [ "" ] }, "comparison_operator": { "type": "string", "enum": [ "gt", "gte", "lt", "lte" ] }, "threshold_value": { "type": "number", "minimum": 0 }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 60 }, "name": { "type": [ "string", "null" ], "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "notification_channels": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "database", "mail", "webhook" ] } } }, "required": [ "resource_type", "resource_id", "metric_type", "comparison_operator", "threshold_value" ], "title": "StoreMetricAlertApiRequest" }, "StoreServerlessContainerRequest": { "type": "object", "title": "StoreServerlessContainerRequest" }, "StoreSshKeyRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "public_key": { "type": "string", "maxLength": 8192 }, "is_default": { "type": "boolean" } }, "required": [ "name", "public_key" ], "title": "StoreSshKeyRequest" }, "StoreStorageBucketRequest": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$", "minLength": 3, "maxLength": 63 }, "display_name": { "type": [ "string", "null" ], "maxLength": 255 }, "region": { "type": "string", "enum": [ "fsn1" ] }, "versioning_enabled": { "type": "boolean" }, "public_access": { "type": "boolean" }, "encryption_enabled": { "type": "boolean" }, "encryption_type": { "type": [ "string", "null" ], "enum": [ "none", "sse-s3", "sse-kms", null ] }, "encryption_kms_key_id": { "type": [ "string", "null" ], "maxLength": 2048 }, "object_lock_enabled": { "type": "boolean", "description": "Object Lock (WORM) configuration" }, "object_lock_default_retention_mode": { "type": [ "string", "null" ], "enum": [ "GOVERNANCE", "COMPLIANCE", null ] }, "object_lock_default_retention_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36500 }, "size_limit_bytes": { "type": [ "integer", "null" ], "description": "Size limit validation (quota)", "minimum": 1073741824 }, "cors_configuration": { "type": "object", "description": "Min 1 GB\nCORS Configuration validation", "properties": { "CORSRules": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "AllowedOrigins": { "type": "array", "items": { "type": "string", "maxLength": 2048 }, "minItems": 1 }, "AllowedMethods": { "type": "array", "items": { "type": "string", "enum": [ "GET", "PUT", "POST", "DELETE", "HEAD" ] }, "minItems": 1 }, "AllowedHeaders": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 256 } }, "ExposeHeaders": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 256 } }, "MaxAgeSeconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 86400 } } }, "maxItems": 10 } } }, "lifecycle_rules": { "type": [ "array", "null" ], "description": "Lifecycle Rules validation", "items": { "type": "object", "properties": { "ID": { "type": "string", "maxLength": 255 }, "Status": { "type": "string", "enum": [ "Enabled", "Disabled" ] }, "Filter": { "type": [ "object", "null" ], "properties": { "Prefix": { "type": [ "string", "null" ], "maxLength": 1024 } } }, "Expiration": { "type": [ "object", "null" ], "properties": { "Days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36500 }, "Date": { "type": [ "string", "null" ], "format": "date-time" }, "ExpiredObjectDeleteMarker": { "type": [ "boolean", "null" ] } } }, "NoncurrentVersionExpiration": { "type": [ "object", "null" ], "properties": { "NoncurrentDays": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36500 } } }, "AbortIncompleteMultipartUpload": { "type": [ "object", "null" ], "properties": { "DaysAfterInitiation": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36500 } } } } }, "maxItems": 100 }, "tags": { "type": [ "array", "null" ], "description": "Tags validation", "items": { "type": "string", "maxLength": 256 }, "maxItems": 50 } }, "required": [ "name", "region" ], "title": "StoreStorageBucketRequest" }, "StoreUptimeCheckApiRequest": { "type": "object", "description": "The dashboard's create rules, with the token ability checked FIRST and the\nper-team cap enforced as validation rather than in the controller.\n\nChecking the ability first matters more here than anywhere else in the\nprogram: StoreUptimeCheckRequest::after() runs the SSRF validator, which\nperforms a LIVE DNS RESOLVE of the submitted URL. Leaving that behind a\ncontroller-body permission check would let a token without `uptime:write`\nmake the platform resolve arbitrary hostnames on its behalf.", "properties": { "name": { "type": "string", "maxLength": 100 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "method": { "type": "string", "enum": [ "GET", "HEAD" ] }, "interval_seconds": { "type": "integer", "enum": [ "60", "300" ] }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 30 }, "expected_status": { "type": "string", "pattern": "^(2xx|2xx-3xx|exact:[1-5][0-9]{2})$" }, "body_keyword": { "type": [ "string", "null" ], "maxLength": 255 }, "follow_redirects": { "type": "boolean" }, "verify_tls": { "type": "boolean" }, "check_ssl_expiry": { "type": "boolean" }, "ssl_expiry_threshold_days": { "type": "integer", "minimum": 1, "maximum": 60 }, "failure_threshold": { "type": "integer", "minimum": 1, "maximum": 10 }, "notify_on_recovery": { "type": "boolean" }, "notification_channels": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "database", "mail", "webhook" ] } } }, "required": [ "name", "url" ], "title": "StoreUptimeCheckApiRequest" }, "StoreVpsInstanceRequest": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "minLength": 2, "maxLength": 39 }, "resource_profile": { "type": "string", "enum": [ "" ] }, "cpu_allocation_type": { "type": [ "string", "null" ], "enum": [ "shared", "dedicated", null ] }, "image": { "type": "string", "enum": [ "" ], "maxLength": 500 }, "network_stack": { "type": [ "string", "null" ], "enum": [ "ipv4_only", "ipv6_only", "dual_stack", null ] }, "datacenter": { "type": "string", "enum": [ "fsn1" ] }, "auth_method": { "type": "string", "enum": [ "ssh_key", "password" ] }, "ssh_key_id": { "type": [ "integer", "null" ] }, "password": { "type": [ "string", "null" ], "minLength": 12 }, "configuration": { "type": "object", "properties": { "auto_start": { "type": "boolean" }, "backup_enabled": { "type": "boolean" }, "monitoring_enabled": { "type": "boolean" } } }, "custom_cloud_init": { "type": [ "string", "null" ], "maxLength": 10000 }, "marketplace_app_id": { "type": [ "integer", "null" ] }, "windows_license_key": { "type": [ "string", "null" ], "pattern": "^[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{5}$" }, "password_confirmation": { "type": [ "string", "null" ], "minLength": 12 } }, "required": [ "name", "resource_profile", "image", "datacenter", "auth_method" ], "title": "StoreVpsInstanceRequest" }, "UpdateApiCacheInstanceRequest": { "type": "object", "description": "API request for updating cache instances.\n\nResources and cost are derived from the resource_profile, looked up against\nthe DB-backed CachePlan via PricingReader. Provider is fixed by the existing\ninstance, not user-chosen.", "properties": { "name": { "type": "string", "maxLength": 255 }, "configuration": { "type": "array", "items": { "type": "string" } }, "resource_profile": { "type": "string" }, "parameter_group_id": { "type": [ "integer", "null" ] }, "automated_snapshots_enabled": { "type": "boolean" } }, "title": "UpdateApiCacheInstanceRequest" }, "UpdateApiDatabaseInstanceRequest": { "type": "object", "description": "API request for updating database instances.\n\nResources and cost are derived from the resource_profile, looked up against\nthe DB-backed DatabasePlan via PricingReader.", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "maxLength": 255 }, "configuration": { "type": "array", "items": { "type": "string" } }, "storage_size_gb": { "type": "integer", "minimum": 10, "maximum": 1500 }, "resource_profile": { "type": "string" }, "parameter_group_id": { "type": [ "integer", "null" ] }, "automated_snapshots_enabled": { "type": "boolean" }, "storage_autoscaling_enabled": { "type": "boolean" }, "storage_autoscale_threshold_percent": { "type": "integer", "minimum": 1, "maximum": 100 }, "storage_autoscale_increment_gib": { "type": "integer", "minimum": 1, "maximum": 1500 } }, "title": "UpdateApiDatabaseInstanceRequest" }, "UpdateApiQueueInstanceRequest": { "type": "object", "description": "API request for updating queue instances.\n\nResources and cost are derived from the resource_profile via PricingReader\nagainst the DB-backed QueuePlan.", "properties": { "resource_profile": { "type": "string" }, "configuration": { "type": "array", "items": { "type": "string" } }, "automated_snapshots_enabled": { "type": "boolean" } }, "title": "UpdateApiQueueInstanceRequest" }, "UpdateAppInstanceRequest": { "type": "object", "properties": { "resource_profile": { "type": "string", "enum": [ "" ] } }, "required": [ "resource_profile" ], "title": "UpdateAppInstanceRequest" }, "UpdateFirewallRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "status": { "type": "string", "enum": [ "draft", "active", "applying", "error" ] }, "attached_instances": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "database", "cache", "vps", "queue", "serverless" ] } } } }, "rules": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "protocol": { "type": "string", "enum": [ "tcp", "udp", "icmp", "any", "gre", "esp" ] }, "port": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535 }, "port_range_start": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535 }, "port_range_end": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535 }, "source_ips": { "type": [ "array", "null" ], "items": { "type": "string" } }, "source_instance_ids": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "database", "cache", "vps", "queue", "serverless" ] } } } }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "action": { "type": [ "string", "null" ], "enum": [ "allow", "deny", null ] }, "order": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "direction", "protocol" ] } } }, "title": "UpdateFirewallRequest" }, "UpdateServerlessContainerRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "maxLength": 63 }, "deployment_type": { "type": "string", "enum": [ "docker_image", "git_repository", "zip_upload" ] }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "image": { "type": "string", "maxLength": 500 }, "image_tag": { "type": "string", "maxLength": 128 }, "port": { "type": "integer", "description": "Container port is editable post-creation: changing it is just a\nKnative revision bump (containerPort + queue-proxy target), not a\nrebuild. Mirrors the StoreServerlessContainerRequest rule but with\n`sometimes`, and rejects ports bound by the queue-proxy sidecar.", "minimum": 1, "maximum": 65535 }, "resource_profile": { "type": "string", "enum": [ "free", "small", "medium", "large" ] }, "min_scale": { "type": "integer", "minimum": 0, "maximum": 100 }, "max_scale": { "type": "integer", "minimum": 1, "maximum": 100 }, "cpu_request": { "type": [ "string", "null" ], "maxLength": 20 }, "cpu_limit": { "type": [ "string", "null" ], "maxLength": 20 }, "memory_request": { "type": [ "string", "null" ], "maxLength": 20 }, "memory_limit": { "type": [ "string", "null" ], "maxLength": 20 }, "environment_variables": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 10000 } }, "concurrency_target": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 }, "scaling_metric": { "type": "string", "enum": [ "rps", "concurrency" ] }, "scaling_target": { "type": "integer", "minimum": 1, "maximum": 1000 }, "timeout_seconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3600 }, "health_check_path": { "type": [ "string", "null" ], "description": "Null keeps the default tcpSocket readiness probe; a path opts the\ncontainer into an httpGet probe on that path.", "pattern": "^\\/\\S*$", "maxLength": 255 }, "progress_deadline_seconds": { "type": [ "integer", "null" ], "minimum": 30, "maximum": 1800 }, "registry_credential_id": { "type": [ "string", "null" ], "format": "uuid" }, "repository_url": { "type": "string", "description": "Git deployment source \u2014 editable post-deploy so customers can fix a\ntypo in the repo URL or rotate credentials without recreating the\ncontainer. Validation only fires for git_repository deployments;\nvalidateChangesSupportedByUpdate() rejects these for other types.", "pattern": "#^(?:https?://|ssh://|git@)(?:[\\w\\-]+@)?[\\w\\-]+(?:\\.[\\w\\-]+)+(?::\\d+)?[/:][\\w\\-./]+/[\\w\\-.]+(?:\\.git)?/?$#", "maxLength": 500 }, "repository_branch": { "type": [ "string", "null" ], "pattern": "^[\\w\\-\\.\\/]+$", "maxLength": 255 }, "git_auth_type": { "type": "string", "enum": [ "none", "ssh_key", "access_token" ] }, "git_credentials": { "type": [ "string", "null" ], "maxLength": 10000 }, "auto_build_on_push": { "type": "boolean" }, "auto_deploy": { "type": "boolean", "description": "Redeploy automatically when this image:tag is re-pushed to the\nDanubeData registry \u2014 docker_image analog of auto_build_on_push." }, "source_type": { "type": "string", "description": "Build configuration (only valid for source deployments \u2014 git_repository / zip_upload)", "enum": [ "dockerfile", "buildpack" ] }, "dockerfile_path": { "type": [ "string", "null" ], "maxLength": 255 }, "build_context_path": { "type": [ "string", "null" ], "maxLength": 255 }, "buildpack_builder": { "type": [ "string", "null" ], "enum": [ "paketobuildpacks/builder-jammy-base", "paketobuildpacks/builder-jammy-full", "paketobuildpacks/builder-jammy-tiny", "gcr.io/buildpacks/builder:v1", "heroku/builder:22", null ], "maxLength": 255 } }, "title": "UpdateServerlessContainerRequest" }, "UpdateStorageBucketRequest": { "type": "object", "properties": { "display_name": { "type": [ "string", "null" ], "maxLength": 255 }, "versioning_enabled": { "type": "boolean" }, "public_access": { "type": "boolean" }, "encryption_enabled": { "type": "boolean" }, "encryption_type": { "type": "string", "enum": [ "none", "sse-s3", "sse-kms" ] }, "encryption_kms_key_id": { "type": [ "string", "null" ], "maxLength": 2048 }, "object_lock_default_retention_mode": { "type": [ "string", "null" ], "description": "Object Lock default retention update (only if Object Lock is already enabled)", "enum": [ "GOVERNANCE", "COMPLIANCE", null ] }, "object_lock_default_retention_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36500 }, "size_limit_bytes": { "type": [ "integer", "null" ], "description": "Size limit validation (quota)", "minimum": 1073741824 }, "cors_configuration": { "type": "object", "description": "Min 1 GB\nCORS Configuration validation", "properties": { "CORSRules": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "AllowedOrigins": { "type": "array", "items": { "type": "string", "maxLength": 2048 }, "minItems": 1 }, "AllowedMethods": { "type": "array", "items": { "type": "string", "enum": [ "GET", "PUT", "POST", "DELETE", "HEAD" ] }, "minItems": 1 }, "AllowedHeaders": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 256 } }, "ExposeHeaders": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 256 } }, "MaxAgeSeconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 86400 } } }, "maxItems": 10 } } }, "lifecycle_rules": { "type": [ "array", "null" ], "description": "Lifecycle Rules validation", "items": { "type": "object", "properties": { "ID": { "type": "string", "maxLength": 255 }, "Status": { "type": "string", "enum": [ "Enabled", "Disabled" ] }, "Filter": { "type": [ "object", "null" ], "properties": { "Prefix": { "type": [ "string", "null" ], "maxLength": 1024 } } }, "Expiration": { "type": [ "object", "null" ], "properties": { "Days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36500 }, "Date": { "type": [ "string", "null" ], "format": "date-time" }, "ExpiredObjectDeleteMarker": { "type": [ "boolean", "null" ] } } }, "NoncurrentVersionExpiration": { "type": [ "object", "null" ], "properties": { "NoncurrentDays": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36500 } } }, "AbortIncompleteMultipartUpload": { "type": [ "object", "null" ], "properties": { "DaysAfterInitiation": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36500 } } } } }, "maxItems": 100 }, "tags": { "type": [ "array", "null" ], "description": "Tags validation", "items": { "type": "string", "maxLength": 256 }, "maxItems": 50 } }, "title": "UpdateStorageBucketRequest" }, "UpdateUptimeCheckRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "method": { "type": "string", "enum": [ "GET", "HEAD" ] }, "interval_seconds": { "type": "integer", "enum": [ "60", "300" ] }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 30 }, "expected_status": { "type": "string", "pattern": "^(2xx|2xx-3xx|exact:[1-5][0-9]{2})$" }, "body_keyword": { "type": [ "string", "null" ], "maxLength": 255 }, "follow_redirects": { "type": "boolean" }, "verify_tls": { "type": "boolean" }, "check_ssl_expiry": { "type": "boolean" }, "ssl_expiry_threshold_days": { "type": "integer", "minimum": 1, "maximum": 60 }, "failure_threshold": { "type": "integer", "minimum": 1, "maximum": 10 }, "notify_on_recovery": { "type": "boolean" }, "notification_channels": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "database", "mail", "webhook" ] } } }, "required": [ "name", "url" ], "title": "UpdateUptimeCheckRequest" }, "UpdateVpsInstanceRequest": { "type": "object", "properties": { "cpu_allocation_type": { "type": "string", "enum": [ "shared", "dedicated" ] }, "resource_profile": { "type": [ "string", "null" ], "enum": [ "large", "large_shared", "medium", "medium_shared", "micro", "micro_shared", "nano", "nano_shared", "pico_shared", "small", "small_shared", "xlarge", null ] }, "configuration": { "type": "object", "properties": { "auto_start": { "type": "boolean" }, "backup_enabled": { "type": "boolean" }, "monitoring_enabled": { "type": "boolean" } } }, "automated_snapshots_enabled": { "type": "boolean" } }, "title": "UpdateVpsInstanceRequest" }, "UptimeCheckResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "method": { "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/UptimeCheckStatus" } ] }, "status_details": { "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "$ref": "#/components/schemas/CapabilitiesResource" }, "enabled": { "type": "boolean" }, "interval_seconds": { "type": "integer" }, "timeout_seconds": { "type": "integer" }, "expected_status": { "type": "string" }, "body_keyword": { "type": [ "string", "null" ] }, "follow_redirects": { "type": "boolean" }, "verify_tls": { "type": "boolean" }, "check_ssl_expiry": { "type": "boolean" }, "ssl_expiry_threshold_days": { "type": "integer" }, "ssl_expires_at": { "type": [ "string", "null" ] }, "failure_threshold": { "type": "integer" }, "notify_on_recovery": { "type": "boolean" }, "notification_channels": { "type": [ "array", "null" ], "items": {} }, "consecutive_failures": { "type": "integer" }, "last_checked_at": { "type": [ "string", "null" ] }, "last_status_code": { "type": [ "integer", "null" ] }, "last_response_time_ms": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ], "description": "A stable probe error CODE (dns, timeout, tls, \u2026), not prose." }, "team_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "method", "status", "status_details", "capabilities", "enabled", "interval_seconds", "timeout_seconds", "expected_status", "body_keyword", "follow_redirects", "verify_tls", "check_ssl_expiry", "ssl_expiry_threshold_days", "ssl_expires_at", "failure_threshold", "notify_on_recovery", "notification_channels", "consecutive_failures", "last_checked_at", "last_status_code", "last_response_time_ms", "last_error", "team_id", "created_at", "updated_at" ], "title": "UptimeCheckResource" }, "UptimeCheckStatus": { "type": "string", "enum": [ "up", "down", "unknown", "paused" ], "title": "UptimeCheckStatus" }, "VpsInstanceResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string", "enum": [ "Pending", "Provisioning", "Starting", "Running", "Stopping", "Stopped", "Rebooting", "Restoring", "Reinstalling", "Error", "Destroying", "Recreating" ] }, "status_details": { "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "description": "Which diagnostics this resource supports \u2014 derived, so an agent\nknows which endpoints are worth calling. `logs` is false by\ndesign here: guest output is the customer's own data.", "$ref": "#/components/schemas/CapabilitiesResource" }, "resource_profile": { "type": "string" }, "cpu_allocation_type": { "type": "string" }, "cpu_cores": { "type": "integer" }, "memory_size_gb": { "type": "integer" }, "storage_size_gb": { "type": "integer" }, "image": { "type": "string" }, "datacenter": { "type": "string" }, "public_ip": { "type": [ "string", "null" ] }, "ipv6_address": { "type": [ "string", "null" ] }, "vnc_access_url": { "type": [ "string", "null" ] }, "monthly_cost_cents": { "type": "integer" }, "monthly_cost_dollars": { "type": "number" }, "deployed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "ssh_key_id": { "type": [ "integer", "null" ] }, "can_be_started": { "type": "boolean" }, "can_be_stopped": { "type": "boolean" }, "can_be_rebooted": { "type": "boolean" }, "can_be_destroyed": { "type": "boolean" } }, "required": [ "id", "name", "status", "status_label", "status_details", "capabilities", "resource_profile", "cpu_allocation_type", "cpu_cores", "memory_size_gb", "storage_size_gb", "image", "datacenter", "public_ip", "ipv6_address", "vnc_access_url", "monthly_cost_cents", "monthly_cost_dollars", "deployed_at", "created_at", "updated_at", "team_id", "user_id", "ssh_key_id", "can_be_started", "can_be_stopped", "can_be_rebooted", "can_be_destroyed" ], "title": "VpsInstanceResource" }, "VpsInstanceStatus": { "type": "string", "enum": [ "pending", "provisioning", "starting", "running", "stopping", "stopped", "rebooting", "restoring", "reinstalling", "error", "destroying", "recreating" ], "title": "VpsInstanceStatus" }, "VpsSnapshotResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "size_gb": { "type": "string" }, "vps_instance_id": { "type": "string" }, "vps_instance": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "status", "size_gb", "vps_instance_id", "created_at", "updated_at" ], "title": "VpsSnapshotResource" }, "VpsVolumeResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "status_details": { "$ref": "#/components/schemas/StatusDetailsResource" }, "capabilities": { "description": "Derived, not hardcoded: a block device has no logs, and saying\nso here saves an agent a 404 to find out.", "$ref": "#/components/schemas/CapabilitiesResource" }, "size_gb": { "type": "integer" }, "pvc_name": { "type": "string", "description": "The cluster-side names, so an operator reading a support ticket\ncan correlate the API object with what they see in Kubernetes." }, "disk_name": { "type": "string" }, "monthly_cost_cents": { "type": "integer" }, "failure_reason": { "type": [ "string", "null" ], "description": "Legacy free-text reason. The machine-readable classification is\nstatus_details.error \u2014 branch on that, not on this prose." }, "vps_instance": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/VpsInstanceStatus" } ] } }, "required": [ "id", "name", "status" ] }, "vps_instance_id": { "type": "string" }, "team_id": { "type": "integer" }, "can_be_resized": { "type": "boolean" }, "can_be_detached": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "status", "status_details", "capabilities", "size_gb", "pvc_name", "disk_name", "monthly_cost_cents", "failure_reason", "vps_instance_id", "team_id", "can_be_resized", "can_be_detached", "created_at", "updated_at" ], "title": "VpsVolumeResource" }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "integer" }, "team_id": { "type": "integer" }, "event": { "type": "string" }, "url": { "type": "string" }, "payload": { "type": "array", "items": {} }, "signature": { "type": "string" }, "response_status": { "type": [ "integer", "null" ] }, "response_body": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "team_id", "event", "url", "payload", "signature", "response_status", "response_body", "attempts", "delivered_at", "failed_at", "error_message", "created_at", "updated_at" ], "title": "WebhookDelivery" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }