{ "openapi": "3.0.3", "info": { "title": "Cedros Data API", "version": "0.1.91", "description": "Single-site Postgres-backed content and custom data storage" }, "servers": [ { "url": "http://localhost:8080", "description": "Local development server" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "DATA", "description": "Entry upsert, query, and collection registration" }, { "name": "ADMIN", "description": "Admin operations for collections, pages, and bootstrap" }, { "name": "SCHEMA", "description": "Custom schema and contract operations" }, { "name": "STORAGE", "description": "Media upload, asset management, and storage config (optional feature)" }, { "name": "SITE", "description": "Site registration, migration, import/export, and config" }, { "name": "AUTHORING", "description": "Content-addressed extension, theme, and custom-page verification" }, { "name": "SITE_MIGRATIONS", "description": "Control-plane public API for asynchronous capture of public sites into Cedros migration packages" }, { "name": "DISCOVERY", "description": "AI discovery endpoints (no auth required)" } ], "paths": { "/entries/upsert": { "post": { "operationId": "upsertEntry", "summary": "Upsert an entry", "description": "Insert or update an entry in a collection. The entry is identified by collection_name + entry_key. Payload must be a JSON object. Contracts are verified on write.", "tags": ["DATA"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertEntryRequest" } } } }, "responses": { "200": { "description": "Upserted entry record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/entries/query": { "post": { "operationId": "queryEntries", "summary": "Query entries from a collection", "description": "Retrieve entries by collection name, optionally filtered by entry_keys, a JSONB contains filter, and pagination. When visitor_id is provided, metered content gating is applied.", "tags": ["DATA"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryEntriesRequest" } } } }, "responses": { "200": { "description": "Array of matching entry records", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntryRecord" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/collections": { "post": { "operationId": "registerCollection", "summary": "Register a collection", "description": "Register a new collection with the specified mode (jsonb or typed). Optionally set table_name for typed collections and a strict_contract.", "tags": ["DATA"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCollectionRequest" } } } }, "responses": { "200": { "description": "Registered collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/custom-schema": { "post": { "operationId": "registerCustomSchema", "summary": "Register a custom schema", "description": "Apply a custom schema definition with types and tables. Returns a report of applied changes, generated SQL, and any breaking changes detected.", "tags": ["SCHEMA"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCustomSchemaRequest" } } } }, "responses": { "200": { "description": "Schema apply report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSchemaApplyReport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/contract/verify": { "post": { "operationId": "verifyContract", "summary": "Verify a contract against sample data", "description": "Check whether sample payloads are compatible with the stored contract for a collection. Returns a report with passes/failures and any breaking or additive changes.", "tags": ["SCHEMA"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyContractRequest" } } } }, "responses": { "200": { "description": "Contract verification report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractVerificationReport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/site/export": { "get": { "operationId": "exportSite", "summary": "Export complete site data", "description": "Export the entire site including site metadata, collections, contracts, custom schema, and all entries.", "tags": ["SITE"], "responses": { "200": { "description": "Full site export", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteExport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/import": { "post": { "operationId": "importSite", "summary": "Import site data", "description": "Import a previously exported site payload. Optionally overwrite existing contracts.", "tags": ["SITE"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSiteRequest" } } } }, "responses": { "200": { "description": "Import result summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/site": { "post": { "operationId": "registerSite", "summary": "Register the active site", "description": "Register or update the singleton site with a display name and optional metadata object.", "tags": ["SITE"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterSiteRequest" } } } }, "responses": { "200": { "description": "Registered site", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/migrate": { "post": { "operationId": "runMigrations", "summary": "Run database migrations", "description": "Apply any pending database migrations.", "tags": ["SITE"], "responses": { "200": { "description": "Migration success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/site/config/{key}": { "get": { "operationId": "getPublicSiteConfig", "summary": "Get public site config by key", "description": "Retrieve a publicly accessible site configuration entry. Allowed keys: global, tipping, monetization. No authentication required.", "tags": ["SITE"], "security": [], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Config key (global, tipping, or monetization)", "schema": { "type": "string", "enum": ["global", "tipping", "monetization"] } } ], "responses": { "200": { "description": "Config payload object. Returns {\"enabled\": false} if key has no stored value.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/content/preview": { "get": { "operationId": "resolveSignedPreview", "summary": "Resolve a signed preview URL", "description": "Load a preview revision using a signed URL minted by /admin/runtime/content/{id}/preview. No authentication required.", "tags": ["ADMIN"], "security": [], "parameters": [ { "name": "entryId", "in": "query", "required": true, "description": "Content entry UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionId", "in": "query", "required": true, "description": "Revision UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "expiresAt", "in": "query", "required": true, "description": "Unix timestamp when the signed URL expires", "schema": { "type": "integer", "format": "int64" } }, { "name": "signature", "in": "query", "required": true, "description": "HMAC signature for the preview request", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preview payload for the requested revision", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/bootstrap": { "post": { "operationId": "bootstrapSite", "summary": "Bootstrap site with defaults", "description": "Seed default collections and entries for the site.", "tags": ["ADMIN"], "responses": { "200": { "description": "Bootstrap report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteBootstrapReport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/collections": { "get": { "operationId": "listCollections", "summary": "List all collections", "description": "Retrieve all registered collections for the site.", "tags": ["ADMIN"], "responses": { "200": { "description": "Array of collections", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createCollection", "summary": "Create a collection (admin)", "description": "Create a new collection via the admin endpoint. Mode defaults to jsonb if omitted.", "tags": ["ADMIN"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterSiteCollectionRequest" } } } }, "responses": { "200": { "description": "Created collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/pages": { "get": { "operationId": "listPages", "summary": "List all pages", "description": "Retrieve all default page entries for the site.", "tags": ["ADMIN"], "responses": { "200": { "description": "Array of page entry records", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntryRecord" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/pages/{page_key}": { "put": { "operationId": "upsertPage", "summary": "Upsert a page", "description": "Insert or update a page entry by page_key.", "tags": ["ADMIN"], "parameters": [ { "name": "page_key", "in": "path", "required": true, "description": "Page entry key", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertPageRequest" } } } }, "responses": { "200": { "description": "Upserted page entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/default-pages": { "get": { "operationId": "getDefaultPages", "summary": "Get default page templates", "description": "Retrieve the built-in default page templates with key, title, route, and section.", "tags": ["ADMIN"], "responses": { "200": { "description": "Array of default page templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DefaultPageTemplate" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/runtime/ai-usage": { "get": { "operationId": "getAiUsageReport", "summary": "Read aggregated AI usage and spend", "description": "Aggregate every recorded AI provider call in a window: cost, tokens, success and failure counts, breakdowns by feature, model, provider, routine and job, daily buckets, the most expensive individual calls, and month-to-date spend on the same terms the billing guard enforces.", "tags": ["ADMIN"], "parameters": [ { "name": "window", "in": "query", "required": false, "description": "Reporting window. The calendar month is the default because it is the only window spending caps are enforced on.", "schema": { "type": "string", "enum": ["month", "24h", "7d", "30d", "all"], "default": "month" } } ], "responses": { "200": { "description": "Aggregated AI usage report", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/runtime/site-brain": { "get": { "operationId": "getSiteBrainPublication", "summary": "Read the canonical site-brain seam", "description": "Return one canonical text-first publication with recent durable site history plus current shared runtime state snapshots.", "tags": ["ADMIN"], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of recent history records to include.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Canonical site-brain publication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteBrainPublication" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/runtime/activity": { "get": { "operationId": "getActivityPage", "summary": "Query immutable Activity evidence", "description": "Query the durable, append-only audit and activity ledger with server-side filtering, exact totals, stable cursor pagination, provenance, actor, outcome, correlation, and integrity metadata.", "tags": ["ADMIN"], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor bound to the active filters and sort." }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "eventClass", "in": "query", "schema": { "type": "string", "enum": ["activity", "audit"] } }, { "name": "area", "in": "query", "schema": { "type": "string", "maxLength": 64 } }, { "name": "sourceKind", "in": "query", "schema": { "type": "string", "enum": ["core", "extension"] } }, { "name": "sourceId", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "actorId", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "outcome", "in": "query", "schema": { "type": "string", "maxLength": 128 } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["newest", "oldest"], "default": "newest" } } ], "responses": { "200": { "description": "Activity evidence page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityPublication" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/runtime/activity/export": { "get": { "operationId": "exportActivity", "summary": "Export immutable Activity evidence", "description": "Stream every record matching the Activity query as newline-delimited JSON. Supports the same filters and sort as the paginated route, excluding cursor and limit.", "tags": ["ADMIN"], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "eventClass", "in": "query", "schema": { "type": "string", "enum": ["activity", "audit"] } }, { "name": "area", "in": "query", "schema": { "type": "string", "maxLength": 64 } }, { "name": "sourceKind", "in": "query", "schema": { "type": "string", "enum": ["core", "extension"] } }, { "name": "sourceId", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "actorId", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "outcome", "in": "query", "schema": { "type": "string", "maxLength": 128 } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["newest", "oldest"], "default": "newest" } } ], "responses": { "200": { "description": "Newline-delimited Activity events", "content": { "application/x-ndjson": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/runtime/operational-logs": { "get": { "operationId": "getOperationalLogs", "summary": "Query durable cross-service operational logs", "description": "Query structured, privacy-sanitized logs from all Cedros services with filtering before a stable opaque cursor. Development falls back explicitly to the bounded current-process memory buffer.", "tags": ["ADMIN"], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "minLevel", "in": "query", "schema": { "type": "string", "enum": ["TRACE", "DEBUG", "INFO", "WARN", "ERROR"] } }, { "name": "targetContains", "in": "query", "schema": { "type": "string" } }, { "name": "textContains", "in": "query", "schema": { "type": "string" } }, { "name": "sourceKind", "in": "query", "schema": { "type": "string", "enum": ["core", "extension"] } }, { "name": "sourceId", "in": "query", "schema": { "type": "string" } }, { "name": "component", "in": "query", "schema": { "type": "string" } }, { "name": "surface", "in": "query", "schema": { "type": "string" } }, { "name": "service", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operational log publication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationalLogsPublication" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/admin/runtime/operational-logs/export": { "get": { "operationId": "exportOperationalLogs", "summary": "Export matching operational logs", "description": "Stream every privacy-sanitized log matching the server-side filters as newline-delimited JSON.", "tags": ["ADMIN"], "parameters": [ { "name": "minLevel", "in": "query", "schema": { "type": "string", "enum": ["TRACE", "DEBUG", "INFO", "WARN", "ERROR"] } }, { "name": "targetContains", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "textContains", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "sourceKind", "in": "query", "schema": { "type": "string", "enum": ["core", "extension"] } }, { "name": "sourceId", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "component", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "surface", "in": "query", "schema": { "type": "string", "maxLength": 128 } }, { "name": "service", "in": "query", "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "Newline-delimited operational logs", "content": { "application/x-ndjson": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/admin/runtime/client-errors": { "post": { "operationId": "recordAdminClientError", "summary": "Record a privacy-safe authenticated admin client error", "tags": ["ADMIN"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminClientErrorRequest" } } } }, "responses": { "200": { "description": "Error recorded", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/runtime/content/{id}/schedule": { "post": { "operationId": "scheduleRuntimeContentPublish", "summary": "Schedule a runtime content publish", "description": "Schedule a future publish time for the current draft revision, or clear it by sending a null publishAt value.", "tags": ["ADMIN"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Runtime content entry UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "publishAt": { "type": "string", "format": "date-time", "nullable": true }, "actorId": { "type": "string", "nullable": true }, "changeNote": { "type": "string", "nullable": true }, "reviewedRevisionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Current reviewed revision required for scheduling unless the schedule is being cleared." } } } } } }, "responses": { "200": { "description": "Updated runtime content detail", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/runtime/content/{id}/editorial-review": { "put": { "operationId": "updateRuntimeContentEditorialReview", "summary": "Persist canonical editorial review state", "description": "Store the reviewed saved-preview revision and optional live-baseline comparison for a runtime content entry.", "tags": ["ADMIN"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Runtime content entry UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewedRevisionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Current saved revision being approved for editorial review." }, "liveComparedRevisionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Current live baseline revision that was compared against the reviewed saved preview." }, "clearLiveComparison": { "type": "boolean", "default": false, "description": "Clear any previously saved live-baseline comparison for the current reviewed revision." }, "actorId": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Updated runtime content detail with canonical editorial review state", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/runtime/content/{id}/preview": { "get": { "operationId": "mintRuntimeContentPreview", "summary": "Mint a signed runtime preview URL", "description": "Create a signed preview URL for the current draft revision of a runtime content entry.", "tags": ["ADMIN"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Runtime content entry UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signed preview payload", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/runtime/content/{id}/rollback": { "post": { "operationId": "rollbackRuntimeContent", "summary": "Restore an older revision as draft", "description": "Restore a prior revision as the current draft revision for a runtime content entry.", "tags": ["ADMIN"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Runtime content entry UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["revisionId"], "properties": { "revisionId": { "type": "string", "format": "uuid" }, "actorId": { "type": "string", "nullable": true }, "changeNote": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Updated runtime content detail", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/media/upload": { "post": { "operationId": "uploadMedia", "summary": "Upload media file", "description": "Upload an image, video, or document via multipart form data. The endpoint inserts a pending asset and durable media job, returns the pending asset immediately, then a background worker stores the original object and performs processing. Images are processed into variants. Videos require ffmpeg/ffprobe and are processed into poster, optimized MP4, and HLS streaming variants. Documents are stored as original-file assets. Job stage/progress and failed async work are reflected on the asset storage/processing status and published through the authenticated media event stream. Requires the 'storage' feature.", "tags": ["STORAGE"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary", "description": "Image, video, or document file to upload" } } } } } }, "responses": { "200": { "description": "Pending uploaded asset; poll the asset for storage and processing completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/media/assets": { "get": { "operationId": "listMediaAssets", "summary": "List media assets", "description": "Retrieve a paginated list of media assets.", "tags": ["STORAGE"], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of assets to return (default 50)", "schema": { "type": "integer", "format": "int64", "default": 50 } }, { "name": "offset", "in": "query", "description": "Number of assets to skip (default 0)", "schema": { "type": "integer", "format": "int64", "default": 0 } } ], "responses": { "200": { "description": "Array of assets", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/media/assets/{asset_id}": { "get": { "operationId": "getMediaAsset", "summary": "Get a media asset", "description": "Retrieve a single media asset by ID.", "tags": ["STORAGE"], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "description": "Asset UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Asset record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateMediaAsset", "summary": "Update a media asset", "description": "Update shared media text (alt/caption) and metadata by ID.", "tags": ["STORAGE"], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "description": "Asset UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetRequest" } } } }, "responses": { "200": { "description": "Updated asset record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteMediaAsset", "summary": "Delete a media asset", "description": "Delete an asset and all its S3 objects (original + variants) by ID. Assets that are still referenced by runtime content are retained and deletion is rejected.", "tags": ["STORAGE"], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "description": "Asset UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/media/assets/{asset_id}/usage": { "get": { "operationId": "getMediaAssetUsage", "summary": "List asset usage", "description": "Return runtime content entries currently referencing the given media asset plus the current retention rule.", "tags": ["STORAGE"], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "description": "Asset UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Usage references plus retention policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUsageReport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/storage/config": { "get": { "operationId": "getStorageConfig", "summary": "Get storage configuration", "description": "Returns whether storage is enabled and a redacted summary of the config (bucket, region, endpoint, CDN, path prefix, redacted access key).", "tags": ["STORAGE"], "responses": { "200": { "description": "Storage config status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConfigResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/storage/test": { "post": { "operationId": "testStorage", "summary": "Test storage connectivity", "description": "Verify that the S3-compatible storage connection is working by issuing a HEAD-bucket request.", "tags": ["STORAGE"], "responses": { "200": { "description": "Storage connection test passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai.txt": { "get": { "operationId": "getAiTxt", "summary": "AI discovery text", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "AI discovery text", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "summary": "LLM documentation (summary)", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "LLM summary documentation", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFullTxt", "summary": "LLM documentation (full)", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "Full LLM documentation", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms-admin.txt": { "get": { "operationId": "getLlmsAdminTxt", "summary": "LLM documentation (admin)", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "Admin-focused LLM documentation", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/skill.md": { "get": { "operationId": "getSkillMd", "summary": "Cedros site-operator entrypoint (Markdown)", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "MCP-first operating guide, capability landscape, and published skill index", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/skill.txt": { "get": { "operationId": "getSkillTxt", "summary": "Cedros agent entrypoint (plain UTF-8)", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "Plain-text fallback containing the same Markdown bytes as /skill.md", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/skill": { "get": { "operationId": "getSkillHtml", "summary": "Cedros agent entrypoint (no-JavaScript HTML)", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "HTML fallback for fetch layers that reject text/markdown", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/schemas/extension-manifest.schema.json": { "get": { "operationId": "getExtensionManifestSchema", "summary": "Canonical Cedros extension manifest JSON Schema", "tags": ["AUTHORING", "DISCOVERY"], "security": [], "responses": { "200": { "description": "Schema-version-1 extension manifest contract", "content": { "application/schema+json": { "schema": { "type": "object" } } } } } } }, "/schemas/extension-context.schema.json": { "get": { "operationId": "getExtensionContextSchema", "summary": "Canonical shared extension-authoring context JSON Schema", "tags": ["AUTHORING", "DISCOVERY"], "security": [], "responses": { "200": { "description": "Validated cross-phase authoring state contract", "content": { "application/schema+json": { "schema": { "type": "object" } } } } } } }, "/authoring/{version}/extension/kit.zip": { "get": { "operationId": "getVersionedExtensionAuthoringKit", "summary": "Download an immutable versioned extension authoring kit or the latest alias", "tags": ["AUTHORING", "DISCOVERY"], "security": [], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "example": "0.1.74" } } ], "responses": { "200": { "description": "Checksummed authoring kit; numeric versions are immutable", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Authoring kit version not found" } } } }, "/authoring/{version}/extension/{path}": { "get": { "operationId": "getVersionedExtensionAuthoringFile", "summary": "Read one file from an immutable versioned extension authoring corpus or the latest alias", "tags": ["AUTHORING", "DISCOVERY"], "security": [], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "example": "0.1.74" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exact versioned corpus file with provenance and cache validators" }, "404": { "description": "Version or file not found" } } } }, "/skills/cedros-extension-authoring/kit.zip": { "get": { "operationId": "getExtensionAuthoringKit", "summary": "Download the public version-matched extension authoring kit", "tags": ["AUTHORING", "DISCOVERY"], "security": [], "responses": { "200": { "description": "Checksummed ZIP containing the complete extension authoring guide, examples, validation scripts, WIT, and admin design contract", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/skills/cedros-extension-authoring/AUTHORING-KIT.json": { "get": { "operationId": "getExtensionAuthoringKitManifest", "summary": "Extension authoring kit compatibility and checksums", "tags": ["AUTHORING", "DISCOVERY"], "security": [], "responses": { "200": { "description": "Version, compatibility contract, public guide paths, and SHA-256 checksums", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/skills/cedros-extension-authoring/docs/extension-authoring/{path}": { "get": { "operationId": "getExtensionAuthoringFile", "summary": "Read one file from the public version-matched extension authoring guide", "tags": ["AUTHORING", "DISCOVERY"], "security": [], "parameters": [ { "name": "path", "in": "path", "required": true, "description": "Relative guide path, including nested reference, contract, or example paths", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exact file embedded in the matching extension authoring kit" }, "404": { "description": "Extension authoring file not found" } } } }, "/skill.json": { "get": { "operationId": "getSkillJson", "summary": "Cedros skill and discovery metadata (JSON)", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "Machine-readable task modes, precedence, provenance, document hashes, skills, and extension capabilities", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent.md": { "get": { "operationId": "getAgentMd", "summary": "Agent integration guide", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "Agent integration guide in Markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/page-docs/index.json": { "get": { "operationId": "getPageDocsIndex", "summary": "Page-guide section index", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "Compact page-guide section metadata and pointers", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/page-docs/sections/{sectionKey}.json": { "get": { "operationId": "getPageDocSection", "summary": "Page-guide metadata for one section", "tags": ["DISCOVERY"], "security": [], "parameters": [ { "name": "sectionKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Compact page-guide metadata for one section", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Page-guide section not found" } } } }, "/page-docs/{slug}.md": { "get": { "operationId": "getPageDocMarkdown", "summary": "One page-specific agent guide", "tags": ["DISCOVERY"], "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page-specific guide in Markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "Page guide not found" } } } }, "/heartbeat.md": { "get": { "operationId": "getHeartbeatMd", "summary": "Health check (Markdown)", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "Health status in Markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/heartbeat.json": { "get": { "operationId": "getHeartbeatJson", "summary": "Health check (JSON)", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "Health status in JSON", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/.well-known/ai-discovery.json": { "get": { "operationId": "getAiDiscoveryJson", "summary": "AI discovery index manifest", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "AI discovery index", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/ai-plugin.json": { "get": { "operationId": "getAiPluginJson", "summary": "OpenAI plugin manifest", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "OpenAI plugin manifest", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/agent.json": { "get": { "operationId": "getAgentJson", "summary": "A2A agent manifest", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "A2A agent manifest", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/mcp": { "get": { "operationId": "getMcpDiscovery", "summary": "MCP discovery endpoint", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "MCP endpoint, resources, tool schemas, and authentication guidance", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/mcp-lite.json": { "get": { "operationId": "getCompactMcpDiscovery", "summary": "Compact MCP discovery endpoint", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "MCP endpoint, resources, tool names, short descriptions, and authentication guidance", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/skills.zip": { "get": { "operationId": "getSkillsBundle", "summary": "Downloadable skills bundle", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "ZIP archive of all skill files", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/api/v1/site-migrations": { "post": { "operationId": "createPublicSiteMigration", "security": [], "summary": "Queue a public-site migration", "description": "Available without login only on cedros.ai, cedroscloud.com, and cedros.io; other hosts return 404. Validates a public HTTP(S) URL, customer rights attestation, scope, SSRF policy, robots policy, and server hard limits, then transactionally enqueues a durable browser-rendered capture. Idempotency-Key is required. The service captures only publicly observable material; it cannot recover drafts, private data or behavior, credentials, authenticated pages, original files never served publicly, private CRM/automation details, or exact licensing terms. Treat the returned migration ID as a capability secret.", "tags": ["SITE_MIGRATIONS"], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteMigrationRequest" } } } }, "responses": { "202": { "description": "Durable migration queued or idempotently replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteMigrationAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v1/site-migrations/{migration_id}": { "get": { "operationId": "getPublicSiteMigration", "security": [], "summary": "Get durable migration status and progress", "tags": ["SITE_MIGRATIONS"], "parameters": [{ "$ref": "#/components/parameters/MigrationId" }], "responses": { "200": { "description": "Migration status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteMigrationRecord" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/site-migrations/{migration_id}/events": { "get": { "operationId": "streamPublicSiteMigrationEvents", "security": [], "summary": "Replay and follow migration events", "description": "Migration-ID-scoped SSE with durable monotonic IDs. Reconnect with Last-Event-ID; terminal events remain replayable for the configured retention period.", "tags": ["SITE_MIGRATIONS"], "parameters": [ { "$ref": "#/components/parameters/MigrationId" }, { "name": "Last-Event-ID", "in": "header", "schema": { "type": "integer", "minimum": 0 } }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "SSE events: migration.status, migration.progress, crawl.url_discovered, crawl.page_started, crawl.page_completed, crawl.page_failed, crawl.asset_saved, crawl.asset_excluded, crawl.issue, migration.package_ready, migration.completed, migration.failed, or migration.canceled", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/site-migrations/{migration_id}/cancel": { "post": { "operationId": "cancelPublicSiteMigration", "security": [], "summary": "Cancel a queued or active migration", "description": "Stops new scheduling, terminates active browser work, preserves captured evidence, and durably converges on canceled.", "tags": ["SITE_MIGRATIONS"], "parameters": [{ "$ref": "#/components/parameters/MigrationId" }], "responses": { "200": { "description": "Canceling, canceled, or already-terminal migration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteMigrationRecord" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/site-migrations/{migration_id}/result": { "get": { "operationId": "getPublicSiteMigrationResult", "security": [], "summary": "Get the versioned machine migration specification", "tags": ["SITE_MIGRATIONS"], "parameters": [{ "$ref": "#/components/parameters/MigrationId" }], "responses": { "200": { "description": "cedros.public-site-migration/v1 result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSiteMigrationSpec" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/site-migrations/{migration_id}/package": { "get": { "operationId": "downloadPublicSiteMigrationPackage", "security": [], "summary": "Download the migration ZIP package", "tags": ["SITE_MIGRATIONS"], "parameters": [ { "$ref": "#/components/parameters/MigrationId" }, { "name": "Range", "in": "header", "description": "Optional single byte range for resumable downloads", "schema": { "type": "string", "example": "bytes=0-1048575" } } ], "responses": { "200": { "description": "Integrity-verified deterministic ZIP streamed with Content-Length, ETag, Accept-Ranges, and X-Cedros-Package-Sha256", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Requested ZIP byte range", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/site-migrations/{migration_id}/pages": { "get": { "operationId": "listPublicSiteMigrationPages", "security": [], "summary": "List or search captured pages", "description": "Search covers URL, route, target path, title, headings, normalized visible text, form labels, image alt text, and document titles.", "tags": ["SITE_MIGRATIONS"], "parameters": [ { "$ref": "#/components/parameters/MigrationId" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Migration-ID-scoped page results", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/site-migrations/{migration_id}/pages/{page_id}": { "get": { "operationId": "getPublicSiteMigrationPage", "security": [], "summary": "Inspect one captured page record", "tags": ["SITE_MIGRATIONS"], "parameters": [ { "$ref": "#/components/parameters/MigrationId" }, { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Exact content, sections, provenance, evidence references, forms, links, assets, SEO, and recommendations", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiSpec", "summary": "OpenAPI specification", "tags": ["DISCOVERY"], "security": [], "responses": { "200": { "description": "This OpenAPI 3.0 specification", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token passed via Authorization header. When cedros-login-profile is enabled, the token is verified against the cedros-login service. The x-cedros-org-id header is also required for organization-scoped requests." } }, "parameters": { "MigrationId": { "name": "migration_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^mig_[0-9a-f]{32}$" } } }, "schemas": { "CreateSiteMigrationRequest": { "type": "object", "required": ["source_url", "authorization"], "properties": { "source_url": { "type": "string", "format": "uri", "description": "Public HTTP(S) URL without embedded credentials" }, "name": { "type": "string", "maxLength": 200 }, "authorization": { "type": "object", "required": ["customer_authorized_public_capture"], "properties": { "customer_authorized_public_capture": { "type": "boolean", "enum": [true] }, "note": { "type": "string", "nullable": true } } }, "scope": { "type": "object", "properties": { "include_subdomains": { "type": "boolean", "default": false }, "allowed_hosts": { "type": "array", "items": { "type": "string" }, "description": "Only hosts related to the canonical source host are accepted" }, "include_paths": { "type": "array", "items": { "type": "string" }, "default": ["/"] }, "exclude_paths": { "type": "array", "items": { "type": "string" } }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "max_depth": { "type": "integer", "minimum": 0, "maximum": 12, "default": 8 } } }, "crawl": { "type": "object", "description": "Robots defaults true. Override requires DataAdmin and a non-empty robots_override_reason. Raw/rendered HTML, screenshots, images, documents, external referenced assets, and safe presentation interactions default true." }, "output": { "type": "object", "description": "Machine spec, implementation Markdown, and ZIP generation default true and are required to remain enabled by schema v1." } } }, "SiteMigrationAccepted": { "type": "object", "required": ["id", "status", "stage", "source_url", "created_at", "status_url", "events_url", "result_url", "package_url"], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued"] }, "stage": { "type": "string" }, "source_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "status_url": { "type": "string" }, "events_url": { "type": "string" }, "result_url": { "type": "string" }, "package_url": { "type": "string" }, "idempotent_replay": { "type": "boolean" } } }, "SiteMigrationProgress": { "type": "object", "required": ["pages_discovered", "pages_queued", "pages_processing", "pages_captured", "pages_failed", "pages_blocked", "assets_discovered", "assets_saved", "assets_excluded", "assets_failed", "documents_saved", "bytes_downloaded"], "additionalProperties": { "type": "integer", "minimum": 0 } }, "SiteMigrationRecord": { "type": "object", "required": ["id", "tenant_id", "source_url", "status", "stage", "progress", "warning_count", "error_count", "result_available", "package_available", "created_at", "updated_at"], "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "source_url": { "type": "string" }, "canonical_origin": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["queued", "preflight", "crawling", "extracting", "normalizing", "packaging", "completed", "completed_with_warnings", "failed", "canceling", "canceled"] }, "stage": { "type": "string" }, "progress": { "$ref": "#/components/schemas/SiteMigrationProgress" }, "crawl_limits": { "type": "object" }, "warning_count": { "type": "integer" }, "error_count": { "type": "integer" }, "result_available": { "type": "boolean" }, "package_available": { "type": "boolean" }, "artifact": { "type": "object", "nullable": true }, "fatal_error": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "PublicSiteMigrationSpec": { "type": "object", "required": ["schema_version", "migration", "source", "capture", "routes", "redirects", "global_components", "templates", "collections", "pages", "assets", "documents", "forms", "integrations", "design_tokens", "issues", "statistics"], "properties": { "schema_version": { "type": "string", "enum": ["cedros.public-site-migration/v1"] }, "migration": { "type": "object" }, "source": { "type": "object" }, "capture": { "type": "object" }, "routes": { "type": "array", "items": { "type": "object" } }, "redirects": { "type": "array", "items": { "type": "object" } }, "global_components": { "type": "array", "items": { "type": "object" } }, "templates": { "type": "array", "items": { "type": "object" } }, "collections": { "type": "array", "items": { "type": "object" } }, "pages": { "type": "array", "items": { "type": "object" } }, "assets": { "type": "array", "items": { "type": "object" } }, "documents": { "type": "array", "items": { "type": "object" } }, "forms": { "type": "array", "items": { "type": "object" } }, "integrations": { "type": "array", "items": { "type": "object" } }, "design_tokens": { "type": "object" }, "authoring_starter": { "type": "object", "description": "Review-required page, theme, and extension authoring handoff. Capture never marks publication or rights approval.", "required": ["contract_version", "review_status", "source_boundary", "migration", "page_candidates", "theme_candidate", "extension_candidate", "rights_review", "required_reviews", "guides"], "properties": { "contract_version": { "type": "string", "enum": ["cedros.site-migration-authoring-starter/v1"] }, "review_status": { "type": "string", "enum": ["review_required"] }, "source_boundary": { "type": "object" }, "migration": { "type": "object" }, "page_candidates": { "type": "array", "items": { "type": "object" } }, "theme_candidate": { "type": "object" }, "extension_candidate": { "type": "object" }, "rights_review": { "type": "object" }, "required_reviews": { "type": "array", "items": { "type": "string" } }, "guides": { "type": "object" } } }, "issues": { "type": "array", "items": { "type": "object" } }, "statistics": { "type": "object" } } }, "UpsertEntryRequest": { "type": "object", "required": ["collection_name", "entry_key", "payload"], "properties": { "collection_name": { "type": "string", "description": "Target collection name" }, "entry_key": { "type": "string", "description": "Unique key for the entry within the collection" }, "payload": { "type": "object", "description": "Entry data (must be a JSON object)" } } }, "QueryEntriesRequest": { "type": "object", "required": ["collection_name"], "properties": { "collection_name": { "type": "string", "description": "Collection to query" }, "entry_keys": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Optional filter by specific entry keys" }, "contains": { "type": "object", "nullable": true, "description": "Optional JSONB containment filter (@>) applied to payload" }, "limit": { "type": "integer", "format": "int64", "default": 100, "minimum": 0, "maximum": 1000, "description": "Maximum entries to return" }, "offset": { "type": "integer", "format": "int64", "default": 0, "minimum": 0, "description": "Number of entries to skip" }, "visitor_id": { "type": "string", "nullable": true, "description": "Optional visitor ID for metered content gating" } } }, "EntryRecord": { "type": "object", "required": ["entry_key", "payload", "updated_at", "version"], "properties": { "entry_key": { "type": "string" }, "payload": { "type": "object" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "string", "nullable": true, "description": "Opaque revision token for JSONB entries; null for typed collections" } } }, "RegisterCollectionRequest": { "type": "object", "required": ["collection_name", "mode"], "properties": { "collection_name": { "type": "string" }, "mode": { "$ref": "#/components/schemas/CollectionMode" }, "table_name": { "type": "string", "nullable": true, "description": "Required for typed mode" }, "strict_contract": { "nullable": true, "allOf": [{ "$ref": "#/components/schemas/ContractSchema" }], "description": "Optional strict contract enforced on all writes" } } }, "RegisterSiteCollectionRequest": { "type": "object", "required": ["collection_name"], "properties": { "collection_name": { "type": "string" }, "mode": { "nullable": true, "allOf": [{ "$ref": "#/components/schemas/CollectionMode" }], "description": "Defaults to jsonb if omitted" }, "table_name": { "type": "string", "nullable": true }, "strict_contract": { "nullable": true, "allOf": [{ "$ref": "#/components/schemas/ContractSchema" }] } } }, "Collection": { "type": "object", "required": ["collection_name", "mode"], "properties": { "collection_name": { "type": "string" }, "mode": { "$ref": "#/components/schemas/CollectionMode" }, "table_name": { "type": "string", "nullable": true }, "strict_contract": { "nullable": true, "allOf": [{ "$ref": "#/components/schemas/ContractSchema" }] } } }, "CollectionMode": { "type": "string", "enum": ["jsonb", "typed"], "description": "Storage mode: jsonb (default flexible JSON) or typed (Postgres-native table)" }, "RegisterSiteRequest": { "type": "object", "required": ["display_name"], "properties": { "display_name": { "type": "string" }, "metadata": { "type": "object", "default": {}, "description": "Arbitrary site metadata" } } }, "Site": { "type": "object", "required": ["display_name", "metadata"], "properties": { "display_name": { "type": "string" }, "metadata": { "type": "object" } } }, "RegisterCustomSchemaRequest": { "type": "object", "required": ["definition"], "properties": { "definition": { "$ref": "#/components/schemas/CustomSchemaDefinition" } } }, "CustomSchemaDefinition": { "type": "object", "properties": { "types": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/CustomTypeDefinition" } }, "tables": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/CustomTableDefinition" } } } }, "CustomTypeDefinition": { "type": "object", "required": ["kind", "name"], "description": "Discriminated union tagged by 'kind'. Enum types have 'values'; composite types have 'fields'.", "properties": { "kind": { "type": "string", "enum": ["enum", "composite"] }, "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" }, "description": "Required for enum kind" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomColumnDefinition" }, "description": "Required for composite kind" } } }, "CustomTableDefinition": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "columns": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/CustomColumnDefinition" } }, "primary_key": { "type": "array", "default": [], "items": { "type": "string" } }, "unique_constraints": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/UniqueConstraintDefinition" } }, "foreign_keys": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/ForeignKeyDefinition" } }, "indexes": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/IndexDefinition" } } } }, "CustomColumnDefinition": { "type": "object", "required": ["name", "data_type"], "properties": { "name": { "type": "string" }, "data_type": { "type": "string", "description": "Supported Postgres built-in type or schema-qualified custom type; type modifiers and arrays are supported" }, "nullable": { "type": "boolean", "default": false }, "default_sql": { "type": "string", "nullable": true, "description": "Postgres literal, optional type cast, or supported built-in default such as CURRENT_TIMESTAMP, NOW(), or gen_random_uuid()" } } }, "UniqueConstraintDefinition": { "type": "object", "required": ["columns"], "properties": { "name": { "type": "string", "nullable": true }, "columns": { "type": "array", "items": { "type": "string" } } } }, "ForeignKeyDefinition": { "type": "object", "required": ["columns", "ref_table", "ref_columns"], "properties": { "name": { "type": "string", "nullable": true }, "columns": { "type": "array", "items": { "type": "string" } }, "ref_table": { "type": "string" }, "ref_columns": { "type": "array", "items": { "type": "string" } }, "on_delete": { "type": "string", "nullable": true, "description": "e.g. CASCADE, SET NULL" } } }, "IndexDefinition": { "type": "object", "required": ["columns"], "properties": { "name": { "type": "string", "nullable": true }, "columns": { "type": "array", "items": { "type": "string" } }, "unique": { "type": "boolean", "default": false } } }, "CustomSchemaApplyReport": { "type": "object", "required": ["applied", "version", "additive_changes", "breaking_changes", "generated_sql"], "properties": { "applied": { "type": "boolean", "description": "Whether the schema was applied" }, "version": { "type": "integer", "format": "int32" }, "additive_changes": { "type": "array", "items": { "type": "string" } }, "breaking_changes": { "type": "array", "items": { "type": "string" } }, "generated_sql": { "type": "array", "items": { "type": "string" } } } }, "VerifyContractRequest": { "type": "object", "required": ["collection_name", "samples"], "properties": { "collection_name": { "type": "string" }, "samples": { "type": "array", "items": { "type": "object" }, "description": "Sample payloads to verify against the stored contract" } } }, "ContractVerificationReport": { "type": "object", "required": ["passes", "additive_changes", "breaking_changes", "incoming_contract"], "properties": { "passes": { "type": "boolean" }, "additive_changes": { "type": "array", "items": { "type": "string" } }, "breaking_changes": { "type": "array", "items": { "type": "string" } }, "stored_contract": { "nullable": true, "allOf": [{ "$ref": "#/components/schemas/ContractSchema" }] }, "incoming_contract": { "$ref": "#/components/schemas/ContractSchema" } } }, "ContractSchema": { "type": "object", "required": ["fields"], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ContractField" } } } }, "ContractField": { "type": "object", "required": ["path", "required", "types"], "properties": { "path": { "type": "string", "description": "Dot-separated path into the payload" }, "required": { "type": "boolean" }, "types": { "type": "array", "items": { "$ref": "#/components/schemas/ValueType" } } } }, "ValueType": { "type": "string", "enum": ["string", "number", "boolean", "object", "array", "null"] }, "SiteExport": { "type": "object", "required": ["site", "collections", "contracts"], "description": "Structural site template — settings + routing + nav + email scaffolding. Operational data (entries, contacts, analytics, campaign history) is not exported; use a full backup for that.", "properties": { "site": { "$ref": "#/components/schemas/Site" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }, "custom_schema": { "nullable": true, "allOf": [{ "$ref": "#/components/schemas/CustomSchemaDefinition" }] }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionContractRecord" } }, "site_settings": { "nullable": true, "allOf": [{ "$ref": "#/components/schemas/SiteSettingsExport" }] }, "redirects": { "type": "array", "items": { "$ref": "#/components/schemas/RedirectExport" } }, "navigation_menus": { "type": "array", "items": { "$ref": "#/components/schemas/NavigationMenuExport" } }, "email_templates": { "type": "array", "items": { "$ref": "#/components/schemas/EmailCampaignTemplateExport" } }, "email_snippets": { "type": "array", "items": { "$ref": "#/components/schemas/EmailCampaignSnippetExport" } }, "sending_providers": { "type": "array", "items": { "$ref": "#/components/schemas/SendingProviderExport" } }, "sender_identities": { "type": "array", "items": { "$ref": "#/components/schemas/SenderIdentityExport" } } } }, "SiteSettingsExport": { "type": "object", "required": [ "site_title", "site_description", "default_description", "default_og_image", "canonical_origin", "locale", "timezone" ], "properties": { "site_title": { "type": "string" }, "site_description": { "type": "string" }, "default_description": { "type": "string" }, "default_og_image": { "type": "string" }, "canonical_origin": { "type": "string" }, "locale": { "type": "string" }, "timezone": { "type": "string" }, "social_links": { "type": "object" }, "metadata": { "type": "object" } } }, "RedirectExport": { "type": "object", "required": ["source_path", "target_path", "status_code"], "properties": { "source_path": { "type": "string" }, "target_path": { "type": "string" }, "status_code": { "type": "integer", "format": "int32" }, "is_prefix": { "type": "boolean", "default": false }, "forward_path": { "type": "boolean", "default": false }, "note": { "type": "string", "nullable": true } } }, "NavigationMenuExport": { "type": "object", "required": ["menu_key", "title"], "properties": { "menu_key": { "type": "string" }, "title": { "type": "string" }, "metadata": { "type": "object" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NavigationItemExport" } } } }, "NavigationItemExport": { "type": "object", "required": ["source_id", "label", "href", "position"], "properties": { "source_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "href": { "type": "string" }, "item_type": { "type": "string", "default": "link" }, "content_type": { "type": "string", "nullable": true }, "content_slug": { "type": "string", "nullable": true }, "parent_ref": { "type": "string", "format": "uuid", "nullable": true }, "position": { "type": "integer", "format": "int32" }, "metadata": { "type": "object" } } }, "EmailCampaignTemplateExport": { "type": "object", "required": [ "name", "category", "status", "subject_template", "preheader_template", "html_body_template", "plain_text_body_template", "default_archive_enabled", "default_tracking_enabled" ], "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string" }, "status": { "type": "string" }, "subject_template": { "type": "string" }, "preheader_template": { "type": "string" }, "html_body_template": { "type": "string" }, "plain_text_body_template": { "type": "string" }, "default_from_name": { "type": "string", "nullable": true }, "default_from_email": { "type": "string", "nullable": true }, "default_reply_to": { "type": "string", "nullable": true }, "default_archive_enabled": { "type": "boolean" }, "default_tracking_enabled": { "type": "boolean" }, "metadata": { "type": "object" } } }, "EmailCampaignSnippetExport": { "type": "object", "required": [ "name", "category", "content_type", "html_content", "plain_text_content", "status" ], "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string" }, "content_type": { "type": "string" }, "html_content": { "type": "string" }, "plain_text_content": { "type": "string" }, "status": { "type": "string" }, "metadata": { "type": "object" } } }, "SendingProviderExport": { "type": "object", "required": ["name", "provider_kind", "rate_limit_per_minute"], "description": "Provider config shell — API keys and credentials are intentionally not exported.", "properties": { "name": { "type": "string" }, "provider_kind": { "type": "string" }, "rate_limit_per_minute": { "type": "integer", "format": "int32" }, "metadata": { "type": "object" } } }, "SenderIdentityExport": { "type": "object", "required": ["from_name", "from_email", "reply_to"], "description": "Sender identity shell — verification tokens are not exported; imported identities start as 'unverified'.", "properties": { "from_name": { "type": "string" }, "from_email": { "type": "string" }, "reply_to": { "type": "string" }, "provider_name": { "type": "string", "nullable": true }, "metadata": { "type": "object" } } }, "CollectionContractRecord": { "type": "object", "required": ["collection_name", "version", "contract"], "properties": { "collection_name": { "type": "string" }, "version": { "type": "integer", "format": "int32" }, "contract": { "$ref": "#/components/schemas/ContractSchema" } } }, "ImportSiteRequest": { "type": "object", "required": ["export"], "properties": { "export": { "$ref": "#/components/schemas/SiteExport" }, "overwrite_contracts": { "type": "boolean", "default": false, "description": "Whether to overwrite existing contracts during import" } } }, "ImportResult": { "type": "object", "required": [ "collections_imported", "contracts_imported", "site_settings_imported", "redirects_imported", "navigation_menus_imported", "email_templates_imported", "email_snippets_imported", "sending_providers_imported", "sender_identities_imported" ], "properties": { "collections_imported": { "type": "integer" }, "contracts_imported": { "type": "integer" }, "site_settings_imported": { "type": "boolean" }, "redirects_imported": { "type": "integer" }, "navigation_menus_imported": { "type": "integer" }, "email_templates_imported": { "type": "integer" }, "email_snippets_imported": { "type": "integer" }, "sending_providers_imported": { "type": "integer" }, "sender_identities_imported": { "type": "integer" } } }, "UpsertPageRequest": { "type": "object", "required": ["payload"], "properties": { "payload": { "type": "object", "description": "Page content payload" } } }, "DefaultPageTemplate": { "type": "object", "required": ["key", "title", "route", "section"], "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "route": { "type": "string" }, "section": { "type": "string" } } }, "SiteBootstrapReport": { "type": "object", "required": ["collections_seeded", "entries_seeded"], "properties": { "collections_seeded": { "type": "integer" }, "entries_seeded": { "type": "integer" } } }, "Asset": { "type": "object", "required": ["id", "filename", "contentType", "sizeBytes", "variants", "text", "metadata", "storage", "processing", "createdAt", "updatedAt"], "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64" }, "dimensions": { "allOf": [{ "$ref": "#/components/schemas/MediaDimensions" }], "nullable": true }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/AssetVariant" }, "description": "Processed image and video variants (resized images, WebP, video poster, optimized MP4, HLS playlist/segments). Documents have an empty variants array." }, "text": { "$ref": "#/components/schemas/MediaAssetText" }, "metadata": { "type": "object" }, "storage": { "$ref": "#/components/schemas/MediaStorageState" }, "processing": { "$ref": "#/components/schemas/MediaProcessingState" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AssetVariant": { "type": "object", "required": ["suffix", "key", "url", "contentType", "dimensions", "kind", "storageStatus", "processingStatus"], "properties": { "suffix": { "type": "string", "description": "Variant identifier (e.g. 'sm', 'md', 'webp')" }, "key": { "type": "string", "description": "S3 object key" }, "url": { "type": "string", "format": "uri", "description": "Public URL for the variant" }, "contentType": { "type": "string" }, "dimensions": { "$ref": "#/components/schemas/MediaDimensions" }, "kind": { "type": "string", "enum": ["thumbnail", "web_optimized", "video_poster", "adaptive_stream", "derived"] }, "storageStatus": { "type": "string", "enum": ["pending", "stored", "missing", "deleting", "failed"] }, "processingStatus": { "type": "string", "enum": ["pending", "ready", "failed"] } } }, "MediaDimensions": { "type": "object", "required": ["width", "height"], "properties": { "width": { "type": "integer", "format": "int32" }, "height": { "type": "integer", "format": "int32" } } }, "MediaAssetText": { "type": "object", "required": ["alt", "caption"], "properties": { "alt": { "type": "string", "nullable": true }, "caption": { "type": "string", "nullable": true } } }, "MediaStorageState": { "type": "object", "required": ["status", "originalKey", "originalUrl", "lastError"], "properties": { "status": { "type": "string", "enum": ["pending", "stored", "missing", "deleting", "failed"] }, "originalKey": { "type": "string" }, "originalUrl": { "type": "string" }, "lastError": { "type": "string", "nullable": true } } }, "MediaProcessingState": { "type": "object", "required": ["status", "stage", "progressPercent", "lastError", "variantCount"], "properties": { "status": { "type": "string", "enum": ["pending", "ready", "failed"] }, "stage": { "type": "string", "description": "Human-readable async media job stage such as queued, uploading_original, processing_image, processing_video, storing_variants, retrying, ready, or failed." }, "progressPercent": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100 }, "lastError": { "type": "string", "nullable": true }, "variantCount": { "type": "integer", "format": "int32" } } }, "MediaRetentionPolicy": { "type": "object", "required": ["mode", "canDelete", "reason", "referenceCount"], "properties": { "mode": { "type": "string", "enum": ["delete_when_unused", "retain_while_referenced"] }, "canDelete": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "referenceCount": { "type": "integer", "format": "int32" } } }, "MediaUsageReport": { "type": "object", "required": ["references", "referenceCount", "retention"], "properties": { "references": { "type": "array", "items": { "$ref": "#/components/schemas/MediaUsageReference" } }, "referenceCount": { "type": "integer", "format": "int32" }, "retention": { "$ref": "#/components/schemas/MediaRetentionPolicy" } } }, "MediaUsageReference": { "type": "object", "required": ["entryId", "contentType", "slug", "routePath", "title", "status", "role", "updatedAt"], "properties": { "entryId": { "type": "string", "format": "uuid" }, "contentType": { "type": "string" }, "slug": { "type": "string" }, "routePath": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "role": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "UpdateAssetRequest": { "type": "object", "properties": { "text": { "type": "object", "properties": { "alt": { "type": "string", "nullable": true }, "caption": { "type": "string", "nullable": true } } }, "alt_text": { "type": "string", "nullable": true }, "caption": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true } } }, "StorageConfigResponse": { "type": "object", "required": ["enabled"], "properties": { "enabled": { "type": "boolean" }, "config": { "type": "object", "nullable": true, "description": "Present when enabled=true. Contains redacted storage configuration.", "properties": { "bucket": { "type": "string" }, "region": { "type": "string" }, "endpoint": { "type": "string", "nullable": true }, "cdn_base_url": { "type": "string", "nullable": true }, "path_prefix": { "type": "string", "nullable": true }, "access_key": { "type": "string", "description": "Redacted access key (first 3 + last 3 chars)" } } } } }, "SiteBrainSourceKind": { "type": "string", "enum": ["core", "extension"] }, "SiteBrainReference": { "type": "object", "required": ["kind", "label", "href"], "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "href": { "type": "string" } } }, "SiteBrainRecord": { "type": "object", "required": [ "id", "occurredAt", "sourceKind", "sourceId", "category", "title", "summary", "text", "tags", "details", "references" ], "properties": { "id": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "sourceKind": { "$ref": "#/components/schemas/SiteBrainSourceKind" }, "sourceId": { "type": "string" }, "category": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "text": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "details": { "type": "object" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/SiteBrainReference" } } } }, "SiteBrainSnapshotSection": { "type": "object", "required": ["section", "title", "summary", "text", "state"], "properties": { "section": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "text": { "type": "string" }, "state": { "type": "object" } } }, "SiteBrainPublication": { "type": "object", "required": ["generatedAt", "timelineLimit", "timeline", "snapshot"], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "timelineLimit": { "type": "integer", "format": "int64" }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/SiteBrainRecord" } }, "snapshot": { "type": "array", "items": { "$ref": "#/components/schemas/SiteBrainSnapshotSection" } } } }, "ActivityEvent": { "type": "object", "required": ["id", "occurredAt", "recordedAt", "eventClass", "area", "sourceKind", "sourceId", "category", "title", "summary", "text", "sourceTable", "sourceRecordId", "transactionId", "tags", "details", "references", "schemaVersion", "contentSha256"], "properties": { "id": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "eventClass": { "type": "string", "enum": ["activity", "audit"] }, "area": { "type": "string" }, "sourceKind": { "$ref": "#/components/schemas/SiteBrainSourceKind" }, "sourceId": { "type": "string" }, "category": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "text": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "actorType": { "type": "string", "nullable": true }, "actorId": { "type": "string", "nullable": true }, "outcome": { "type": "string", "nullable": true }, "correlationId": { "type": "string", "nullable": true }, "causationId": { "type": "string", "nullable": true }, "sourceTable": { "type": "string" }, "sourceRecordId": { "type": "string" }, "transactionId": { "type": "integer", "format": "int64" }, "tags": { "type": "array", "items": { "type": "string" } }, "details": { "type": "object" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/SiteBrainReference" } }, "schemaVersion": { "type": "integer" }, "contentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "ActivityPublication": { "type": "object", "required": ["generatedAt", "totalMatching", "hasMore", "nextCursor", "maxPageSize", "durable", "appendOnly", "events", "facets"], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "totalMatching": { "type": "integer", "format": "int64" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true }, "maxPageSize": { "type": "integer", "maximum": 500 }, "durable": { "type": "boolean", "enum": [true] }, "appendOnly": { "type": "boolean", "enum": [true] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEvent" } }, "facets": { "type": "object" } } }, "OperationalLogRecord": { "type": "object", "required": ["id", "observedAt", "level", "target", "sourceKind", "sourceId", "component", "surface", "service", "fields", "spans", "spansTruncated"], "properties": { "id": { "type": "string", "format": "uuid" }, "observedAt": { "type": "string", "format": "date-time" }, "level": { "type": "string", "enum": ["TRACE", "DEBUG", "INFO", "WARN", "ERROR"] }, "target": { "type": "string" }, "sourceKind": { "$ref": "#/components/schemas/SiteBrainSourceKind" }, "sourceId": { "type": "string" }, "component": { "type": "string" }, "surface": { "type": "string" }, "service": { "type": "string" }, "instance": { "type": "string", "nullable": true }, "releaseSha": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "fields": { "type": "object", "additionalProperties": { "type": "string" } }, "spans": { "type": "array", "items": { "type": "object" } }, "spansTruncated": { "type": "boolean" } } }, "OperationalLogsPublication": { "type": "object", "required": ["generatedAt", "retention", "page", "logs"], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "retention": { "type": "object" }, "page": { "type": "object" }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/OperationalLogRecord" } } } }, "AdminClientErrorRequest": { "type": "object", "required": ["message", "extensionId", "moduleId", "sectionId", "qualifiedSectionId", "pluginVersion"], "properties": { "message": { "type": "string", "maxLength": 2048 }, "stack": { "type": "string", "nullable": true, "maxLength": 8192 }, "componentStack": { "type": "string", "nullable": true, "maxLength": 8192 }, "kind": { "type": "string", "enum": ["error", "unhandledrejection"], "default": "error" }, "surface": { "type": "string", "enum": ["admin_section", "admin_runtime"], "default": "admin_section" }, "extensionId": { "type": "string" }, "moduleId": { "type": "string" }, "sectionId": { "type": "string" }, "qualifiedSectionId": { "type": "string" }, "pluginVersion": { "type": "string" }, "packageEntrypoint": { "type": "string", "nullable": true }, "routePath": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OkResponse": { "type": "object", "required": ["ok"], "properties": { "ok": { "type": "boolean", "enum": [true] } } }, "ErrorResponse": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Stable machine-readable error code" } } } }, "responses": { "BadRequest": { "description": "Invalid request (validation error, breaking schema change, contract failure, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Insufficient permissions for the requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Site not configured or collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Requested state or pinned contract conflicts with the current server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PayloadTooLarge": { "description": "Uploaded request or artifact exceeds the documented limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "The applicable authenticated or anonymous rate/concurrency quota is exhausted", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Suggested delay before attempting another submission, in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServiceUnavailable": { "description": "Required storage, admission, sandbox, or external service infrastructure is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalError": { "description": "Internal server error (database, I/O, or unexpected failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }