{ "openapi": "3.1.0", "info": { "title": "Spawnbase Media API", "version": "1.0.0", "description": "Game media CDN API. Fivemanage-shaped payloads under /api/v1. Auth: team API token in the Authorization header." }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Team API token, sent raw: `Authorization: `." }, "Dashboard": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token", "description": "Customer session with strict companion cookie; approval requires a fresh MFA proof." }, "Staff": { "type": "apiKey", "in": "header", "name": "Cf-Access-Jwt-Assertion", "description": "Verified live staff identity through the configured independent service; never a customer/API token." } }, "schemas": { "File": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "public" ] }, "legacyPublic": { "type": "boolean" }, "contentUrl": { "type": "string" }, "id": { "type": "string" }, "filename": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "other" ] }, "size": { "type": "number" }, "hash": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "url": { "type": "string" }, "originalUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "visibility", "legacyPublic", "contentUrl", "id", "filename", "type", "size", "hash", "metadata", "url", "originalUrl", "createdAt" ] }, "Error": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "status", "error" ] }, "TokenInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "*", "files:read", "files:write", "files:delete", "files:publish", "logs:read", "logs:write", "logs:import", "logs:admin", "logs:delete", "boards:read", "boards:write" ] }, "maxItems": 20, "default": [ "files:write" ] }, "expiresAt": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "name" ] }, "TokenScope": { "type": "string", "enum": [ "*", "files:read", "files:write", "files:delete", "files:publish", "logs:read", "logs:write", "logs:import", "logs:admin", "logs:delete", "boards:read", "boards:write" ] } }, "parameters": {} }, "paths": { "/api/v1/file": { "post": { "summary": "Upload a file (multipart)", "description": "Multipart requests are limited to 8 MiB including the envelope. Use a raw signed PUT for larger files.", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "public" ] }, "file": { "type": "string", "format": "binary" }, "filename": { "type": "string" }, "path": { "type": "string" }, "metadata": { "type": "string", "description": "JSON-encoded metadata object" }, "retentionExempt": { "type": "string" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Stored file", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "public" ] }, "legacyPublic": { "type": "boolean" }, "contentUrl": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "originalUrl": { "type": "string" } }, "required": [ "visibility", "legacyPublic", "contentUrl", "id", "url", "originalUrl" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List files", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "image", "video", "audio", "other" ] }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "path", "in": "query" } ], "responses": { "200": { "description": "Page of files", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "pagination": { "type": "object", "properties": { "page": { "type": "number" }, "limit": { "type": "number" }, "total": { "type": "number" } }, "required": [ "page", "limit", "total" ] } }, "required": [ "status", "data", "pagination" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/file/base64": { "post": { "summary": "Upload a file (base64 JSON)", "description": "JSON requests are limited to 8 MiB including the encoded file and envelope.", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "public" ] }, "base64": { "type": "string", "minLength": 1 }, "filename": { "type": "string" }, "path": { "type": "string" }, "metadata": { "type": "string" }, "retentionExempt": { "type": "boolean" } }, "required": [ "base64" ] } } } }, "responses": { "200": { "description": "Stored file", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "public" ] }, "legacyPublic": { "type": "boolean" }, "contentUrl": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "originalUrl": { "type": "string" } }, "required": [ "visibility", "legacyPublic", "contentUrl", "id", "url", "originalUrl" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/file/presigned-url": { "get": { "summary": "Create a presigned upload URL (GET, Fivemanage shape)", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "Unix seconds; TTL is clamped to 5 minutes" }, "required": false, "description": "Unix seconds; TTL is clamped to 5 minutes", "name": "expiresAt", "in": "query" }, { "schema": { "type": "string", "enum": [ "private", "public" ] }, "required": false, "name": "visibility", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "filename", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "path", "in": "query" }, { "schema": { "type": "string", "description": "Expected SHA-256 hex; a match returns the existing file" }, "required": false, "description": "Expected SHA-256 hex; a match returns the existing file", "name": "hash", "in": "query" } ], "responses": { "200": { "description": "Presigned URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "presignedUrl": { "type": "string" } }, "required": [ "presignedUrl" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a presigned upload URL (POST, bindable)", "description": "Body fields bind into the grant and are enforced on completion: filename, path, metadata, kind, maxBytes.", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "public" ] }, "expiresAt": { "type": "integer", "exclusiveMinimum": 0 }, "filename": { "type": "string" }, "path": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "maxBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000000 }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "Presigned URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "presignedUrl": { "type": "string" } }, "required": [ "presignedUrl" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/file/presigned-url/{token}": { "post": { "summary": "Upload to a presigned URL (multipart POST or raw PUT)", "description": "Multipart POST is limited to 8 MiB. Raw PUT with Content-Length streams up to 100,000,000 bytes. Completed retries return the original file without overwriting it; failed claimed grants require reminting.", "tags": [ "Media" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "token", "in": "path" } ], "responses": { "200": { "description": "Stored file", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "public" ] }, "legacyPublic": { "type": "boolean" }, "contentUrl": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string" }, "originalUrl": { "type": "string" } }, "required": [ "visibility", "legacyPublic", "contentUrl", "id", "url", "originalUrl" ] } }, "required": [ "status", "data" ] } } } }, "401": { "description": "Invalid, expired, or used grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Grant already claimed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/file/usage": { "get": { "summary": "Current-period usage vs plan limits", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "period": { "type": "string" }, "storageBytes": { "type": "number" }, "deliveryBytes": { "type": "number" }, "fileCount": { "type": "number" }, "plan": { "type": "string" }, "limits": { "type": "object", "properties": { "storageBytes": { "type": "number" }, "deliveryBytes": { "type": "number" } }, "required": [ "storageBytes", "deliveryBytes" ] } }, "required": [ "period", "storageBytes", "deliveryBytes", "fileCount", "plan", "limits" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/file/{path}": { "get": { "summary": "File metadata by id or path", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "path", "in": "path" } ], "responses": { "200": { "description": "File", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "$ref": "#/components/schemas/File" } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a file", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "path", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": {} } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/file/{id}": { "patch": { "summary": "Publish or unpublish a file (files:publish)", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "public" ] } }, "required": [ "visibility" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated visibility; all old shares revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "$ref": "#/components/schemas/File" } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/file/{id}/share": { "post": { "summary": "Create a bearer read link (files:publish)", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresIn": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 3600 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Single-file share, maximum 24 hours; not recipient-bound", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "url": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "url", "expiresAt" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Revoke all shares for a file (files:publish)", "tags": [ "Media" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Revoked" }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/file/{id}/content": { "get": { "summary": "Read file bytes with files:read or a valid bearer share", "tags": [ "Media" ], "security": [ { "ApiKey": [] }, {} ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "share", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "team", "in": "query" } ], "responses": { "200": { "description": "Authenticated content; private no-store" }, "206": { "description": "Single byte range" }, "304": { "description": "Authorized unchanged representation" }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "Invalid range" } } }, "head": { "summary": "Read file bytes with files:read or a valid bearer share", "tags": [ "Media" ], "security": [ { "ApiKey": [] }, {} ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "share", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "team", "in": "query" } ], "responses": { "200": { "description": "Authenticated content; private no-store" }, "206": { "description": "Single byte range" }, "304": { "description": "Authorized unchanged representation" }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "Invalid range" } } } }, "/api/v1/logs/aggregate": { "get": { "summary": "Aggregate retained logs into bounded chronological buckets", "description": "Exact counts over the inclusive from/to interval, scoped to the authenticated team. Error counts include error and fatal levels. Empty buckets are included; bucket intervals do not overlap. Metadata filters are rejected. Requires logs:read.", "tags": [ "Logs" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "required": false, "name": "dataset", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "level", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "resource", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "body", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": true, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": true, "name": "to", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "required": false, "name": "order", "in": "query" }, { "schema": { "type": [ "boolean", "null" ], "default": false }, "required": false, "name": "includeTotal", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 120, "default": 48 }, "required": false, "name": "buckets", "in": "query" } ], "responses": { "200": { "description": "Chronological buckets and exact totals", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "count": { "type": "integer", "minimum": 0 }, "errors": { "type": "integer", "minimum": 0 } }, "required": [ "from", "to", "count", "errors" ] } }, "total": { "type": "integer", "minimum": 0 }, "errors": { "type": "integer", "minimum": 0 } }, "required": [ "from", "to", "buckets", "total", "errors" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/dashboards": { "get": { "summary": "List saved dashboards", "description": "Requires boards:read. Underlying log queries require logs:read separately.", "tags": [ "Dashboards" ], "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "Team dashboards" }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/logs/datasets": { "post": { "summary": "Create a log dataset", "description": "Requires logs:admin. Ingestion may create its named dataset within plan limits with logs:write.", "tags": [ "Logs" ], "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" } }, "required": [ "name" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/logs/datasets/{name}": { "delete": { "summary": "Delete a dataset and its logs", "description": "Requires logs:delete. The default dataset cannot be deleted.", "tags": [ "Logs" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "required": true, "name": "name", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "removed": { "type": "number" } }, "required": [ "removed" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/support/team/view": { "get": { "summary": "Team support grants, signed history and dashboard notifications", "tags": [ "Support" ], "security": [ { "Dashboard": [] } ], "responses": { "200": { "description": "Latest 100 grants and 200 audit receipts", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "directoryReady": { "type": "boolean" }, "operators": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "id", "name" ], "additionalProperties": false }, "maxItems": 100 }, "grants": { "type": "array", "items": { "type": "object", "properties": { "teamId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "nonce": { "type": "string", "format": "uuid" }, "operatorId": { "type": "string", "minLength": 1, "maxLength": 200 }, "caseId": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9 _-]+$" }, "reason": { "type": "string", "minLength": 5, "maxLength": 300 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 240, "default": 30 }, "scope": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "maxItems": 20 }, "logs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "maxItems": 20 }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "timestamp", "level", "body", "resource" ] }, "minItems": 1, "maxItems": 4 }, "downloads": { "type": "boolean" }, "maxBytes": { "type": "integer", "minimum": 1, "maximum": 20971520 }, "maxReads": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "files", "logs", "fields", "downloads", "maxBytes", "maxReads" ], "additionalProperties": false }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "operatorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "approverId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "mfaAt": { "type": "integer", "minimum": 0 }, "policy": { "type": "string", "enum": [ "support-v1" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "state": { "type": "string", "enum": [ "pending", "active", "revoked", "expired" ] }, "reads": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 } }, "required": [ "teamId", "nonce", "operatorId", "caseId", "reason", "scope", "id", "operatorName", "approverId", "sessionId", "mfaAt", "policy", "createdAt", "expiresAt", "state", "reads", "bytes" ], "additionalProperties": false } }, "history": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "at": { "type": "integer", "minimum": 0 }, "policy": { "type": "string", "enum": [ "support-v1" ] }, "teamId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "grantId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "actorId": { "type": "string", "minLength": 1, "maxLength": 200 }, "action": { "type": "string", "enum": [ "consent", "allow", "deny", "revoke", "expiry" ] }, "resource": { "type": "string", "enum": [ "grant", "file", "log" ] }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "bytes": { "type": "integer", "minimum": 0, "maximum": 1048576 }, "scopeHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "reason": { "type": "string", "enum": [ "approved", "read", "first_access", "scope", "inactive", "limit", "identity", "revoked", "expired", "unavailable" ] } }, "required": [ "id", "at", "policy", "teamId", "grantId", "actorId", "action", "resource", "resourceId", "bytes", "scopeHash", "reason" ], "additionalProperties": false }, "receipt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "acceptedAt": { "type": "integer", "minimum": 0 }, "signature": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "hash", "acceptedAt", "signature" ], "additionalProperties": false } }, "required": [ "event", "receipt" ] } } }, "required": [ "enabled", "directoryReady", "operators", "grants", "history" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Consent proof already used or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Support identity or durable audit unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/support/team/grants": { "post": { "summary": "Approve exact read-only resources for a named operator", "tags": [ "Support" ], "security": [ { "Dashboard": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "teamId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "nonce": { "type": "string", "format": "uuid" }, "operatorId": { "type": "string", "minLength": 1, "maxLength": 200 }, "caseId": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9 _-]+$" }, "reason": { "type": "string", "minLength": 5, "maxLength": 300 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 240, "default": 30 }, "scope": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "maxItems": 20 }, "logs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "maxItems": 20 }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "timestamp", "level", "body", "resource" ] }, "minItems": 1, "maxItems": 4 }, "downloads": { "type": "boolean" }, "maxBytes": { "type": "integer", "minimum": 1, "maximum": 20971520 }, "maxReads": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "files", "logs", "fields", "downloads", "maxBytes", "maxReads" ], "additionalProperties": false } }, "required": [ "teamId", "nonce", "operatorId", "caseId", "reason", "scope" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Durably audited active consent", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "teamId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "nonce": { "type": "string", "format": "uuid" }, "operatorId": { "type": "string", "minLength": 1, "maxLength": 200 }, "caseId": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9 _-]+$" }, "reason": { "type": "string", "minLength": 5, "maxLength": 300 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 240, "default": 30 }, "scope": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "maxItems": 20 }, "logs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "maxItems": 20 }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "timestamp", "level", "body", "resource" ] }, "minItems": 1, "maxItems": 4 }, "downloads": { "type": "boolean" }, "maxBytes": { "type": "integer", "minimum": 1, "maximum": 20971520 }, "maxReads": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "files", "logs", "fields", "downloads", "maxBytes", "maxReads" ], "additionalProperties": false }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "operatorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "approverId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "mfaAt": { "type": "integer", "minimum": 0 }, "policy": { "type": "string", "enum": [ "support-v1" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "state": { "type": "string", "enum": [ "pending", "active", "revoked", "expired" ] }, "reads": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 } }, "required": [ "teamId", "nonce", "operatorId", "caseId", "reason", "scope", "id", "operatorName", "approverId", "sessionId", "mfaAt", "policy", "createdAt", "expiresAt", "state", "reads", "bytes" ], "additionalProperties": false } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Consent proof already used or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Support identity or durable audit unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/support/team/grants/{id}": { "delete": { "summary": "Revoke support consent immediately; audit retries on outage", "tags": [ "Support" ], "security": [ { "Dashboard": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Revoked; independent notification may be pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "auditPending": { "type": "boolean" } }, "required": [ "revoked", "auditPending" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Consent proof already used or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Support identity or durable audit unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/support/staff/grants": { "get": { "summary": "List grants for the live immutable staff identity", "tags": [ "Support" ], "security": [ { "Staff": [] } ], "responses": { "200": { "description": "Active assignments", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "properties": { "operator": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "active": { "type": "boolean", "enum": [ true ] }, "mfa": { "type": "boolean", "enum": [ true ] }, "phishingResistant": { "type": "boolean", "enum": [ true ] }, "expiresAt": { "type": "integer" } }, "required": [ "id", "name", "active", "mfa", "phishingResistant", "expiresAt" ], "additionalProperties": false }, "grants": { "type": "array", "items": { "type": "object", "properties": { "teamId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "nonce": { "type": "string", "format": "uuid" }, "operatorId": { "type": "string", "minLength": 1, "maxLength": 200 }, "caseId": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9 _-]+$" }, "reason": { "type": "string", "minLength": 5, "maxLength": 300 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 240, "default": 30 }, "scope": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "maxItems": 20 }, "logs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "maxItems": 20 }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "timestamp", "level", "body", "resource" ] }, "minItems": 1, "maxItems": 4 }, "downloads": { "type": "boolean" }, "maxBytes": { "type": "integer", "minimum": 1, "maximum": 20971520 }, "maxReads": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "files", "logs", "fields", "downloads", "maxBytes", "maxReads" ], "additionalProperties": false }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "operatorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "approverId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "mfaAt": { "type": "integer", "minimum": 0 }, "policy": { "type": "string", "enum": [ "support-v1" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "state": { "type": "string", "enum": [ "pending", "active", "revoked", "expired" ] }, "reads": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 } }, "required": [ "teamId", "nonce", "operatorId", "caseId", "reason", "scope", "id", "operatorName", "approverId", "sessionId", "mfaAt", "policy", "createdAt", "expiresAt", "state", "reads", "bytes" ], "additionalProperties": false } } }, "required": [ "operator", "grants" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Consent proof already used or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Support identity or durable audit unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/support/staff/grants/{id}/{kind}/{resource}": { "get": { "summary": "Audited exact resource read; at most 1 MiB per request", "description": "No search, pagination, aggregation or team selectors. File Range must have an explicit start/end and at most 1 MiB. Files default to their first chunk. Each read consumes the approved byte/read budgets. Conditional requests cannot bypass audit. Content release requires valid signed durable audit acceptance and final live consent/identity checks. Already admitted bytes cannot be recalled.", "tags": [ "Support" ], "security": [ { "Staff": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "file", "log" ] }, "required": true, "name": "kind", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "resource", "in": "path" }, { "schema": { "type": "string", "enum": [ "1" ] }, "required": false, "name": "download", "in": "query" } ], "responses": { "200": { "description": "Only approved log fields; private no-store JSON" }, "206": { "description": "Private no-store file chunk" }, "400": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope missing or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Consent proof already used or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Support identity or durable audit unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": {} }