{ "openapi": "3.1.0", "info": { "title": "Backbuild API", "version": "1.0.0", "summary": "REST API for the Backbuild platform (api.backbuild.ai).", "description": "The complete REST API for Backbuild — the SaaS-building platform. Every endpoint returns a uniform JSON envelope: successful responses set `success: true` with the payload under `data`; failed responses set `success: false` with a machine-readable `error.code` (drawn from the shared `ErrorCode` vocabulary) and a human-readable `error.message`. List endpoints additionally return a `pagination` object. The request/response shapes documented here are mirrored by hand from the authoritative Zod schemas in `packages/backbuild-api/src/routes/**` and verified against the route handlers; see `openapi/README.md` for the source-of-truth and regeneration conventions. This document is assembled from per-domain fragments under `openapi/paths/` by `openapi/build.mjs`.", "contact": { "name": "Backbuild Platform Team", "url": "https://backbuild.ai" }, "license": { "name": "Proprietary — Gable Digital Solutions, Inc.", "identifier": "LicenseRef-GDS-Proprietary" } }, "servers": [ { "url": "https://api.dev.backbuild.ai", "description": "Development" }, { "url": "https://api.staging.backbuild.ai", "description": "Staging" }, { "url": "https://api.backbuild.ai", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Admin & Security", "x-slug": "admin-security", "description": "Organization security, access control, and administration: the security overview, audit events and alerts, data-subject-access requests, consent and privacy controls, role-based access control (roles, permissions, policies, departments, and groups), alert rules, and the project-management surface (specs, tasks, categories, and phases)." }, { "name": "AI Assistant", "x-slug": "ai-assistant", "description": "Manage AI assistant sessions, conversations, messages, cost tracking, multi-environment access matrices, sharing, AI model and provider configuration, finite-state-machine skills, multi-agent engine sessions, global system prompts, and the vision-verdict endpoint." }, { "name": "AI Testing, Search & Indexing", "x-slug": "search-indexing", "description": "Semantic/vector search over indexed documents, natural-language and hybrid (dense + ColBERT) retrieval, the AI test center (scenarios/personalities/test-data assets + runs), vector-index benchmarking, content-indexing status, and the in-app training & courseware platform." }, { "name": "Authentication", "x-slug": "authentication", "description": "Account registration, login, OAuth, password reset, token refresh, session lifecycle, MFA, and OAuth device-authorization for CLI/MCP clients." }, { "name": "Prove, Science & Studio", "x-slug": "prove-science-studio", "description": "Solver-DAG operations and theorem authoring, proof browser and artifact graph, kernel-run logs, submission pipeline, and webhook delivery audit for Backbuild Prove." }, { "name": "Billing & Subscriptions", "x-slug": "billing", "description": "Manage subscriptions, invoices, payment methods, checkout sessions, credit packs, pricing plans, API keys, Stripe Connect profiles, and academic verification flows for Backbuild and Backbuild Science." }, { "name": "Communications & Productivity", "x-slug": "communications", "description": "Mailbox, messaging, domain management, calendar, scheduling, and email-list management for Backbuild organizations." }, { "name": "Containers & Virtual Workers", "x-slug": "containers", "description": "Provision and manage multi-cloud AI-agent containers, Virtual Workers, terminal sessions, sandbox environments, and the code-API tool-bridge used by in-container agents to act on behalf of the authenticated user." }, { "name": "Files & Documents", "description": "File-bridge relay (WebSocket), BBProve confined source read/write, document library management, BB Docs collaborative editor, document comments and shares, resource versioning, and Science artifact promotion." }, { "name": "Organizations & Users", "x-slug": "organizations", "description": "Org-scoped administrative surfaces: per-key settings toggles, custom-domain lifecycle, control policies, URL-slug availability, visibility rules, bootstrap context, CCPA consumer-privacy rights, and legal-agreement signing." }, { "name": "Projects, Entities & Data Model", "x-slug": "entities", "description": "Manage project CI/CD pipelines, logical environments, project templates, entities and entity types, entity media, entity relationships and relationship types, entity permission grants, and saved views." }, { "name": "Projects", "x-slug": "projects", "description": "Create and manage projects — the primary workspace unit that groups entities, files, tasks, and views within an organization. The organization is taken from the authenticated session; callers never pass `org_id`. Identifiers and timestamps are assigned by the platform." }, { "name": "Releases & Automation", "x-slug": "releases-automation", "description": "Manage SaaS package release lifecycle, desktop distribution, container deployments, feature flags, campaigns, automation rules, time triggers, workflows, and change management." }, { "name": "SaaS Builder", "x-slug": "saas-builder", "description": "Create and publish SaaS packages — define pricing plans, branding, custom domains, marketing pages, seed data, screen definitions, app configs, feature flags, AI model overrides, data bundles, promotions, connector configs, and integrations for packages built on the Backbuild platform." }, { "name": "Sheets, Slides & Collaboration", "x-slug": "sheets-slides-collaboration", "description": "BB Sheets (spreadsheets) with cell comments, BB Slides decks, the collaboration and realtime Yjs WebSocket transports, and offline sync." }, { "name": "SSO & SCIM", "x-slug": "sso-scim", "description": "Enterprise SAML 2.0 / OIDC single sign-on, the authenticated SSO config admin surface, and SCIM 2.0 user provisioning." } ], "paths": { "/v1/alert-rules": { "get": { "operationId": "listAlertRules", "summary": "List alert rules for the authenticated user's organization", "description": "Returns all alert rules associated with the authenticated user's active organization. Standard bearer-token authentication.", "tags": [ "Admin & Security" ], "responses": { "200": { "description": "Array of alert rule records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Admin_AlertRule" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createAlertRule", "summary": "Create an alert rule", "description": "Creates a new alert rule in the authenticated user's active organization. Standard bearer-token authentication.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Admin_AlertRuleCreateRequest" } } } }, "responses": { "201": { "description": "Created alert rule.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Admin_AlertRule" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/alert-rules/{alertRuleId}": { "put": { "operationId": "updateAlertRule", "summary": "Update an alert rule (not yet implemented)", "description": "This endpoint is not yet implemented and always returns `501 NOT_IMPLEMENTED`.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "alertRuleId", "in": "path", "required": true, "description": "Alert rule identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "501": { "description": "`NOT_IMPLEMENTED` — update is not yet available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "deleteAlertRule", "summary": "Delete an alert rule (not yet implemented)", "description": "This endpoint is not yet implemented and always returns `501 NOT_IMPLEMENTED`.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "alertRuleId", "in": "path", "required": true, "description": "Alert rule identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "501": { "description": "`NOT_IMPLEMENTED` — delete is not yet available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/projects/{projectId}/specs": { "get": { "operationId": "backbuildListSpecs", "summary": "List specs for a project", "description": "Returns all specification documents for the given project. Requires `project.view` permission on the project.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Array of spec records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backbuild_Spec" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "backbuildCreateSpec", "summary": "Create a spec in a project", "description": "Creates a new specification document within a project. Requires `project.update` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "content": { "type": "string", "nullable": true } } } } } }, "responses": { "201": { "description": "Created spec record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backbuild_Spec" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/specs/{specId}": { "get": { "operationId": "backbuildGetSpec", "summary": "Get a spec", "description": "Returns a single specification document. Requires `project.view` permission on the parent project.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "specId", "in": "path", "required": true, "description": "Specification identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Spec record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backbuild_Spec" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "backbuildUpdateSpec", "summary": "Update a spec", "description": "Updates a specification document. Requires `project.update` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "content": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Updated spec record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backbuild_Spec" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "backbuildDeleteSpec", "summary": "Delete a spec", "description": "Permanently deletes a specification document and all its tasks. Requires `project.delete` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Spec deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/specs/{specId}/tasks": { "get": { "operationId": "backbuildListSpecTasks", "summary": "List tasks in a spec", "description": "Returns all tasks belonging to a specification. Requires `project.view` permission on the parent project.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Array of task records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backbuild_Task" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/tasks/{taskId}": { "get": { "operationId": "backbuildGetTask", "summary": "Get a task", "description": "Returns a single task record. Requires `project.view` permission on the parent project.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backbuild_Task" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "backbuildUpdateTask", "summary": "Update a task", "description": "Updates a task's fields. Requires `project.update` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 1000 }, "status": { "type": "string", "maxLength": 100 }, "phase": { "type": "string", "maxLength": 100, "nullable": true }, "category": { "type": "string", "maxLength": 100, "nullable": true } } } } } }, "responses": { "200": { "description": "Updated task record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backbuild_Task" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "backbuildDeleteTask", "summary": "Delete a task", "description": "Permanently deletes a task and its activity log. Requires `project.delete` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/tasks/{taskId}/activity": { "get": { "operationId": "backbuildListTaskActivity", "summary": "List task activity log", "description": "Returns the ordered activity log for a task (status changes, assignments, comments). Requires `project.view` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Activity log entries.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backbuild_TaskActivity" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/tasks": { "get": { "operationId": "backbuildListTasks", "summary": "List tasks for a project", "description": "Returns tasks for the given project, with optional filters. Requires `project.view` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "spec_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "assignee_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Array of task records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backbuild_Task" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "backbuildCreateTask", "summary": "Create a task in a project", "description": "Creates a new task in the project. Requires `project.update` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": { "type": "string", "maxLength": 65536 }, "spec_id": { "type": "string", "format": "uuid" }, "assignee_id": { "type": "string", "format": "uuid" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "depends_on": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "201": { "description": "Created task.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backbuild_Task" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/task-statuses": { "post": { "operationId": "backbuildCreateTaskStatus", "summary": "Create a task status for a project", "description": "Creates a new task status definition. Requires `project.update` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "key" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$", "description": "Unique status key. Must start with a lowercase letter and contain only lowercase letters, digits, and underscores." }, "color": { "type": "string", "maxLength": 32, "pattern": "^#[0-9a-fA-F]{6}$" }, "sort_order": { "type": "integer" } } } } } }, "responses": { "201": { "description": "Created task status.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backbuild_TaskStatus" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "backbuildListTaskStatuses", "summary": "List task statuses for a project", "description": "Returns the ordered list of task status definitions for a project. Requires `project.view` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Task status list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backbuild_TaskStatus" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/categories": { "post": { "operationId": "backbuildCreateCategory", "summary": "Create a category for a project", "description": "Creates a new category. Requires `project.update` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 4096 }, "parent_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Created category.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backbuild_Category" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "backbuildListCategories", "summary": "List task/spec categories for a project", "description": "Returns the list of category definitions for a project. Requires `project.view` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Category list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backbuild_Category" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/phases": { "post": { "operationId": "backbuildCreatePhase", "summary": "Create a phase for a project", "description": "Creates a new phase definition. Requires `project.update` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 4096 }, "sort_order": { "type": "integer" } } } } } }, "responses": { "201": { "description": "Created phase.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backbuild_Phase" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "backbuildListPhases", "summary": "List project phases", "description": "Returns the ordered list of phase definitions for a project. Requires `project.view` permission.", "tags": [ "Admin & Security" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Phase list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backbuild_Phase" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/assistant/ws": { "get": { "operationId": "aiCoreAssistantWsUpgrade", "summary": "WebSocket upgrade for the AI assistant Durable Object", "description": "Upgrades an HTTP connection to a WebSocket session routed to the per-user AssistantDO. The caller must pass a valid, unexpired session access token in the `token` query parameter (the WebSocket protocol does not support custom headers during upgrade). The token is validated (signature, expiry, token-version revocation) before the connection is forwarded. Feature-flag gating on AI operations is enforced inside the Durable Object on each prompt submission, not at upgrade time, so conversation history and presence are always available once connected.", "tags": [ "AI Assistant" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "Valid session access token (JWT). Required because the WebSocket upgrade cannot carry an Authorization header. Token must be unexpired and must pass revocation check.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "101": { "description": "Switching Protocols — WebSocket connection established to the AssistantDO." }, "400": { "description": "`VALIDATION_ERROR` — `Upgrade: websocket` header missing, or `token` query parameter absent or empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_TOKEN_EXPIRED` — token is expired. `AUTH_TOKEN_INVALID` — token signature invalid, claims missing, or the token has been revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "426": { "description": "`VALIDATION_ERROR` — `Upgrade: websocket` header missing (HTTP 426 Upgrade Required variant emitted by the handler).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/assistant/conversations": { "get": { "operationId": "aiCoreAssistantListConversations", "summary": "List assistant conversations (assistant mount)", "description": "Returns the paginated list of conversations for the authenticated user in their current organization. This endpoint is served from the `/v1/assistant` mount and is an alias for the conversations accessible via the AssistantDO. The canonical conversation CRUD lives under `/v1/conversations`.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of conversations to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of conversations to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of conversations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_ConversationSummary" } } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` — a query parameter has an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/assistant/conversations/{id}": { "get": { "operationId": "aiCoreAssistantGetConversation", "summary": "Get conversation history (assistant mount)", "description": "Returns the full conversation record, including messages, for the given conversation id. A conversation that does not exist or belongs to a different tenant returns `404 NOT_FOUND` (anti-enumeration — indistinguishable from missing).", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The conversation record with its message history.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AiCore_ConversationDetail" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — the supplied id is not a valid UUIDv7.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — the conversation does not exist or is not visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations": { "get": { "operationId": "aiCoreListConversations", "summary": "List conversations", "description": "Returns a paginated list of conversations in the caller's organization, filtered by optional criteria. Results are scoped to the caller's organization and visible conversations via Row-Level Security.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Filter by project (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "task_id", "in": "query", "required": false, "description": "Filter by task (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "context_type", "in": "query", "required": false, "description": "Filter by conversation context type.", "schema": { "type": "string", "enum": [ "project", "task", "assistant", "general" ] } }, { "name": "is_archived", "in": "query", "required": false, "description": "Filter by archived state (`true` or `false`).", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "search", "in": "query", "required": false, "description": "Full-text search term (max 200 chars).", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of conversations to return (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of conversations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_ConversationSummary" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a query parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "aiCoreCreateConversation", "summary": "Create a conversation", "description": "Creates a new conversation in the caller's organization, optionally associated with a project or task. Returns the created conversation record with a platform-assigned id.", "tags": [ "AI Assistant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_ConversationCreateRequest" } } } }, "responses": { "201": { "description": "Conversation created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AiCore_ConversationDetail" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/{id}": { "get": { "operationId": "aiCoreGetConversation", "summary": "Get a conversation", "description": "Returns a single conversation by id. A conversation that does not exist or belongs to another tenant returns `404 NOT_FOUND`.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The conversation record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AiCore_ConversationDetail" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — the id is not a valid UUIDv7.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "aiCoreUpdateConversation", "summary": "Update a conversation", "description": "Updates a conversation's title, archive state, or metadata. At least one field is required. Returns the updated conversation.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_ConversationUpdateRequest" } } } }, "responses": { "200": { "description": "The updated conversation record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AiCore_ConversationDetail" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "aiCoreDeleteConversation", "summary": "Delete a conversation", "description": "Deletes a conversation and its associated data. Returns `{ deleted: true }` on success.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The conversation was deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/{conversationId}/messages": { "get": { "operationId": "aiCoreListConversationMessages", "summary": "List conversation messages", "description": "Returns the paginated messages for a conversation. Uses page-based pagination (page/page_size). Rejects unknown query keys with `400 VALIDATION_ERROR`.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (1–100 000, default 1).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "description": "Messages per page (1–500, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "List of messages and pagination metadata.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_ConversationMessage" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/{conversationId}/messages/{messageId}/attachments": { "post": { "operationId": "aiCoreCreateMessageAttachment", "summary": "Add a file attachment to a message", "description": "Records a file attachment on an existing conversation message. The attachment is identified by the caller-supplied `file_url` (e.g., an R2 pre-signed URL obtained before this call). Org-scoped IDOR protection is enforced by the stored procedure.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "messageId", "in": "path", "required": true, "description": "Message identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_AttachmentCreateRequest" } } } }, "responses": { "201": { "description": "Attachment record created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "attachment": { "$ref": "#/components/schemas/AiCore_Attachment" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `INVALID_JSON` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/{id}/costs": { "post": { "operationId": "aiCoreRecordConversationCost", "summary": "Record an AI cost entry for a conversation", "description": "Persists a per-message (or conversation-level) AI cost record: model name, input/output token counts, and USD cost. Used by the AI/conversation runtime to maintain per-org billing ledger entries. The calling user and organization are derived from the session context (RLS). The stored procedure verifies the conversation exists and the caller has the `conversation.create` permission.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_ConversationCostCreateRequest" } } } }, "responses": { "201": { "description": "Cost entry recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "cost": { "$ref": "#/components/schemas/AiCore_ConversationCost" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `INVALID_JSON` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/artifacts/{id}": { "patch": { "operationId": "aiCoreUpdateConversationArtifact", "summary": "Update a conversation artifact", "description": "Updates metadata fields on an existing conversation artifact (file_name, r2_key, mime_type, file_size, checksum_sha256, metadata). At least one field must be supplied. Org-scoped IDOR protection is enforced by the stored procedure. Unknown body keys are rejected with `400 VALIDATION_ERROR`.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Artifact identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_ArtifactUpdateRequest" } } } }, "responses": { "200": { "description": "The updated artifact record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "artifact": { "$ref": "#/components/schemas/AiCore_Artifact" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `INVALID_JSON` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — a unique constraint was violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/{id}/env-matrix": { "get": { "operationId": "aiCoreGetConversationEnvMatrix", "summary": "Get AI session environment matrix", "description": "Returns the per-session environment access matrix for the conversation — the list of environments the AI assistant is permitted to read from or write to. Authorization is enforced inside the stored procedure based on the caller's own env access.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The environment matrix for the conversation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_EnvMatrix" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "aiCoreSetConversationEnvMatrix", "summary": "Set AI session environment matrix", "description": "Full-replace of the per-session environment access matrix. Each entry specifies an environment and its read/write permissions. An empty `matrix` array clears the matrix (reverts to home-env default). The stored procedure enforces that every requested env_id is accessible to the caller — inaccessible or duplicate entries are rejected. Unknown body keys are rejected with `400 VALIDATION_ERROR`.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_EnvMatrixSetRequest" } } } }, "responses": { "200": { "description": "The updated environment matrix.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_EnvMatrix" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `INVALID_JSON` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/{id}/env-matrix/read": { "post": { "operationId": "aiCoreReadAcrossEnvs", "summary": "Multi-environment read for AI session", "description": "Executes a read across exactly the environments in the conversation's `can_read` matrix and returns merged, environment-labeled results. Only environments the caller can access and that the matrix grants read permission to are queried. Unknown query keys are rejected with `400 VALIDATION_ERROR`.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Optional per-environment row cap (1–2000).", "schema": { "type": "integer", "minimum": 1, "maximum": 2000 } } ], "responses": { "200": { "description": "Merged multi-environment read result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/{id}/shares": { "post": { "operationId": "aiCoreCreateConversationShare", "summary": "Create a conversation share", "description": "Creates a sharing grant on a conversation. Only the conversation creator or a super-admin may manage shares. Public sharing additionally requires an admin/owner role and the org's `conversation_public_sharing_allowed` setting. Unknown body keys are rejected at 400.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_ShareCreateRequest" } } } }, "responses": { "201": { "description": "Share created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "share": { "$ref": "#/components/schemas/AiCore_Share" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `INVALID_JSON` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — a duplicate share already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "aiCoreListConversationShares", "summary": "List conversation shares", "description": "Returns the active (and optionally revoked) sharing grants for a conversation. `include_revoked=true` surfaces historical revoked grants for audit purposes. Unknown query keys are rejected at 400.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_revoked", "in": "query", "required": false, "description": "Include revoked shares in the response.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "List of share grants.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "shares": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_Share" } } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/{id}/shares/{shareId}": { "delete": { "operationId": "aiCoreRevokeConversationShare", "summary": "Revoke a conversation share", "description": "Revokes a sharing grant on a conversation.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "shareId", "in": "path", "required": true, "description": "Share grant identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The share was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/artifacts/{id}/shares": { "post": { "operationId": "aiCoreCreateArtifactShare", "summary": "Create an artifact share", "description": "Creates a sharing grant on a conversation artifact. The artifact creator, the parent-conversation creator, or a super-admin may manage artifact shares. Public sharing requires admin/owner role and the org's `conversation_public_sharing_allowed` setting.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Artifact identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_ShareCreateRequest" } } } }, "responses": { "201": { "description": "Artifact share created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "share": { "$ref": "#/components/schemas/AiCore_Share" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `INVALID_JSON` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "aiCoreListArtifactShares", "summary": "List artifact shares", "description": "Returns the sharing grants on a conversation artifact. `include_revoked=true` includes revoked grants for audit purposes.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Artifact identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_revoked", "in": "query", "required": false, "description": "Include revoked shares (`true` or `false`).", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "List of artifact share grants.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "shares": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_Share" } } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/conversations/artifacts/{id}/shares/{shareId}": { "delete": { "operationId": "aiCoreRevokeArtifactShare", "summary": "Revoke an artifact share", "description": "Revokes a sharing grant on a conversation artifact.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Artifact identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "shareId", "in": "path", "required": true, "description": "Share grant identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The artifact share was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-models/available": { "get": { "operationId": "aiCoreListAvailableAiModels", "summary": "List available AI models for the org", "description": "Returns the paginated set of AI models available to the caller's organization — both the shared relational catalog and any org-specific overrides. `supports_voice=true` filters to voice-capable models only.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number (1–100 000, default 1).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "description": "Models per page (1–500, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "supports_voice", "in": "query", "required": false, "description": "Filter to voice-capable models only.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Paginated list of available AI models (system catalog merged with org overrides).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_AvailableAiModel" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-models/system": { "get": { "operationId": "aiCoreGetSystemAiModels", "summary": "List system AI models with org override state", "description": "Returns the paginated list of system AI models along with each model's enabled/disabled state for the caller's organization.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "description": "Models per page (max 200, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Paginated list of system AI models with per-org enabled state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_SystemAiModelWithOverride" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "aiCoreSetSystemAiModelOverrides", "summary": "Batch-set system AI model enabled overrides", "description": "Full-replace of system model enabled/disabled overrides (max 200 entries). Requires super-admin role in the platform root organization.", "tags": [ "AI Assistant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_SystemModelToggleRequest" } } } }, "responses": { "200": { "description": "Updated system model override result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-models/system/override": { "post": { "operationId": "aiCoreCreateSystemModelOverride", "summary": "Create (upsert) a system model override", "description": "Upserts a single enabled/disabled override for a system model. Requires super-admin role in the platform root organization.", "tags": [ "AI Assistant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_SystemModelOverrideItem" } } } }, "responses": { "200": { "description": "Upserted override.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_SystemModelOverrideItem" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "aiCoreUpsertSystemModelOverride", "summary": "Upsert a system model override", "description": "Upserts a single enabled/disabled override for a system model. Semantically equivalent to `POST /system/override`. Requires super-admin role in the platform root organization.", "tags": [ "AI Assistant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_SystemModelOverrideItem" } } } }, "responses": { "200": { "description": "Upserted override.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_SystemModelOverrideItem" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-models": { "get": { "operationId": "aiCoreListAiModels", "summary": "List org AI models", "description": "Returns a paginated list of org-level AI model catalog entries. Optionally filter by `provider_id` or `is_enabled`.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "description": "Models per page (max 200, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "provider_id", "in": "query", "required": false, "description": "Filter by provider (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "is_enabled", "in": "query", "required": false, "description": "Filter by enabled state.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Paginated list of org AI model catalog entries.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_OrgAiModel" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "aiCoreCreateAiModel", "summary": "Create an org AI model", "description": "Adds a new AI model to the org catalog. Cost/credit values are per-million-token.", "tags": [ "AI Assistant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_AiModelCreateRequest" } } } }, "responses": { "201": { "description": "AI model created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_OrgAiModel" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-models/{id}": { "put": { "operationId": "aiCoreUpdateAiModel", "summary": "Update an org AI model", "description": "Partial update of an org AI model. All fields are optional; only supplied fields are changed.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "AI model identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_AiModelUpdateRequest" } } } }, "responses": { "200": { "description": "Updated AI model.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_OrgAiModel" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "aiCoreDeleteAiModel", "summary": "Delete an org AI model", "description": "Deletes an org AI model catalog entry. Returns `204 No Content`.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "AI model identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "AI model deleted." }, "400": { "description": "`VALIDATION_ERROR` — invalid ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-model-config": { "get": { "operationId": "aiCoreGetAiModelConfig", "summary": "Get org AI model configuration", "description": "Returns the merged AI model catalog for the caller's org: relational catalog fused with JSONB-stored org overrides (org wins on collision). Requires admin or owner role.", "tags": [ "AI Assistant" ], "responses": { "200": { "description": "Merged AI model configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_AiModelConfig" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "aiCoreUpdateAiModelConfig", "summary": "Update org AI model configuration", "description": "Full-replace of the org AI model catalog (providers + models + default_model_id). Provider `cloudflare_secret_name` values must be org-scoped (prefix `org___`); cross-tenant references are rejected with `400 VALIDATION_ERROR`. Max 100 providers, 500 models. Requires admin or owner role.", "tags": [ "AI Assistant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_AiModelCatalogUpdateRequest" } } } }, "responses": { "200": { "description": "Updated AI model configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_AiModelConfig" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a field failed, or `cloudflare_secret_name` is not org-scoped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-providers": { "get": { "operationId": "aiCoreListAiProviders", "summary": "List AI providers", "description": "Returns a paginated list of org-level AI provider configurations. API keys are never included in responses.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "description": "Providers per page (max 200, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "is_enabled", "in": "query", "required": false, "description": "Filter by enabled state.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "List of AI provider records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_AiProvider" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "aiCoreCreateAiProvider", "summary": "Create an AI provider", "description": "Creates a new AI provider. The API key is stored encrypted and never returned. The `api_base_url` undergoes SSRF validation: HTTPS required, no private/RFC-1918 IPs, vendor hostname suffix pinning for known protocol types. Requires admin or owner role.", "tags": [ "AI Assistant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_AiProviderCreateRequest" } } } }, "responses": { "201": { "description": "AI provider created (no API key in response).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_AiProvider" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` / `INVALID_PARAMETER` (SSRF guard on `api_base_url`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — duplicate provider name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-providers/{id}": { "get": { "operationId": "aiCoreGetAiProvider", "summary": "Get an AI provider", "description": "Returns a single AI provider record. API key not included. Requires admin or owner role.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "AI provider identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "AI provider record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_AiProvider" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "aiCoreUpdateAiProvider", "summary": "Update an AI provider", "description": "Partial update of an AI provider. All fields are optional; only supplied fields are changed. Same SSRF guard on `api_base_url`. Pass `api_key: null` to clear the stored credential.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "AI provider identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_AiProviderUpdateRequest" } } } }, "responses": { "200": { "description": "Updated AI provider (API key omitted).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_AiProvider" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `VALIDATION_ERROR` / `INVALID_PARAMETER` (SSRF).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "aiCoreDeleteAiProvider", "summary": "Delete an AI provider", "description": "Deletes an AI provider and its encrypted API key. Returns `204 No Content`. Requires admin or owner role.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "AI provider identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "AI provider deleted." }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/engine/sessions": { "get": { "operationId": "aiCoreListEngineSessions", "summary": "List multi-agent engine sessions", "description": "Returns the paginated list of multi-agent engine sessions visible to the caller. Requires `project.view` permission. Optionally filter by status.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by session status.", "schema": { "type": "string", "enum": [ "running", "paused", "completed", "cancelled", "failed" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Max sessions to return (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of engine sessions. Cursor-based pagination — `has_more: true` indicates additional pages exist (use `offset` to advance).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_EngineSession" } }, "has_more": { "type": "boolean", "description": "True when additional sessions exist beyond this page." } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/engine/sessions/{id}/status": { "get": { "operationId": "aiCoreGetEngineSessionStatus", "summary": "Get engine session status", "description": "Returns the current status record for an engine session. Returns `404 SESSION_NOT_FOUND` when the session key does not exist in the engine store. Requires `project.view` permission.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Engine session identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Engine session status.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_EngineSessionStatus" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SESSION_NOT_FOUND` — no session with this id exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/engine/sessions/{id}/tasks": { "get": { "operationId": "aiCoreGetEngineSessionTasks", "summary": "Get tasks for an engine session", "description": "Returns the task list for an engine session. Requires `project.view` permission.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Engine session identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session task list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_EngineTask" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SESSION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/engine/sessions/{id}/agents": { "get": { "operationId": "aiCoreGetEngineSessionAgents", "summary": "Get agents for an engine session", "description": "Returns the agent list for an engine session. Requires `project.view` permission.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Engine session identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session agent list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_EngineAgent" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SESSION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/engine/sessions/{id}/pause": { "post": { "operationId": "aiCoreEngineSessionPause", "summary": "Pause an engine session", "description": "Signals the multi-agent engine to pause the specified session. Requires `project.update` permission. Returns `SESSION_NOT_FOUND` if the session key does not exist in the engine store.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Engine session identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session pause signal sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SESSION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/engine/sessions/{id}/resume": { "post": { "operationId": "aiCoreEngineSessionResume", "summary": "Resume an engine session", "description": "Signals the multi-agent engine to resume a paused session. Requires `project.update` permission.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Engine session identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session resume signal sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SESSION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/engine/sessions/{id}/cancel": { "post": { "operationId": "aiCoreEngineSessionCancel", "summary": "Cancel an engine session", "description": "Signals the multi-agent engine to cancel the specified session. Requires `project.update` permission.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Engine session identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session cancel signal sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SESSION_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/skills/policies": { "get": { "operationId": "aiCoreListSkillPolicies", "summary": "List skill visibility policies", "description": "Returns the list of visibility policies available for use with skills in the caller's organization.", "tags": [ "AI Assistant" ], "responses": { "200": { "description": "List of skill visibility policies.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_SkillPolicy" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/skills/workspace": { "get": { "operationId": "aiCoreGetSkillWorkspace", "summary": "Get skill workspace plan entitlements", "description": "Returns the plan-scoped AI model entitlements for the skill editor UI — the list of models available to this org's active pricing plan, along with full plan entitlement details (credits, storage, capabilities).", "tags": [ "AI Assistant" ], "responses": { "200": { "description": "Skill workspace plan entitlements.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "model_options": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_SkillModelOption" }, "description": "AI models available to this org under the active pricing plan." }, "plan_entitlements": { "oneOf": [ { "$ref": "#/components/schemas/AiCore_SkillPlanEntitlements" }, { "type": "null" } ], "description": "Full plan entitlement record, or null if no active plan subscription is found." } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/skills": { "get": { "operationId": "aiCoreListSkills", "summary": "List skills", "description": "Returns the list of skills in the caller's organization. Results are filtered to skills the caller can access via visibility policies (admins/super-admins see all). Supports search, type filter, and offset pagination.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "skill_type", "in": "query", "required": false, "description": "Filter by skill type.", "schema": { "type": "string", "enum": [ "prompt", "chain", "agent", "composite" ] } }, { "name": "is_enabled", "in": "query", "required": false, "description": "Filter by enabled state ('true' or 'false').", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "search", "in": "query", "required": false, "description": "Search filter applied to skill name, description, status, and overall prompt (case-insensitive).", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Max skills to return (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of skills.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_Skill" } }, "total_count": { "type": "integer", "description": "Total number of skills matching the filter (before offset/limit)." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "aiCoreCreateSkill", "summary": "Create a skill", "description": "Creates a new FSM-based skill in the org. Accepts an optional FSM states array (max 100) and transitions array (max 300). Unknown body keys are rejected (`.strict()`). Returns `409 DUPLICATE` if a skill with the same name already exists. Requires appropriate org permission.", "tags": [ "AI Assistant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_SkillCreateRequest" } } } }, "responses": { "201": { "description": "Skill created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_Skill" } } } ] } } } }, "400": { "description": "`INVALID_JSON` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`DUPLICATE` — a skill with the same name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/skills/{id}": { "get": { "operationId": "aiCoreGetSkill", "summary": "Get a skill", "description": "Returns a single skill by id.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Skill record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_Skill" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "aiCoreUpdateSkill", "summary": "Update a skill", "description": "Partial update of a skill — all fields are optional. Unknown body keys are rejected (`.strict()`). Returns `400 INVALID_ID_FORMAT` when the path `id` is not a valid UUID. Returns `404 NOT_FOUND` when the skill does not exist. Returns `409 CONFLICT` on name collision.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_SkillUpdateRequest" } } } }, "responses": { "200": { "description": "Updated skill.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_Skill" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `INVALID_JSON` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`DUPLICATE` / `CONFLICT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "aiCoreDeleteSkill", "summary": "Delete a skill", "description": "Deletes a skill and its FSM configuration.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Skill deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/skills/{id}/publish": { "post": { "operationId": "aiCorePublishSkill", "summary": "Publish a skill to live stage", "description": "Snapshots the current test-stage FSM and publishes it to the live stage. Accepts an optional `version` number; defaults to the skill's current version. Returns `400 INVALID_ID_FORMAT` if the path `id` is not a valid UUID. Returns `404 NOT_FOUND` if the skill does not exist.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_SkillPublishRequest" } } } }, "responses": { "200": { "description": "Skill published.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_Skill" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/skills/{id}/requests": { "post": { "operationId": "aiCoreCreateSkillFeatureRequest", "summary": "Submit a skill capability feature request", "description": "Creates a capability/feature request for a skill. Used to record user-requested enhancements against a specific skill and stage (test or live). Returns `400 INVALID_ID_FORMAT` if the path `id` is not a valid UUID. Returns `404 NOT_FOUND` if the skill does not exist.", "tags": [ "AI Assistant" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Skill identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_SkillFeatureRequestCreate" } } } }, "responses": { "201": { "description": "Feature request created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiCore_SkillFeatureRequest" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` / `INVALID_JSON` / `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/vision/verdict": { "post": { "operationId": "aiCoreVisionVerdict", "summary": "AI vision content verdict", "description": "Submits a base64-encoded image to an AI vision model and returns a structured verdict (`yes`/`no`/`unclear`/`refused`). Useful for content moderation, verification workflows, and automated image triage.\n\nAuthentication: accepts either a session JWT (bearer) or an API key — whichever the caller holds. In both cases the caller must also hold the `vision` API key scope and the `vision.verify` permission in their organization. AI budget credit is reserved before the call and committed on success (rolled back on model or policy failure).\n\nRate limited to 60 requests per minute per user:org pair.", "tags": [ "AI Assistant" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCore_VisionVerdictRequest" } } } }, "responses": { "200": { "description": "Vision verdict produced.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AiCore_VisionVerdictResponse" } } } ] } } } }, "400": { "description": "`INVALID_JSON` / `VALIDATION_ERROR` — a required field is missing or out of bounds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `vision` API key scope or the `vision.verify` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`CONTENT_POLICY_VIOLATION` — the AI model refused to process the image due to a content policy violation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`INTERNAL_ERROR` — AI budget gate is temporarily unavailable. Retry after a brief delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/search/vector": { "post": { "operationId": "aiOpsSearchVector", "summary": "Dense vector search", "description": "Cosine-similarity search over indexed document chunks using a caller-supplied embedding. Results are nonce-wrapped for safe downstream LLM consumption. Per-user rate limit of 60 requests/minute.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_VectorSearchRequest" } } } }, "responses": { "200": { "description": "Wrapped search results.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiOps_WrappedSearchResults" } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body) or `VALIDATION_ERROR` (a field failed validation, e.g. `threshold` below the 0.55 floor, or a stored-procedure input fault surfaced with `details.spCode`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — more than 60 search requests in the rolling minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/search/hybrid": { "post": { "operationId": "aiOpsSearchHybrid", "summary": "Hybrid search (dense + optional ColBERT rerank)", "description": "Dense vector retrieval with optional ColBERT late-interaction reranking for higher precision. Results are nonce-wrapped. Per-user rate limit of 60 requests/minute.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_HybridSearchRequest" } } } }, "responses": { "200": { "description": "Wrapped search results.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiOps_WrappedSearchResults" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/search/fulltext": { "post": { "operationId": "aiOpsSearchFulltext", "summary": "Full-text search (retired)", "description": "This endpoint is not implemented. It always returns 501 with `Sunset` and `Link: rel=\"successor-version\"` headers pointing to `/v1/search/hybrid`. Use `/v1/search/hybrid` (dense + ColBERT) or `/v1/search/natural` (natural-language) instead.", "tags": [ "AI Testing, Search & Indexing" ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "`NOT_IMPLEMENTED` — the route is retired; migrate to `/v1/search/hybrid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/search/natural": { "post": { "operationId": "aiOpsSearchNatural", "summary": "Natural-language search", "description": "Embeds the supplied natural-language query server-side (Workers AI bge-large-en-v1.5) and runs hybrid retrieval. Counts against the daily embedding budget and a per-user 60/minute rate limit. Results are nonce-wrapped.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_NaturalSearchRequest" } } } }, "responses": { "200": { "description": "Wrapped search results, echoing the `query`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "query": { "type": "string" } } }, { "$ref": "#/components/schemas/AiOps_WrappedSearchResults" } ] } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — per-user rate limit or the daily embedding budget was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`INTERNAL_ERROR` — the embedding model produced no vector or another server fault.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`INTERNAL_ERROR` — the AI budget gate is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/benchmarks/generate": { "post": { "operationId": "aiOpsBenchmarkGenerate", "summary": "Generate a synthetic vector dataset", "description": "Generates a synthetic embedding dataset for benchmarking vector-index techniques. Requires the `benchmark.run` permission.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_GenerateDataRequest" } } } }, "responses": { "201": { "description": "The generated dataset record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "The created dataset (id + parameters)." } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — missing the `benchmark.run` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/benchmarks/run": { "post": { "operationId": "aiOpsBenchmarkRun", "summary": "Run a benchmark suite", "description": "Runs a benchmark suite against a generated dataset across one or more vector-index techniques. Requires the `benchmark.run` permission.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_RunSuiteRequest" } } } }, "responses": { "200": { "description": "The benchmark run result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — missing the `benchmark.run` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the dataset does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/benchmarks/results": { "get": { "operationId": "aiOpsBenchmarkResults", "summary": "List benchmark results", "description": "Lists benchmark results for the organization, optionally filtered by run or technique, with page/pageSize pagination.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "run_id", "in": "query", "required": false, "description": "Filter to a single benchmark run.", "schema": { "type": "string", "format": "uuid" } }, { "name": "technique", "in": "query", "required": false, "description": "Filter by index technique.", "schema": { "type": "string", "enum": [ "hnsw", "diskann", "vchordrq", "vchordg", "colbert_maxsim", "hybrid_dense_colbert" ] } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (1–200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Benchmark results.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/benchmarks/runs/{runId}/charts": { "get": { "operationId": "aiOpsBenchmarkCharts", "summary": "Get chart data for a benchmark run", "description": "Returns chart-ready data for a benchmark run for the chosen metric.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Benchmark run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "chart", "in": "query", "required": false, "description": "Which metric to chart (default `speed`).", "schema": { "type": "string", "enum": [ "speed", "latency", "size", "accuracy" ] } } ], "responses": { "200": { "description": "Chart data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (bad run id) or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/indexing/ws": { "get": { "operationId": "aiOpsIndexingWs", "summary": "Indexing status WebSocket", "description": "WebSocket upgrade that streams live content-indexing/embedding progress. The connection authenticates in-handler via the connection token; this is not a JSON endpoint.", "tags": [ "AI Testing, Search & Indexing" ], "security": [ { "oneTimeTicket": [] } ], "responses": { "101": { "description": "Switching Protocols — the WebSocket connection is established." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "426": { "description": "Upgrade Required — the request was not a WebSocket upgrade." } } } }, "/v1/ai-testing/workspace": { "get": { "operationId": "aiOpsTestingWorkspace", "summary": "Get the AI test workspace", "description": "Returns the caller's AI-testing workspace: scenarios, personality assets, and test-data assets (draft + live stages).", "tags": [ "AI Testing, Search & Indexing" ], "responses": { "200": { "description": "Workspace assets.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-testing/assets": { "post": { "operationId": "aiOpsTestingCreateAsset", "summary": "Create a test asset", "description": "Creates a scenario, personality, or test-data asset. Requires AI-testing author permission.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_AssetCreateRequest" } } } }, "responses": { "201": { "description": "The created asset.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — missing AI-testing author permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-testing/assets/{id}": { "put": { "operationId": "aiOpsTestingUpdateAsset", "summary": "Update a test asset", "description": "Updates a draft/live snapshot or metadata of a test asset. Requires AI-testing author permission.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_AssetUpdateRequest" } } } }, "responses": { "200": { "description": "The updated asset.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-testing/assets/{id}/publish": { "post": { "operationId": "aiOpsTestingPublishAsset", "summary": "Publish a test asset", "description": "Promotes a test asset's draft snapshot to its live stage. Requires AI-testing author permission.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Asset identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The published asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-testing/scenarios/{id}/run": { "post": { "operationId": "aiOpsTestingRunScenario", "summary": "Run a test scenario", "description": "Executes a single test scenario against the target assistant or skill at the chosen stage, returning the run result. Requires AI-testing author permission.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Scenario asset identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_RunScenarioRequest" } } } }, "responses": { "200": { "description": "The scenario run result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-testing/run-all": { "post": { "operationId": "aiOpsTestingRunAll", "summary": "Run all test scenarios", "description": "Runs every scenario in the workspace at the requested stage (draft, live, or mixed). Requires AI-testing author permission.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_RunAllRequest" } } } }, "responses": { "200": { "description": "The aggregate run result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ai-testing/results/{id}": { "get": { "operationId": "aiOpsTestingGetResult", "summary": "Get a test run result", "description": "Returns the stored result of a previous scenario or run-all execution.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Run result identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The run result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/entity-types/clone": { "post": { "operationId": "aiOpsTrainingCloneType", "summary": "Clone a training entity type", "description": "Clones a system or org training entity type into the organization, optionally renaming and adding fields. Requires the `entity_type.create` permission.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_CloneTypeRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `entity_type.create` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/courses": { "post": { "operationId": "aiOpsTrainingCreateCourse", "summary": "Create a course", "description": "Creates a training course bound to a project and a training entity type. Requires the `training.author` permission.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_CreateCourseRequest" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.author` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/courses/{courseId}": { "get": { "operationId": "aiOpsTrainingGetCourse", "summary": "Get a course tree", "description": "Returns the full course tree (chapters/lessons/steps). Answer keys are stripped for learners; authors/admins see them. Requires entitlement to the course.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "courseId", "in": "path", "required": true, "description": "Course identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "aiOpsTrainingUpdateCourse", "summary": "Update course metadata", "description": "Updates course metadata (title/description/locale/etc). At least one field required. Requires `training.author`.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "courseId", "in": "path", "required": true, "description": "Course identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_CourseUpdateRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.author` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "CONFLICT — the course cannot be updated in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/courses/{courseId}/publish": { "post": { "operationId": "aiOpsTrainingPublishCourse", "summary": "Publish a course", "description": "Publishes a course, optionally binding pricing/feature-flag/marketplace listing. Requires `training.author`.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "courseId", "in": "path", "required": true, "description": "Course identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_PublishCourseRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.author` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "CONFLICT — the course is in a state that cannot be published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/courses/{courseId}/archive": { "post": { "operationId": "aiOpsTrainingArchiveCourse", "summary": "Archive a course", "description": "Archives a course. Requires `training.author`.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "courseId", "in": "path", "required": true, "description": "Course identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.author` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "CONFLICT — the course is already archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/courses/{courseId}/unpublish": { "post": { "operationId": "aiOpsTrainingUnpublishCourse", "summary": "Unpublish a course", "description": "Reverts a published course to draft. Requires `training.author`.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "courseId", "in": "path", "required": true, "description": "Course identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.author` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "CONFLICT — the course cannot be unpublished in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/nodes": { "post": { "operationId": "aiOpsTrainingUpsertNode", "summary": "Upsert a course node", "description": "Creates or updates a chapter/lesson/step node in a course. Requires `training.author`.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_NodeUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.author` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/catalog": { "get": { "operationId": "aiOpsTrainingCatalog", "summary": "Get the course catalog", "description": "Returns the courses the caller is entitled to. Requires `training.learn`.", "tags": [ "AI Testing, Search & Indexing" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.learn` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/my": { "get": { "operationId": "aiOpsTrainingMyHub", "summary": "Get the learner hub", "description": "Returns the callers enrollments, progress, and assignments. Requires `training.learn`.", "tags": [ "AI Testing, Search & Indexing" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.learn` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/enrollments": { "post": { "operationId": "aiOpsTrainingEnroll", "summary": "Enroll in a course", "description": "Enrolls the caller (or, for assigners, another user) in a course. Requires `training.learn`.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_EnrollRequest" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.learn` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/progress": { "post": { "operationId": "aiOpsTrainingProgress", "summary": "Batch-update progress", "description": "Upserts progress for up to 500 nodes in an enrollment. Requires `training.learn`.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_ProgressBatchRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.learn` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/attempts": { "post": { "operationId": "aiOpsTrainingSubmitAttempt", "summary": "Submit a graded attempt", "description": "Submits an answer for grading (auto-graded, including HOL-kernel equation equivalence where applicable). Requires `training.learn`.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_AttemptRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.learn` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/certificates": { "get": { "operationId": "aiOpsTrainingListCertificates", "summary": "List certificates", "description": "Lists the callers certificates; admins see all org certificates. Requires `training.learn`.", "tags": [ "AI Testing, Search & Indexing" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.learn` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/certificates/revoke": { "post": { "operationId": "aiOpsTrainingRevokeCertificate", "summary": "Revoke a certificate", "description": "Revokes a certificate by enrollment id or serial. Requires `training.admin`.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_CertificateRevokeRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.admin` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/certificates/verify": { "get": { "operationId": "aiOpsTrainingVerifyCertificate", "summary": "Verify a certificate", "description": "Verifies a certificate by serial. Available to any authenticated user.", "tags": [ "AI Testing, Search & Indexing" ], "parameters": [ { "name": "serial", "in": "query", "required": true, "description": "Certificate serial to verify.", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/assign": { "post": { "operationId": "aiOpsTrainingAssign", "summary": "Bulk-assign learners", "description": "Assigns up to 1000 users to a course with an optional due date. Requires `training.assign`.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_AssignRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.assign` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/required": { "post": { "operationId": "aiOpsTrainingSetRequired", "summary": "Set required training", "description": "Upserts a required-training rule for an org/role/group/user scope with optional recurrence. Requires `training.assign`.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_RequiredSetRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.assign` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/my/transcript": { "get": { "operationId": "aiOpsTrainingTranscript", "summary": "Export own transcript", "description": "Exports the callers training transcript. Requires `training.learn`.", "tags": [ "AI Testing, Search & Indexing" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.learn` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/learners/erase": { "post": { "operationId": "aiOpsTrainingEraseLearner", "summary": "Erase learner training data", "description": "GDPR/FERPA erasure of a learners training data at the chosen scope. Requires `training.admin`.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_LearnerEraseRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.admin` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/training/attempts/grade": { "post": { "operationId": "aiOpsTrainingGradeAttempt", "summary": "Override grade / add feedback", "description": "Admin override of an attempt score or instructor feedback. Requires `training.admin`.", "tags": [ "AI Testing, Search & Indexing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOps_AttemptGradeRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "FORBIDDEN — missing the `training.admin` permission or not entitled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/lookup": { "post": { "operationId": "authLookup", "summary": "Look up account by email", "description": "Determines whether an email address is registered and whether passwordless (passkey) login is enabled for that account. Used by the login UI to decide which credential flow to present. Requires a valid Cloudflare Turnstile token.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_LookupRequest" } } } }, "responses": { "200": { "description": "Lookup result. `action` indicates the recommended login flow (`password`, `passkey`, `sso`, `register`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_LookupResponse" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/register": { "post": { "operationId": "authRegister", "summary": "Register a new account", "description": "Creates a new user account with email and password. Returns session tokens on success, or an `mfa_enrollment_required` flag when MFA enrollment is mandatory. Requires a Cloudflare Turnstile token. Password must meet complexity requirements (uppercase, lowercase, digit, special character) and must not appear in known breach databases.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_RegisterRequest" } } } }, "responses": { "200": { "description": "Registration succeeded. Returns session tokens, or `mfa_enrollment_required: true` when the org requires MFA enrollment before access is granted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_AuthResult" } } } } } }, "400": { "description": "Validation error or weak/breached password. Error codes: `VALIDATION_ERROR`, `BREACHED_PASSWORD`.", "$ref": "#/components/responses/ValidationError" }, "409": { "description": "Email already registered. Error code: `EMAIL_ALREADY_EXISTS`.", "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/initiate": { "post": { "operationId": "authInitiate", "summary": "Initiate email verification flow", "description": "Starts a passwordless registration flow by sending a verification code to the given email address. Returns a `flow_id` used in subsequent `/registration/validate` and `/complete-registration` calls. Requires a Cloudflare Turnstile token.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_InitiateRequest" } } } }, "responses": { "200": { "description": "Verification email sent. Returns `flow_id` and a user-facing message.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_InitiateResponse" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/registration/validate": { "post": { "operationId": "authRegistrationValidate", "summary": "Validate registration verification code", "description": "Validates the verification code for an in-progress registration flow without completing it. Used to give inline feedback before the user fills in the rest of the registration form.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_RegistrationValidateRequest" } } } }, "responses": { "200": { "description": "Code is valid for the given flow.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "validated": { "type": "boolean", "description": "Always `true` on success." } }, "required": [ "validated" ], "additionalProperties": false } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "410": { "description": "Flow expired or code is invalid. Error code: `NOT_FOUND` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/complete-registration": { "post": { "operationId": "authCompleteRegistration", "summary": "Complete email-verified registration", "description": "Completes a passwordless registration flow started by `/initiate`. Verifies the code, sets the password, creates the account, and returns session tokens. May return `mfa_enrollment_required` when the org mandates MFA before granting full access. Password must meet complexity requirements and must not appear in known breach databases. Requires a Cloudflare Turnstile token.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_CompleteRegistrationRequest" } } } }, "responses": { "200": { "description": "Registration complete. Returns session tokens or `mfa_enrollment_required: true`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_AuthResult" } } } } } }, "400": { "description": "Validation error, invalid/expired code, or breached password. Error codes: `VALIDATION_ERROR`, `BREACHED_PASSWORD`.", "$ref": "#/components/responses/ValidationError" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/login": { "post": { "operationId": "authLogin", "summary": "Log in with email and password", "description": "Authenticates a user with email and password. On success returns session tokens. If the account has MFA enabled, returns `mfa_required: true` and an `mfa_challenge_token` instead of session tokens. If the account must enroll MFA, returns `mfa_enrollment_required: true` and an `mfa_enrollment_token`. An optional `mfaDeviceToken` bypasses the interactive MFA challenge for a remembered device. Requires a Cloudflare Turnstile token.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_LoginRequest" } } } }, "responses": { "200": { "description": "Login result. One of: full session tokens, `mfa_required` with challenge token, or `mfa_enrollment_required` with enrollment token.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_AuthResult" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "description": "Invalid credentials or account locked. Error codes: `AUTH_INVALID_CREDENTIALS`, `AUTH_ACCOUNT_LOCKED`, `AUTH_EMAIL_NOT_VERIFIED`.", "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/refresh": { "post": { "operationId": "authRefresh", "summary": "Refresh session tokens", "description": "Exchanges a valid refresh token for a new access token / refresh token pair. The old refresh token is invalidated (rotation). Returns `AUTH_REFRESH_TOKEN_INVALID` if the token has been revoked, already rotated, or is expired.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_RefreshRequest" } } } }, "responses": { "200": { "description": "New token pair issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_TokenPair" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "description": "Refresh token invalid, expired, or revoked. Error codes: `AUTH_REFRESH_TOKEN_INVALID`, `TOKEN_REVOKED`, `SESSION_INVALID`.", "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/logout": { "post": { "operationId": "authLogout", "summary": "Log out current session", "description": "Revokes the current session's refresh token and invalidates the session. The access token remains technically valid until its short TTL expires but will fail on any endpoint that checks session state.", "tags": [ "Authentication" ], "responses": { "200": { "description": "Session revoked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/logout-all": { "post": { "operationId": "authLogoutAll", "summary": "Log out all sessions", "description": "Revokes all active sessions for the authenticated user across all devices.", "tags": [ "Authentication" ], "responses": { "200": { "description": "All sessions revoked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/switch-org": { "post": { "operationId": "authSwitchOrg", "summary": "Switch active organization", "description": "Issues new session tokens scoped to the specified organization. The caller must be a member of the target org.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_SwitchOrgRequest" } } } }, "responses": { "200": { "description": "New org-scoped token pair issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_TokenPair" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "User is not a member of the target organization. Error code: `ORG_MEMBERSHIP_REQUIRED`.", "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/switch-env": { "post": { "operationId": "authSwitchEnv", "summary": "Switch active environment", "description": "Issues new session tokens scoped to the specified environment within the current organization.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_SwitchEnvRequest" } } } }, "responses": { "200": { "description": "New env-scoped token pair issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_TokenPair" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/google-oauth": { "post": { "operationId": "authGoogleOAuth", "summary": "Authenticate with Google OAuth", "description": "Exchanges a Google authorization code for session tokens. Creates a new account if the email does not exist, or links/logs into an existing account. Returns `mfa_required`, `mfa_enrollment_required`, or `google_link_required` when further action is needed. An optional `mfaDeviceToken` (or array `mfaDeviceTokens` for multi-org) bypasses the MFA challenge for a remembered device.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_GoogleOAuthRequest" } } } }, "responses": { "200": { "description": "OAuth result. One of: full session tokens, `mfa_required`, `mfa_enrollment_required`, or `google_link_required` with a `linkToken`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_GoogleOAuthResult" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "description": "Google OAuth exchange failed. Error code: `AUTH_OAUTH_FAILED`.", "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/google-oauth/confirm-link": { "post": { "operationId": "authGoogleConfirmLink", "summary": "Confirm linking Google account to existing account", "description": "Confirms that the authenticated user consents to linking their existing Backbuild account to the Google identity identified by `linkToken` (received from `/google-oauth` when `google_link_required` is returned).", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_GoogleConfirmLinkRequest" } } } }, "responses": { "200": { "description": "Google account successfully linked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "linked": { "type": "boolean" }, "userId": { "type": "string", "format": "uuid" } }, "required": [ "linked", "userId" ], "additionalProperties": false } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/otp/create": { "post": { "operationId": "authOtpCreate", "summary": "Send a one-time password", "description": "Sends a one-time password (OTP) to the user's email for the specified purpose (`login`, `verify_email`, or `reset_password`). Rate-limited per email. Requires a Cloudflare Turnstile token.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OtpCreateRequest" } } } }, "responses": { "200": { "description": "OTP sent (or silently suppressed if the email does not exist, to prevent enumeration).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/otp/verify": { "post": { "operationId": "authOtpVerify", "summary": "Verify a one-time password", "description": "Verifies the OTP sent by `/otp/create` and, if valid, returns session tokens (for `login` purpose) or confirms email/password-reset eligibility (other purposes). Requires the caller's IP address via `CF-Connecting-IP`.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OtpVerifyRequest" } } } }, "responses": { "200": { "description": "OTP verified. Returns session tokens for `login` purpose.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_AuthResult" } } } } } }, "400": { "description": "Invalid OTP or expired. Error codes: `VALIDATION_ERROR`, `AUTH_INVALID_CREDENTIALS`.", "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/password/reset/request": { "post": { "operationId": "authPasswordResetRequest", "summary": "Request a password reset", "description": "Sends a password-reset code to the email address if it is registered. Always returns success to prevent email enumeration. Requires a Cloudflare Turnstile token.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_PasswordResetRequestBody" } } } }, "responses": { "200": { "description": "Reset email dispatched (or silently suppressed for unknown emails).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/password/reset": { "post": { "operationId": "authPasswordReset", "summary": "Reset password with code", "description": "Resets the user's password using the code sent to their email by `/password/reset/request`. The new password must meet complexity requirements and must not appear in known breach databases.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_PasswordResetBody" } } } }, "responses": { "200": { "description": "Password successfully reset.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } } } } }, "400": { "description": "Invalid/expired code, weak password, or breached password. Error codes: `VALIDATION_ERROR`, `BREACHED_PASSWORD`.", "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/password/change": { "post": { "operationId": "authPasswordChange", "summary": "Change password", "description": "Changes the authenticated user's password. For accounts with an existing password, `old_password` is required (omit for initial password set). Requires a recent MFA step-up. On success, revokes all other sessions.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_PasswordChangeRequest" } } } }, "responses": { "200": { "description": "Password changed. All other sessions revoked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "was_initial_set": { "type": "boolean", "description": "True if this was the first password set (no old password existed)." }, "sessions_revoked": { "type": "integer", "description": "Number of other sessions that were revoked." } }, "required": [ "was_initial_set", "sessions_revoked" ], "additionalProperties": false } } } } } }, "400": { "description": "Validation error or breached password. Error codes: `VALIDATION_ERROR`, `BREACHED_PASSWORD`.", "$ref": "#/components/responses/ValidationError" }, "401": { "description": "Old password incorrect or MFA step-up required. Error codes: `AUTH_INVALID_CREDENTIALS`, `MFA_STEPUP_REQUIRED`, `REAUTH_REQUIRED`.", "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/webauthn/assertion/options": { "post": { "operationId": "authWebauthnAssertionOptions", "summary": "Get WebAuthn assertion options for passkey login", "description": "Returns WebAuthn assertion (get) options for the primary passkey login flow. Returns an `assertion_nonce` that must be submitted with the credential in `/webauthn/assertion/verify`.", "tags": [ "Authentication" ], "security": [ {} ], "responses": { "200": { "description": "WebAuthn assertion options and nonce.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_WebauthnAssertionOptions" } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/webauthn/assertion/verify": { "post": { "operationId": "authWebauthnAssertionVerify", "summary": "Verify WebAuthn assertion for passkey login", "description": "Verifies a WebAuthn assertion credential against the stored passkey and the nonce issued by `/webauthn/assertion/options`. On success returns session tokens.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_WebauthnAssertionVerifyRequest" } } } }, "responses": { "200": { "description": "Passkey verified. Returns session tokens.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_TokenPair" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "description": "Assertion verification failed. Error code: `AUTH_INVALID_CREDENTIALS`.", "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/preferences/passkey-primary-override": { "post": { "operationId": "authPasskeyPrimaryOverride", "summary": "Override passkey-primary login preference", "description": "Sets the authenticated user's passkey-primary login preference to `inherit` (follow org policy), `force_on` (always prompt passkey first), or `force_off` (always show password form first).", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_PasskeyPrimaryOverrideRequest" } } } }, "responses": { "200": { "description": "Preference saved.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "override": { "type": "string", "enum": [ "inherit", "force_on", "force_off" ] } }, "required": [ "override" ], "additionalProperties": false } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/landing-hint": { "get": { "operationId": "authLandingHint", "summary": "Get login landing hint", "description": "Returns a hint for the login page based on the visitor's cookie and Origin/Referer headers. Used to detect returning users and determine whether the org has passwordless login enabled. Public endpoint; does not require authentication.", "tags": [ "Authentication" ], "security": [ {} ], "responses": { "200": { "description": "Landing hint for the login UI.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_LandingHint" } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/me": { "get": { "operationId": "authMe", "summary": "Get current user identity and first-paint data", "description": "Returns the authenticated user's full identity (profile, org, roles, permissions) together with first-paint bootstrap slices fetched in parallel. This is the primary session-bootstrap endpoint called on app load.", "tags": [ "Authentication" ], "responses": { "200": { "description": "User identity and bootstrap data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_MeResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/dev/grant-test-entitlements": { "post": { "operationId": "authDevGrantTestEntitlements", "summary": "Grant test entitlements (dev only)", "description": "Development-only endpoint that grants test plan entitlements to the authenticated user's organization. Returns `404 NOT_FOUND` in non-dev environments.", "tags": [ "Authentication" ], "responses": { "200": { "description": "Test entitlements granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/dev/purge-test-org": { "post": { "operationId": "authDevPurgeTestOrg", "summary": "Purge test organization (dev only)", "description": "Development-only endpoint that purges the test organization and optionally specific users. Returns `404 NOT_FOUND` in non-dev environments. The caller must be authenticated and the target org must be a test organization.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_DevPurgeTestOrgRequest" } } } }, "responses": { "200": { "description": "Test organization purged. Returns audit summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/device/authorize": { "post": { "operationId": "deviceAuthAuthorize", "summary": "Initiate device authorization flow", "description": "Starts the OAuth 2.0 device authorization flow (RFC 8628 adapted with PKCE). The client provides a PKCE code challenge and receives a device code, user code, and verification URI. The user visits the verification URI in a browser to authorize the device. **Note**: This endpoint returns a raw JSON object, not the standard Backbuild envelope.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_DeviceAuthorizeRequest" } } } }, "responses": { "200": { "description": "Device authorization initiated. Raw JSON response (no envelope wrapper).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_DeviceAuthorizeResponse" } } } }, "400": { "description": "Missing or invalid `redirect_uri`, `code_challenge`, or `code_challenge_method`. Raw JSON error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/device/complete": { "post": { "operationId": "deviceAuthComplete", "summary": "Approve device authorization (browser user)", "description": "Called by the authenticated browser user to approve a pending device authorization. The user enters the `user_code` displayed on the device. On success, the authorization code is minted and the device can exchange it for tokens.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_DeviceCompleteRequest" } } } }, "responses": { "200": { "description": "Authorization approved. Returns the authorization code and redirect URI for the device to use.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_DeviceCompleteResponse" } } } } } }, "400": { "description": "Invalid or expired user code. Error code: `VALIDATION_ERROR`, `NOT_FOUND`.", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/device/token": { "post": { "operationId": "deviceAuthToken", "summary": "Exchange device authorization code for tokens", "description": "Exchanges the authorization code from the device flow for an access token (and optionally a refresh token). The PKCE verifier must match the challenge submitted in `/device/authorize`. Supports `token_type=jwt` for a full JWT session or `token_type=api_key` (default) for a long-lived opaque API key. **Response format is RFC 6749 style** (`{access_token, token_type, expires_in?, refresh_token?}`), not the standard Backbuild envelope.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_DeviceTokenRequest" } } } }, "responses": { "200": { "description": "Token issued. RFC 6749 response format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_DeviceTokenResponse" } } } }, "400": { "description": "RFC 6749 error response. `error` values include `invalid_grant`, `invalid_request`, `invalid_client`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/methods": { "get": { "operationId": "mfaListMethods", "summary": "List enrolled MFA methods", "description": "Returns all MFA methods enrolled for the authenticated user. Accepts either a full session JWT or an MFA enrollment token (issued during login when MFA enrollment is required).", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of enrolled MFA methods.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "methods": { "type": "array", "items": { "$ref": "#/components/schemas/Authentication_MfaMethod" } } }, "required": [ "methods" ], "additionalProperties": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/totp/setup": { "post": { "operationId": "mfaTotpSetup", "summary": "Set up TOTP MFA method", "description": "Generates a TOTP secret and URI for enrollment. The returned `encryptedSecret` must be submitted along with the first TOTP code to `/totp/confirm` to complete enrollment. Accepts either a full session JWT or an MFA enrollment token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_TotpSetupRequest" } } } }, "responses": { "200": { "description": "TOTP setup initiated. Scan the URI with an authenticator app, then confirm with `/totp/confirm`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_TotpSetupResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "TOTP method already enrolled. Error code: `MFA_ALREADY_ENROLLED`.", "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/totp/confirm": { "post": { "operationId": "mfaTotpConfirm", "summary": "Confirm TOTP enrollment", "description": "Verifies the first TOTP code against the encrypted secret from `/totp/setup`, completing TOTP enrollment. Returns recovery codes on first enrollment. If this is the first MFA method, also returns a full session (completing login when enrollment was required). Accepts either a full session JWT or an MFA enrollment token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_TotpConfirmRequest" } } } }, "responses": { "200": { "description": "TOTP enrolled. `recoveryCodes` present if this is the first method enrolled.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_MfaEnrollResult" } } } } } }, "400": { "description": "Invalid TOTP code. Error code: `AUTH_MFA_INVALID`.", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/webauthn/register/options": { "post": { "operationId": "mfaWebauthnRegisterOptions", "summary": "Get WebAuthn registration options for MFA enrollment", "description": "Returns WebAuthn attestation (create) options and a `challenge_token` for enrolling a security key or platform authenticator as an MFA method. Accepts either a full session JWT or an MFA enrollment token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "WebAuthn registration options and challenge token.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_WebauthnChallengeOptions" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/webauthn/register/verify": { "post": { "operationId": "mfaWebauthnRegisterVerify", "summary": "Verify WebAuthn registration for MFA enrollment", "description": "Verifies the attestation response from the authenticator and stores the credential as an MFA method. Returns recovery codes on first enrollment. If this is the first MFA method and enrollment was required, also returns a full session. Accepts either a full session JWT or an MFA enrollment token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_WebauthnRegisterVerifyRequest" } } } }, "responses": { "200": { "description": "WebAuthn credential enrolled.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_MfaEnrollResult" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/email-otp/setup": { "post": { "operationId": "mfaEmailOtpSetup", "summary": "Set up email OTP MFA method", "description": "Enrolls the user's verified email address as an MFA method and sends a verification OTP. Returns recovery codes on first enrollment. Accepts either a full session JWT or an MFA enrollment token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Email OTP method enrolled.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_EmailOtpSetupResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Email OTP method already enrolled. Error code: `MFA_ALREADY_ENROLLED`.", "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/methods/{methodId}": { "delete": { "operationId": "mfaDeleteMethod", "summary": "Delete an MFA method", "description": "Removes an enrolled MFA method. When `force=true` is passed, requires a recent authentication and MFA step-up. Passing `force` without a recent step-up returns `MFA_STEPUP_REQUIRED`.", "tags": [ "Authentication" ], "parameters": [ { "name": "methodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the MFA method to delete." }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, requires a recent MFA step-up and deletes even the last method (fully disenrolling MFA)." } ], "responses": { "200": { "description": "Method deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_MfaDeleteMethodResponse" } } } } } }, "401": { "description": "Not authenticated or step-up required. Error codes: `AUTH_REQUIRED`, `MFA_STEPUP_REQUIRED`, `REAUTH_REQUIRED`.", "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "mfaRenameMethod", "summary": "Rename an MFA method", "description": "Updates the display name of an enrolled MFA method.", "tags": [ "Authentication" ], "parameters": [ { "name": "methodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the MFA method to rename." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_MfaRenameRequest" } } } }, "responses": { "200": { "description": "Method renamed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_MfaRenameResponse" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/recovery-codes/generate": { "post": { "operationId": "mfaGenerateRecoveryCodes", "summary": "Generate new recovery codes", "description": "Generates a fresh set of one-time recovery codes, invalidating any previously issued codes. The returned codes are shown only once.", "tags": [ "Authentication" ], "responses": { "200": { "description": "New recovery codes issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_RecoveryCodesResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/step-up/methods": { "get": { "operationId": "mfaStepUpMethods", "summary": "List available step-up MFA methods", "description": "Returns the list of MFA method types available for step-up authentication for the current user.", "tags": [ "Authentication" ], "responses": { "200": { "description": "Available step-up method types.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "string" }, "description": "Array of method type strings, e.g. `[\"totp\", \"webauthn\"]`." } }, "required": [ "methods" ], "additionalProperties": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/step-up/totp": { "post": { "operationId": "mfaStepUpTotp", "summary": "Perform TOTP step-up", "description": "Verifies a TOTP code to elevate the current session to MFA-stepped-up status. Returns a new token pair with the step-up claim. Required before sensitive operations such as password change. Only the `code` field is accepted; device-remember fields do not apply to step-up.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_TotpStepUpRequest" } } } }, "responses": { "200": { "description": "Step-up successful. Returns new token pair.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_TokenPair" } } } } } }, "400": { "description": "Invalid TOTP code format. Error code: `VALIDATION_ERROR`.", "$ref": "#/components/responses/ValidationError" }, "401": { "description": "Wrong TOTP code or no TOTP method enrolled. Error code: `AUTH_MFA_INVALID`.", "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/step-up/webauthn/options": { "post": { "operationId": "mfaStepUpWebauthnOptions", "summary": "Get WebAuthn options for step-up", "description": "Returns WebAuthn assertion options and an HMAC-signed `challenge_token` for step-up authentication.", "tags": [ "Authentication" ], "responses": { "200": { "description": "WebAuthn assertion options and challenge token for step-up.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_WebauthnChallengeOptions" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/step-up/webauthn/verify": { "post": { "operationId": "mfaStepUpWebauthnVerify", "summary": "Verify WebAuthn assertion for step-up", "description": "Verifies a WebAuthn assertion for step-up and returns a new token pair with the step-up claim.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_WebauthnStepUpVerifyRequest" } } } }, "responses": { "200": { "description": "Step-up successful. Returns new token pair.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_TokenPair" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/challenge/totp": { "post": { "operationId": "mfaChallengeTotpVerify", "summary": "Verify TOTP during MFA challenge", "description": "Verifies a TOTP code during an active MFA challenge (mid-login). Requires an MFA challenge token issued by `/login`, `/google-oauth`, or similar. On success, returns full session tokens. Optionally issues a `mfaDeviceToken` for remembered-device bypass on future logins.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_TotpChallengeRequest" } } } }, "responses": { "200": { "description": "MFA verified. Returns session tokens and optionally a device trust token.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_MfaChallengeResult" } } } } } }, "400": { "description": "Invalid or expired TOTP code. Error codes: `AUTH_MFA_INVALID`, `AUTH_MFA_TOKEN_EXPIRED`, `MFA_JWT_REPLAY`.", "$ref": "#/components/responses/ValidationError" }, "401": { "description": "Missing or invalid MFA challenge token. Error codes: `AUTH_REQUIRED`, `AUTH_MFA_TOKEN_EXPIRED`.", "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/challenge/webauthn/options": { "post": { "operationId": "mfaChallengeWebauthnOptions", "summary": "Get WebAuthn options during MFA challenge", "description": "Returns WebAuthn assertion options and a `challenge_token` during an active MFA challenge. Requires an MFA challenge token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "WebAuthn assertion options for the MFA challenge.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_WebauthnChallengeOptions" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/challenge/webauthn/verify": { "post": { "operationId": "mfaChallengeWebauthnVerify", "summary": "Verify WebAuthn assertion during MFA challenge", "description": "Verifies a WebAuthn assertion during an active MFA challenge. Requires an MFA challenge token. On success returns full session tokens and optionally a device trust token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_WebauthnChallengeVerifyRequest" } } } }, "responses": { "200": { "description": "MFA verified. Returns session tokens and optionally a device trust token.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_MfaChallengeResult" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/challenge/email-otp/send": { "post": { "operationId": "mfaChallengeEmailOtpSend", "summary": "Send email OTP during MFA challenge", "description": "Sends an email OTP to the user's registered email address during an active MFA challenge. Requires an MFA challenge token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OTP sent.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_EmailOtpSendResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/challenge/email-otp/verify": { "post": { "operationId": "mfaChallengeEmailOtpVerify", "summary": "Verify email OTP during MFA challenge", "description": "Verifies the email OTP sent by `/challenge/email-otp/send` during an active MFA challenge. Requires an MFA challenge token. On success returns full session tokens and optionally a device trust token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_EmailOtpVerifyRequest" } } } }, "responses": { "200": { "description": "MFA verified. Returns session tokens and optionally a device trust token.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_MfaChallengeResult" } } } } } }, "400": { "description": "Invalid or expired OTP code. Error codes: `AUTH_MFA_INVALID`, `AUTH_MFA_TOKEN_EXPIRED`.", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/mfa/challenge/recovery": { "post": { "operationId": "mfaChallengeRecoveryVerify", "summary": "Use recovery code during MFA challenge", "description": "Verifies a one-time recovery code during an active MFA challenge. The code is consumed and cannot be reused. Requires an MFA challenge token. On success returns full session tokens and optionally a device trust token.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_RecoveryCodeRequest" } } } }, "responses": { "200": { "description": "Recovery code accepted. Returns session tokens.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Authentication_MfaChallengeResult" } } } } } }, "400": { "description": "Invalid or already-used recovery code. Error codes: `AUTH_MFA_INVALID`, `AUTH_MFA_TOKEN_EXPIRED`.", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "mcpOAuthProtectedResourceMeta", "summary": "OAuth 2.0 protected resource metadata", "description": "Returns RFC 9728 protected-resource metadata for the MCP API surface. Lists the authorization server(s) and supported bearer methods.", "tags": [ "Authentication" ], "security": [ {} ], "responses": { "200": { "description": "Protected resource metadata document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthProtectedResourceMeta" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/.well-known/oauth-protected-resource/v1/mcp": { "get": { "operationId": "mcpOAuthProtectedResourceMetaAlt", "summary": "OAuth 2.0 protected resource metadata (MCP path variant)", "description": "Alternative path for RFC 9728 protected-resource metadata targeting `/v1/mcp` specifically. Returns the same document as `/.well-known/oauth-protected-resource`.", "tags": [ "Authentication" ], "security": [ {} ], "responses": { "200": { "description": "Protected resource metadata document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthProtectedResourceMeta" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "mcpOAuthAuthorizationServerMeta", "summary": "OAuth 2.0 authorization server metadata", "description": "Returns RFC 8414 authorization server metadata (also served at `/.well-known/openid-configuration`). Describes all OAuth 2.1 endpoints, supported grant types, PKCE methods, and dynamic client registration endpoint.", "tags": [ "Authentication" ], "security": [ {} ], "responses": { "200": { "description": "Authorization server metadata document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthAuthorizationServerMeta" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/.well-known/openid-configuration": { "get": { "operationId": "mcpOAuthOpenIdConfiguration", "summary": "OpenID Connect discovery document", "description": "Alias for `/.well-known/oauth-authorization-server`. Returns the same RFC 8414 authorization server metadata. Provided for compatibility with OpenID Connect clients.", "tags": [ "Authentication" ], "security": [ {} ], "responses": { "200": { "description": "Authorization server metadata document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthAuthorizationServerMeta" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/oauth/register": { "post": { "operationId": "mcpOAuthRegisterClient", "summary": "Dynamic client registration (RFC 7591)", "description": "Registers a new OAuth 2.0 client dynamically per RFC 7591. Returns a `client_id` for use in subsequent authorization requests.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthClientRegistrationRequest" } } } }, "responses": { "201": { "description": "Client registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthClientRegistrationResponse" } } } }, "400": { "description": "RFC 7591 error response. `error` values include `invalid_redirect_uri`, `invalid_client_metadata`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/oauth/authorize": { "get": { "operationId": "mcpOAuthAuthorize", "summary": "OAuth 2.0 authorization endpoint", "description": "Initiates the OAuth 2.0 authorization code flow with PKCE (S256 required, plain rejected per RFC 7636 §4.6). Redirects the user to the consent page on success, or returns an RFC 6749 error response.", "tags": [ "Authentication" ], "security": [ {} ], "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" }, "description": "PKCE code challenge (S256)." }, { "name": "code_challenge_method", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "S256" ] }, "description": "PKCE challenge method. Only `S256` is accepted." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to consent page or error redirect." }, "400": { "description": "RFC 6749 error response for invalid requests that cannot be redirected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthErrorResponse" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/oauth/token": { "post": { "operationId": "mcpOAuthToken", "summary": "OAuth 2.0 token endpoint", "description": "Exchanges an authorization code for an access token using the `authorization_code` grant type. The PKCE verifier must match the challenge submitted in `/oauth/authorize`. Accepts `application/x-www-form-urlencoded` or `application/json`. **Response format is RFC 6749 style** — not the standard Backbuild envelope.", "tags": [ "Authentication" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthTokenRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthTokenRequest" } } } }, "responses": { "200": { "description": "Access token issued. RFC 6749 response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthTokenResponse" } } } }, "400": { "description": "RFC 6749 error response. `error` values include `invalid_grant`, `invalid_request`, `invalid_client`, `unsupported_grant_type`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authentication_OAuthErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/operations": { "post": { "operationId": "proveOpsRegisterOperation", "summary": "Register a DAG solver operation", "description": "Registers a new solver-DAG operation (a named rewrite strategy) at `global`, `tenant`, or `project` scope. The scope walk and permission checks are enforced by the stored procedure: `tenant.write` or `global.write` permission is required. `global` scope writes additionally require platform-staff-level permission (`bbprove.global.write`) which is not held by ordinary organization owners — the SP returns `403 FORBIDDEN` for such attempts. `project_scope_id` is required when `scope` is `project`.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_OperationRegisterRequest" } } } }, "responses": { "201": { "description": "Operation registered. The new operation record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_OperationRow" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — body failed schema validation (missing required field, enum out of range, string too long, etc.) or `INVALID_ID_FORMAT` for a malformed UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `bbprove.tenant.write` (or `bbprove.global.write` for `scope=global`) permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — an operation with the same `(scope, name)` already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "proveOpsListOperations", "summary": "List solver-DAG operations for a scope", "description": "Returns all active (and optionally superseded) solver-DAG operations visible at `scope`. The SP applies the project → tenant → global scope walk so that project-scoped operations inherit tenant and global operations. `project_scope_id` is required when `scope=project`. Requires `bbprove.read` permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "description": "Visibility scope: `global` (platform-wide), `tenant` (organization-wide), or `project` (project-scoped).", "schema": { "type": "string", "enum": [ "global", "tenant", "project" ] } }, { "name": "project_scope_id", "in": "query", "required": false, "description": "Required when `scope=project`. The project whose scoped operations are returned (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "strategy_kind", "in": "query", "required": false, "description": "Filter to operations of a specific strategy kind.", "schema": { "type": "string", "enum": [ "normalize_to_fixpoint", "pattern_isolate", "decision_procedure", "symbolic_rewrite", "compute", "custom" ] } }, { "name": "include_rules", "in": "query", "required": false, "description": "When `false`, the per-operation rule list is omitted from the response to reduce payload size. Defaults to `true`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "include_superseded", "in": "query", "required": false, "description": "When `true`, superseded (soft-retracted) operations are included alongside active ones. Defaults to `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of operations to return (default and ceiling are server-determined).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of operations to skip for offset pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of operations matching the scope filter.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveOps_OperationRow" } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `scope` is missing or invalid; `project_scope_id` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `bbprove.read` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/operations/lookup": { "get": { "operationId": "proveOpsLookupOperation", "summary": "Look up a solver-DAG operation by name", "description": "Fetches a single solver-DAG operation by its `(scope, name)` key. The SP applies the scope walk for `project` scope (project → tenant → global). `project_scope_id` is required when `scope=project`. Requires `bbprove.read` permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "description": "Scope level: `global`, `tenant`, or `project`.", "schema": { "type": "string", "enum": [ "global", "tenant", "project" ] } }, { "name": "name", "in": "query", "required": true, "description": "Operation name to look up (1–1000 characters).", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 } }, { "name": "project_scope_id", "in": "query", "required": false, "description": "Required when `scope=project`. Project identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_rules", "in": "query", "required": false, "description": "When `true`, the operation's associated theorem rules are included. Defaults to `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "include_superseded", "in": "query", "required": false, "description": "When `true`, a superseded operation at this name can still be returned.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "The operation record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_OperationRow" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `scope` or `name` is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `bbprove.read` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — no operation exists at `(scope, name)` visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/operations/{operationId}/rules": { "post": { "operationId": "proveOpsAddOperationRule", "summary": "Tag a theorem as a rewrite rule for an operation", "description": "Associates a theorem (by `theorem_id`) as a rewrite rule on the given solver-DAG operation. The optional `rule_order` determines priority (lower = higher priority); `direction` constrains the rule's application direction. Requires `bbprove.tenant.write` (or `bbprove.global.write` for global-scope operations) permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "description": "Solver-DAG operation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_RuleAddRequest" } } } }, "responses": { "201": { "description": "Rule association created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_RuleRow" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed `operationId`. `VALIDATION_ERROR` — body failed schema validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks write permission for the operation's scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — `operationId` or `theorem_id` not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the theorem is already a rule on this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/operations/{operationId}/rules/{theoremId}": { "delete": { "operationId": "proveOpsRemoveOperationRule", "summary": "Remove a theorem rule from an operation", "description": "Removes the association between the given theorem and solver-DAG operation. Requires `bbprove.tenant.write` (or `bbprove.global.write`) permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "description": "Solver-DAG operation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "theoremId", "in": "path", "required": true, "description": "Theorem identifier to disassociate (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rule removed. The updated operation record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_OperationRow" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed `operationId` or `theoremId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks write permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — operation or rule association not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/operations/{operationId}/supersede": { "post": { "operationId": "proveOpsSupersedeOperation", "summary": "Supersede (soft-retract) a solver-DAG operation", "description": "Marks the given operation as superseded by `new_operation_id`. Superseded operations are excluded from the default listing (`include_superseded=false`) but remain queryable for audit purposes. Requires `bbprove.tenant.admin` (or `bbprove.global.admin`) permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "description": "Solver-DAG operation to supersede (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_SupersedeRequest" } } } }, "responses": { "200": { "description": "Operation superseded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_OperationRow" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks admin permission for the operation's scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — `operationId` or `new_operation_id` not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the operation is already superseded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/operations/{operationId}/test-cases": { "post": { "operationId": "proveOpsAddTestCase", "summary": "Add a static test case to an operation", "description": "Attaches a static LaTeX test case to the given solver-DAG operation. An optional `expected_output` and `oracle_kind` control how the kernel verifier evaluates the test. Requires `bbprove.tenant.write` (or `bbprove.global.write`) permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "description": "Solver-DAG operation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_TestCaseAddRequest" } } } }, "responses": { "201": { "description": "Test case added.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_TestCaseRow" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks write permission for the operation's scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — `operationId` not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "proveOpsListTestCases", "summary": "List test cases for an operation", "description": "Returns the static test cases attached to the given solver-DAG operation. Inactive (soft-deleted) test cases are excluded by default; pass `include_inactive=true` to include them. Requires `bbprove.read` permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "description": "Solver-DAG operation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_inactive", "in": "query", "required": false, "description": "When `true`, soft-deleted test cases are included. Defaults to `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum test cases to return.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of test cases to skip for pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of test cases.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveOps_TestCaseRow" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed `operationId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `bbprove.read` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — `operationId` not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/test-cases/{testCaseId}": { "delete": { "operationId": "proveOpsDeactivateTestCase", "summary": "Deactivate (soft-delete) a test case", "description": "Soft-deletes a DAG operation test case by setting `is_active=false`. The test case remains in the audit trail and can be retrieved with `include_inactive=true`. Requires `bbprove.tenant.write` (or `bbprove.global.write`) permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "testCaseId", "in": "path", "required": true, "description": "Test case identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Test case deactivated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_TestCaseRow" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed `testCaseId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks write permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — test case not found or not visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/tenant-blocks": { "post": { "operationId": "proveOpsAddTenantBlock", "summary": "Block a content hash at tenant scope", "description": "Suppresses a global DAG content hash at the organization (tenant) level, preventing it from being applied within the org even when it is present in a global operation. `blocked_content_hash` must be a 64-character lowercase hex SHA-256 digest. Requires `bbprove.tenant.admin` permission.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_TenantBlockAddRequest" } } } }, "responses": { "201": { "description": "Content hash blocked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_TenantBlockRow" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `blocked_content_hash` is not a 64-character lowercase hex digest, or the body is otherwise invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `bbprove.tenant.admin` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the content hash is already blocked at this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/tenant-blocks/{blockId}": { "delete": { "operationId": "proveOpsRevokeTenantBlock", "summary": "Revoke a tenant-scope content hash block", "description": "Removes a previously added tenant-level DAG content hash block, restoring access to the global hash. Requires `bbprove.tenant.admin` permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "blockId", "in": "path", "required": true, "description": "Tenant block identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Block revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed `blockId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `bbprove.tenant.admin` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — block not found or does not belong to the caller's organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/theorems": { "post": { "operationId": "proveOpsRegisterTheorem", "summary": "Register a DAG theorem", "description": "Registers a new theorem in the solver-DAG knowledge base at `global`, `tenant`, or `project` scope. `proof_latex` and `conclusion` carry the formal content; `proof_class` classifies the audit status. Setting `kernel_verified=true` requires platform-staff-level permission (`bbprove.global.write`) — the SP returns `403 FORBIDDEN` for ordinary callers. `project_scope_id` is required when `scope=project`.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_TheoremRegisterRequest" } } } }, "responses": { "201": { "description": "Theorem registered.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_TheoremRow" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — body failed schema validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks write permission for the requested scope (or `bbprove.global.write` for `kernel_verified=true`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a theorem with the same `(scope, name)` already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "proveOpsListTheorems", "summary": "List DAG theorems for a scope", "description": "Returns solver-DAG theorems visible at `scope`. The SP walks the scope hierarchy (project → tenant → global). Optional `name_prefix` prefix-matches on theorem names. Requires `bbprove.read` permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "description": "Visibility scope: `global`, `tenant`, or `project`.", "schema": { "type": "string", "enum": [ "global", "tenant", "project" ] } }, { "name": "project_scope_id", "in": "query", "required": false, "description": "Required when `scope=project`. Project identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "name_prefix", "in": "query", "required": false, "description": "Optional name prefix filter (up to 1000 characters).", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "include_superseded", "in": "query", "required": false, "description": "When `true`, superseded theorems are included. Defaults to `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of theorems to return.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of theorems to skip for pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of theorems.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveOps_TheoremRow" } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `scope` is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `bbprove.read` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/theorems/lookup": { "get": { "operationId": "proveOpsLookupTheorem", "summary": "Look up a DAG theorem by name", "description": "Fetches a single solver-DAG theorem by its `(scope, name)` key. The SP applies the scope walk for `project` scope. Requires `bbprove.read` permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "description": "Scope level: `global`, `tenant`, or `project`.", "schema": { "type": "string", "enum": [ "global", "tenant", "project" ] } }, { "name": "name", "in": "query", "required": true, "description": "Theorem name (1–1000 characters).", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 } }, { "name": "project_scope_id", "in": "query", "required": false, "description": "Required when `scope=project`. Project identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_superseded", "in": "query", "required": false, "description": "When `true`, a superseded theorem at this name can still be returned.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "The theorem record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_TheoremRow" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `scope` or `name` is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `bbprove.read` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — no theorem exists at `(scope, name)` visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/dag/theorems/{theoremId}/supersede": { "post": { "operationId": "proveOpsSupersedeTheorem", "summary": "Supersede (soft-retract) a DAG theorem", "description": "Marks the given theorem as superseded by `new_theorem_id`. Superseded theorems are excluded from default listings but remain queryable for audit and rule-resolution purposes. Requires `bbprove.tenant.admin` (or `bbprove.global.admin`) permission.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "theoremId", "in": "path", "required": true, "description": "Theorem to supersede (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_TheoremSupersedeRequest" } } } }, "responses": { "200": { "description": "Theorem superseded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_TheoremRow" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks admin permission for the theorem's scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — `theoremId` or `new_theorem_id` not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the theorem is already superseded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/proofs/graph": { "get": { "operationId": "proveOpsGetProofsGraph", "summary": "Get the proof artifact dependency graph", "description": "Returns the directed acyclic graph of kernel artifacts (nodes) and their dependency edges for the given project. Nodes and edges can be filtered by `kind` and/or `state` (comma-separated multi-value). JWT-authenticated; project membership and `prove.read` permission are enforced by the stored procedure. No Prove subscription entitlement gate — any project member may browse the graph.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "kind", "in": "query", "required": false, "description": "Comma-separated artifact kind filter. Allowed values: `hypothesis`, `prediction`, `observation`, `definition`, `obligation`, `discharge`, `theorem`, `lemma`, `corollary`, `proposition`.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Comma-separated artifact state filter. Allowed values: `draft`, `submitted`, `pending`, `suggestive`, `corroborated`, `discharged`, `accepted_unverified`, `accepted_pending_promotion`, `provisional`, `promoted`, `rejected`, `refuted`, `stale`, `superseded`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artifact graph with nodes and edges.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_ArtifactGraph" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid UUID `projectId` or an unrecognized value in the `kind`/`state` filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/proofs/table": { "get": { "operationId": "proveOpsGetProofsTable", "summary": "Get a paginated proof artifact table", "description": "Returns a paginated, optionally text-searched list of kernel artifacts for the given project. Text search (`q`) is a full-text keyword search over artifact names and source. Results are ordered by relevance when `q` is supplied, by recency otherwise. JWT-authenticated; no Prove subscription gate.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "q", "in": "query", "required": false, "description": "Full-text search query (1–500 characters). Control characters (except `\\n`/`\\t`) are rejected.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (1–100000, default 1).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Records per page (1–200, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "kind", "in": "query", "required": false, "description": "Comma-separated artifact kind filter (same allowed values as the graph endpoint).", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Comma-separated artifact state filter (same allowed values as the graph endpoint).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated artifact table.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/ProveOps_ArtifactSummary" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`, out-of-range pagination params, unrecognized filter value, or control characters in `q`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/proofs/{artifactId}": { "get": { "operationId": "proveOpsGetArtifact", "summary": "Get a proof artifact", "description": "Returns a single kernel artifact with its associated kernel-run record and source document metadata. JWT-authenticated; project membership required. A non-existent or inaccessible artifact is indistinguishable from a missing one (uniform 404).", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "artifactId", "in": "path", "required": true, "description": "Artifact identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Artifact record with associated run and document.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_ArtifactDetail" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — malformed `projectId` or `artifactId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/proofs/{artifactId}/history": { "get": { "operationId": "proveOpsGetArtifactHistory", "summary": "Get a proof artifact's transition history", "description": "Returns the state-transition history for a kernel artifact (e.g. `draft` → `submitted` → `promoted`). JWT-authenticated; project membership required.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "artifactId", "in": "path", "required": true, "description": "Artifact identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum history entries to return (1–500, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "Ordered list of artifact state transitions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "history": { "type": "array", "items": { "$ref": "#/components/schemas/ProveOps_ArtifactTransition" } } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — malformed path param or invalid `limit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/proofs/search": { "post": { "operationId": "proveOpsSemanticSearchProofs", "summary": "Semantic search over proof source documents", "description": "Runs a hybrid dense + ColBERT semantic search over the project's proof source documents. The query is embedded by the platform's embedding service; results are ranked by cosine similarity against a `threshold` floor. JWT-authenticated; project membership required. No Prove subscription gate.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_SemanticSearchRequest" } } } }, "responses": { "200": { "description": "Ranked list of matching proof source documents.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/ProveOps_SemanticSearchResult" } } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`, missing/too-long query, or control characters in the query string.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "`INTERNAL_ERROR` — an unexpected server error, including a failure to contact the embedding service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "`INTERNAL_ERROR` — the embedding service returned an error or was unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbprove/projects/{projectId}/graph/layout": { "get": { "operationId": "proveOpsGetGraphLayout", "summary": "Get the user's persisted graph layout", "description": "Returns the calling user's persisted node positions and viewport for the project's proof artifact graph. Layouts are keyed per `(organization, project, user)` — each collaborator has independent node positions. Returns `null` under `data` when no layout has been saved yet (the client falls back to an automatic Verlet-physics layout). JWT-authenticated; project membership required.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Persisted layout, or `null` when no layout has been saved.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/ProveOps_GraphLayout" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — malformed `projectId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "proveOpsSaveGraphLayout", "summary": "Save the user's graph layout", "description": "Upserts the calling user's node positions and viewport for the project's proof artifact graph. Sending an empty `nodes` array with no `viewport` fields deletes the stored layout (reset to automatic Verlet-physics). JWT-authenticated; project membership required.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_GraphLayoutPutRequest" } } } }, "responses": { "200": { "description": "Layout saved (or cleared). `saved=true` when positions were written; `cleared=true` when the layout was deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "saved", "cleared", "updated_at" ], "properties": { "saved": { "type": "boolean", "description": "`true` when node positions were written." }, "cleared": { "type": "boolean", "description": "`true` when the layout was deleted (reset to automatic)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the upsert." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — malformed `projectId`, `nodes` exceeds 5000 entries, non-finite coordinates, or `viewport.zoom` out of the 0.05–20 range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/runs/{runId}/log": { "get": { "operationId": "proveOpsGetRunLog", "summary": "Get a kernel-run log", "description": "Returns metadata and AI-verdict (if any) for a single kernel verification run, including state, exit code, document reference, timing, and AI-check result. Consumed by the artifact history panel run-log overlay. JWT-authenticated; access is scoped to the caller's organization by Row-Level Security — cross-organization lookups return `404 NOT_FOUND`. No Prove subscription gate.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Kernel run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Kernel run log record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_KernelRunLog" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — malformed `runId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller's organization does not match the run's organization (returned as `NOT_FOUND` by the SP for anti-enumeration).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/submissions": { "post": { "operationId": "proveOpsCreateSubmission", "summary": "Submit a document for kernel evaluation", "description": "Submits the HEAD version of the given document for asynchronous Lean 4 kernel evaluation. The server resolves the current HEAD for the `documentId` chain, inserts a `queued` kernel run row, and best-effort enqueues the job. If the queue binding is unavailable, the run row is still created and can be replayed; `queue_warning` in the response will be non-null in that case. The `enableAiCheck` flag opts the run into an optional AI grader stage; when omitted, the server resolves the effective value from the per-document → per-user-per-project → per-project preference chain. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveOps_SubmissionCreateRequest" } } } }, "responses": { "200": { "description": "Submission queued. `queue_warning` is non-null if the background job queue was unavailable — the run row exists regardless and will be processed once the queue is restored.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveOps_SubmissionCreateResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `documentId` is missing or not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` — no active Backbuild Prove subscription. `BILLING_SUBSCRIPTION_PAST_DUE` or `BILLING_SUBSCRIPTION_CANCELLED` for lapsed subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller lacks project membership or `prove.submit` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — `documentId` not found or the HEAD version of the document chain is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/webhooks/{webhookId}/deliveries": { "get": { "operationId": "proveOpsListWebhookDeliveries", "summary": "List webhook delivery audit records", "description": "Returns the per-attempt delivery audit log for a Backbuild Prove webhook. Allows operators to review delivery status, response codes, and retry history. `only_failed=true` filters to failed attempts only. Requires `prove.read` permission (JWT-authenticated; no entitlement gate).", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of delivery records to return.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of delivery records to skip for pagination.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "only_failed", "in": "query", "required": false, "description": "When `true`, only failed delivery attempts are returned. Defaults to `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Paginated list of delivery audit records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveOps_WebhookDelivery" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed `webhookId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `prove.read` permission or the webhook does not belong to the caller's organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/documents": { "post": { "operationId": "proveDocsSaveDocument", "summary": "Save (or no-op) a document version", "description": "Persists a new version of a document in the given project. The body carries the full source content; if the content is byte-for-byte identical to the current HEAD the server may return the existing version (no-op). `format` defaults to `pf2` when omitted. Supplying an existing `document_id` anchors the version onto that document chain; omit it to let the server create a new chain.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveDocs_DocumentSaveRequest" } } } }, "responses": { "200": { "description": "Document version saved (or no-op'd). The persisted document version record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_DocumentVersion" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `project_id`, malformed body, or a path that fails canonicalization (e.g. path traversal, double-encoded, null bytes, absolute path).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — the caller's organization does not have an active Backbuild Prove entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "proveDocsListDocuments", "summary": "List project documents", "description": "Returns documents in the project. By default only the HEAD (latest) version of each document is returned. Pass `head_only=false` to include all historical versions. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "head_only", "in": "query", "required": false, "description": "When `false`, all historical versions are returned instead of only the HEAD. Defaults to `true`.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "List of document versions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveDocs_DocumentVersion" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — the caller's organization does not have an active Backbuild Prove entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/documents/{documentId}/assets": { "post": { "operationId": "proveDocsUploadAsset", "summary": "Upload a document asset (image)", "description": "Stream-uploads an image asset into the given document's asset store. The upload pipeline validates in this order: UUID params → document effective-access write-gate → R2 binding check → body size cap → magic-byte image type sniff + dimension/frame/ratio caps + SVG sanitization → content-addressed R2 PUT. Access is gated by project membership and write-grant, not a Prove subscription, so all document authors (regardless of subscription state) can upload images. Knowing the resulting content-addressed `sha256` does not grant read access — delivery requires a re-checked read on the owning document per request.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Owning document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "ext", "in": "query", "required": false, "description": "Declared image file extension (`png`, `jpg`, `gif`, `webp`, `svg`). Used as a cross-check only — the server sniffs the actual type from the bytes and the sniff is authoritative.", "schema": { "type": "string", "enum": [ "png", "jpg", "gif", "webp", "svg" ] } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw image bytes. Maximum size is enforced server-side; the limit varies by environment but is typically 10 MB." } } } }, "responses": { "201": { "description": "Asset uploaded successfully. All metadata values are decoder-measured (never client-asserted).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_AssetUploadResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid UUID params or path canonicalization failure. `UNSUPPORTED_FILE_TYPE` — the image type is not allowed or an SVG contains unsafe content. `UPLOAD_SUPPRESSED` — the content matches the operator deny-list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller has read-only access to the document and cannot upload assets into it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the document does not exist, is not a Backbuild Prove document, does not belong to the named project, or the caller cannot see it (uniform 404, no existence oracle).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — the uploaded image exceeds the maximum allowed size. `FILE_SIZE_LIMIT_EXCEEDED` is also emitted at 413 when the image cap is breached post-sniff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — the asset storage binding is not configured or is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbprove/projects/{projectId}/documents/{documentId}/assets/{assetSha}": { "get": { "operationId": "proveDocsDeliverAsset", "summary": "Deliver a document asset (image)", "description": "Streams the immutable image asset identified by its content-addressed `assetSha` (64-character lowercase hex SHA-256). Read access on the owning document is re-checked on every request — a revoked membership cannot use a cached URL to keep accessing assets. Supports `If-None-Match` for conditional GET (304). The `ext` query parameter is required to reconstruct the storage key.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Owning document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "assetSha", "in": "path", "required": true, "description": "Content-addressed SHA-256 identifier — 64 lowercase hex characters.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "ext", "in": "query", "required": true, "description": "Image file extension used to reconstruct the storage key. Must be one of the allowed types.", "schema": { "type": "string", "enum": [ "png", "jpg", "gif", "webp", "svg" ] } } ], "responses": { "200": { "description": "Image bytes. `Content-Type` reflects the stored MIME type; `ETag` equals `\"\"`; `Cache-Control: private, max-age=3600`.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "Not Modified — the `If-None-Match` value matched the `ETag`." }, "400": { "description": "`VALIDATION_ERROR` — invalid UUID params, `assetSha` is not a 64-character hex digest, or `ext` is missing/invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the asset's storage key belongs to a different organization than the session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the document is not visible to the caller or the asset object is missing from storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — the asset storage binding is not configured or is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbprove/documents/{documentId}": { "get": { "operationId": "proveDocsGetDocument", "summary": "Get a document version", "description": "Fetches a single document version by its id. The caller must be a member of the owning project. A document the caller cannot see is indistinguishable from a non-existent one (404).", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "Document version identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The document version record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_DocumentVersion" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/predictions": { "get": { "operationId": "proveDocsListPredictions", "summary": "List project predictions", "description": "Returns the predictions for the given project, optionally filtered by parent hypothesis. Predictions are created by the kernel from `\\prediction{...}` macros in the document source — they are not directly mutable via this API. JWT-authenticated; project-membership enforced inside the stored procedure.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "parent_hypothesis_id", "in": "query", "required": false, "description": "Filter to predictions that belong to a specific hypothesis (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of predictions to return (1–1000, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of predictions to skip for pagination.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated list of predictions with total count.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "predictions": { "type": "array", "items": { "$ref": "#/components/schemas/ProveDocs_PredictionSummary" } }, "total": { "type": "integer", "description": "Total matching predictions." }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/predictions/{predictionId}": { "get": { "operationId": "proveDocsGetPrediction", "summary": "Get a prediction", "description": "Returns a single prediction with its structured observables and computational evidence. JWT-authenticated; project-membership enforced inside the stored procedure. If the returned prediction does not belong to the URL `projectId`, `404 NOT_FOUND` is returned.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "predictionId", "in": "path", "required": true, "description": "Prediction identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The prediction record with observables and evidence.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_PredictionDetail" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — prediction not found or does not belong to the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/discoveries": { "get": { "operationId": "proveDocsListDiscoveries", "summary": "List project discoveries", "description": "Returns the project-scoped feed of 5σ discoveries (kernel artifacts where `is_discovery` is true), enriched with first-discovery timestamp and parent hypothesis. Paginated and filtered by a lookback window. JWT-authenticated; no Prove entitlement gate (any project member may view discoveries).", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "sinceDays", "in": "query", "required": false, "description": "Look-back window in days (1–3650, default 30).", "schema": { "type": "integer", "minimum": 1, "maximum": 3650, "default": 30 } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (1–100000, default 1).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Records per page (1–100, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated discoveries feed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "discoveries": { "type": "array", "items": { "$ref": "#/components/schemas/ProveDocs_Discovery" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "since_days": { "type": "integer", "description": "The lookback window used for this response." } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/documents/{documentId}/build-pdf": { "post": { "operationId": "proveDocsBuildPdf", "summary": "Submit a document for PDF rendering", "description": "Submits the HEAD version of the given document for asynchronous PDF rendering. A new `bbprove_pdf_builds` row is created with status `queued` and a build job is enqueued. If `idempotent` is true (default) and a `done` build for the same input already exists, that build is returned immediately with `reused: true`. `queue_warning` in the response is non-null when the internal build queue was unavailable — the row is still created and can be replayed. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Document identifier (UUIDv7). The HEAD version of this document is built.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveDocs_PdfBuildRequest" } } } }, "responses": { "200": { "description": "Build queued (or reused). `reused: true` when an existing `done` build was returned unchanged.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_PdfBuildCreateResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid UUID params or invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required. `FORBIDDEN` — project membership required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — document not found or does not belong to this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/pdf-builds/{buildId}": { "get": { "operationId": "proveDocsGetPdfBuild", "summary": "Get PDF build status", "description": "Returns the current status of a PDF build. JWT + project-membership required; no Prove entitlement gate (viewers must be able to poll regardless of subscription state).", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "PDF build identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PDF build record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_PdfBuildRow" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/pdf-builds/{buildId}/download": { "get": { "operationId": "proveDocsDownloadPdf", "summary": "Download a rendered PDF", "description": "Streams the rendered PDF for a `done` build. Returns `409 CONFLICT` when the build is in any state other than `done` (e.g. `queued`, `running`, `failed`). JWT + project-membership required; no Prove entitlement gate.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "PDF build identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PDF file bytes. `Content-Type: application/pdf`; `Content-Disposition: attachment`; `Cache-Control: private, max-age=0, must-revalidate`.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — build not found or PDF object missing from storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the build is not yet in `done` state (still `queued`/`running`) or has `failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/pdf-builds/{buildId}/error-log": { "get": { "operationId": "proveDocsGetPdfBuildErrorLog", "summary": "Get PDF build error log", "description": "Streams the captured builder log for a failed PDF build. Returns `404 NOT_FOUND` if no error log was captured (e.g. build never ran or the log was not retained). JWT + project-membership required; no Prove entitlement gate.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "PDF build identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Builder log text. `Content-Type: text/plain; charset=utf-8`.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — no error log captured for this build.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/pdf-builds": { "get": { "operationId": "proveDocsListPdfBuilds", "summary": "List PDF builds for a project", "description": "Returns PDF build records for the project, most recent first. Optionally filter by `document_id` or `status`. JWT + project-membership required; no Prove entitlement gate.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "document_id", "in": "query", "required": false, "description": "Filter to builds for a specific document (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by build status.", "schema": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "List of PDF build records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveDocs_PdfBuildRow" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/theorems/{artifactId}/export": { "post": { "operationId": "proveDocsCreateTheoremExport", "summary": "Create a theorem export", "description": "Initiates an export of a theorem artifact. `tex` and `json` formats complete synchronously (content returned inline in the response). `pdf` is async — a build job is enqueued and the caller must poll `poll_url` (the `/v1/bbprove/theorem-exports/{exportId}` endpoint). Requires `prove.read` permission on the project (enforced inside the stored procedure). Export creation is audit-logged.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "artifactId", "in": "path", "required": true, "description": "Theorem artifact identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveDocs_TheoremExportRequest" } } } }, "responses": { "200": { "description": "Export created. For `tex`/`json` formats, `content` contains the result inline. For `pdf`, `status` is `queued`; poll `poll_url` for completion.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_TheoremExportCreateResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid UUID params or unsupported `format`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `prove.read` permission on the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — artifact or project not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — no signing key is registered for this organization or the artifact is in an invalid state for export. A `CONFLICT` with a `no signing key` context means the caller must register a signing key before exporting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/theorem-exports/{exportId}": { "get": { "operationId": "proveDocsGetTheoremExport", "summary": "Get theorem export status", "description": "Returns the current status of a theorem export. For PDF exports, the row is auto-promoted to `done` or `failed` when the underlying PDF build completes. JWT-authenticated; project-membership enforced inside the stored procedure.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "exportId", "in": "path", "required": true, "description": "Theorem export identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Theorem export status record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_TheoremExportRow" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/theorem-exports/{exportId}/content": { "get": { "operationId": "proveDocsDownloadTheoremExport", "summary": "Download theorem export content", "description": "Downloads the content of a completed theorem export. Returns `409 CONFLICT` when the export is not yet in `done` state. `tex` and `json` are served inline; `pdf` is streamed from storage. JWT-authenticated; project-membership enforced inside the stored procedure.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "exportId", "in": "path", "required": true, "description": "Theorem export identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Export content. `Content-Disposition: attachment`. Content-Type varies by format: `application/json` for `json`, `application/x-tex` for `tex`, `application/pdf` for `pdf`.", "content": { "application/json": { "schema": { "type": "string" } }, "application/x-tex": { "schema": { "type": "string" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — export not found or content unavailable from storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the export is not yet in `done` state or has `failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/realtime/ticket": { "post": { "operationId": "proveDocsMintRealtimeTicket", "summary": "Mint a realtime subscription ticket", "description": "Validates the caller's project access, then mints a single-use 60-second ticket for the project's realtime event room. After receiving the ticket, open a WebSocket connection to `GET /v1/collaboration/ws?token={ticket}` and send `{ type: 'join_room', roomId: room }` using the `room` value from the response. The ticket is deleted on first use and expires after 60 seconds; any error during the access check fails closed with `403 FORBIDDEN`.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Single-use realtime ticket minted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_RealtimeTicket" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller does not have read access to this project, or the access check failed (fail-closed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/settings/user": { "get": { "operationId": "proveDocsGetUserProjectPrefs", "summary": "Get user Prove preferences for a project", "description": "Returns the calling user's per-project Prove preferences, including the effective AI-check value after applying override → project-default fallback. JWT-authenticated; project-membership required.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "User preference record with effective values.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_UserProjectPrefs" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "proveDocsSetUserProjectPrefs", "summary": "Set user Prove preferences for a project", "description": "Updates the calling user's per-project Prove preferences. `default_ai_check_user_override` accepts `true`, `false`, or `null` — passing `null` clears the override so the project-level default applies. JWT-authenticated; project-membership required.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveDocs_UserProjectPrefsRequest" } } } }, "responses": { "200": { "description": "Updated user preference record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_UserProjectPrefs" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `default_ai_check_user_override` must be `true`, `false`, or `null`; the key must be present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/shares": { "post": { "operationId": "proveDocsCreateShare", "summary": "Grant a cross-org share", "description": "Grants (or upserts) a cross-organization share of a document or artifact to a recipient organization. When `can_edit` is `true`, `granted_by_policy_id` is required — the API validates this before the stored procedure and returns `400 INVALID_POLICY` immediately. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveDocs_ShareCreateRequest" } } } }, "responses": { "200": { "description": "Share created or upserted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_Share" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid payload. `INVALID_POLICY` — `can_edit=true` but `granted_by_policy_id` is absent, or the referenced policy failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required. `FORBIDDEN` — caller lacks share-grant permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "proveDocsListShares", "summary": "List shares", "description": "Returns active shares filtered by `scope`. `scope=owned` returns shares this organization has granted; `scope=received` returns shares other organizations have granted to this organization. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "description": "Whether to return shares this org has granted (`owned`) or received (`received`).", "schema": { "type": "string", "enum": [ "owned", "received" ] } } ], "responses": { "200": { "description": "List of shares.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveDocs_Share" } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `scope` is missing or is not `owned` or `received`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/shares/{shareId}": { "get": { "operationId": "proveDocsGetShare", "summary": "Get a share", "description": "Returns a single share record with target metadata. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "shareId", "in": "path", "required": true, "description": "Share identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The share record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_Share" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required. `FORBIDDEN` — caller is neither the owner nor the recipient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "proveDocsRevokeShare", "summary": "Revoke a cross-org share", "description": "Revokes a cross-organization share. Idempotent — revoking a non-existent or already-revoked share returns success. Only the owning organization can revoke. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "shareId", "in": "path", "required": true, "description": "Share identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Share revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required. `FORBIDDEN` — caller is not the share owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/pdf-settings": { "get": { "operationId": "proveDocsGetPdfSettings", "summary": "Get project PDF build defaults", "description": "Returns the per-project default PDF build settings (theme, primary language). JWT + project-membership (viewer level) required; no Prove entitlement gate so viewers always have access to display the Build PDF UX defaults.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Project PDF settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_PdfSettings" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "proveDocsUpsertPdfSettings", "summary": "Upsert project PDF build defaults", "description": "Persists per-project PDF build defaults (theme, primary language). Requires JWT + Backbuild Prove entitlement. Editor-level membership is enforced inside the stored procedure. At least one field must be present; unknown fields are rejected (`additionalProperties: false`).", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveDocs_PdfSettingsRequest" } } } }, "responses": { "200": { "description": "Updated project PDF settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_PdfSettings" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `theme`, invalid `primaryLanguage` (must satisfy BCP-47 syntax: 2-3 letter language code optionally followed by hyphen-separated subtags, max 35 chars).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required. `FORBIDDEN` — caller lacks editor-level project membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/documents/{documentId}/history": { "get": { "operationId": "proveDocsGetDocumentHistory", "summary": "Get document version history", "description": "Returns the full version chain for the document identified by `documentId`. The caller must supply `project_id` and `path` query parameters; these allow the server to locate the chain efficiently and verify that `documentId` belongs to it. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "Document version identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": true, "description": "Project identifier (UUIDv7) that owns the document chain.", "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "description": "Project-relative canonical file path (URL-encoded). Must match the canonicalization rules: no leading slash, no `.` or `..` segments, no null bytes, no backslashes, not double-encoded.", "schema": { "type": "string", "minLength": 1, "maxLength": 4096 } } ], "responses": { "200": { "description": "Ordered list of document versions in the chain (oldest first).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveDocs_DocumentVersion" } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `project_id` or `path` missing/invalid, or `path` fails canonicalization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/documents/drafts": { "put": { "operationId": "proveDocsUpsertDraft", "summary": "Upsert a document draft", "description": "Creates or replaces the in-progress draft for the given `(project, path)` tuple. There is at most one draft per `(org, project, path)`; every PUT overwrites the previous draft body. Returns persisted metadata only — content is not echoed to minimize auto-save response size. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveDocs_DraftSaveRequest" } } } }, "responses": { "200": { "description": "Draft saved. Returns the persisted draft metadata (content not echoed).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_DraftMeta" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid body, invalid `path` (canonicalization failure), or `project_id` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/documents/drafts/{path}": { "get": { "operationId": "proveDocsGetDraft", "summary": "Get a document draft", "description": "Fetches the in-progress draft for `(project, path)`. Always returns a stable envelope: `{ exists: false }` when no draft is present; `{ exists: true, draft: { ... } }` otherwise. The `:path` segment must be URL-encoded by the caller. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "path", "in": "path", "required": true, "description": "URL-encoded project-relative file path (e.g. `ch01%2Fmain.pf2`). The server decodes and canonicalizes this before looking up the draft.", "schema": { "type": "string", "minLength": 1, "maxLength": 4096 } } ], "responses": { "200": { "description": "Draft lookup result. `exists` is always present; `draft` is present only when `exists` is `true`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_DraftGetResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `project_id` UUID or path canonicalization failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "proveDocsDiscardDraft", "summary": "Discard a document draft", "description": "Discards the in-progress draft for `(project, path)`. Idempotent — `{ discarded: false }` is returned when no draft existed. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "path", "in": "path", "required": true, "description": "URL-encoded project-relative file path.", "schema": { "type": "string", "minLength": 1, "maxLength": 4096 } } ], "responses": { "200": { "description": "Draft discarded (or was not present). `discarded` is `true` if a draft existed and was deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "discarded": { "type": "boolean", "description": "True if a draft existed and was deleted." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `project_id` UUID or path canonicalization failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/documents/drafts/{path}/publish": { "post": { "operationId": "proveDocsPublishDraft", "summary": "Publish a document draft", "description": "Atomically materializes the in-progress draft into a new document version and clears the draft. If no draft exists for the given `(project, path)`, returns `404 NOT_FOUND` with `error.sub_code = 'PUBLISH_NO_DRAFT'`. If the draft's base version is stale (another commit landed since the draft was saved), returns `409 CONFLICT` with `error.sub_code = 'PUBLISH_CONFLICT'` and `error.details` carrying `{ current_head_version_id, current_head_version, draft_base_version_id, draft_base_version }` to enable a 3-way merge in the editor. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "path", "in": "path", "required": true, "description": "URL-encoded project-relative file path.", "schema": { "type": "string", "minLength": 1, "maxLength": 4096 } } ], "responses": { "200": { "description": "Draft published successfully. Returns the new document version record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_DraftPublishResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `project_id` UUID or path canonicalization failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — no draft exists for `(project, path)`. The error envelope includes `error.sub_code = 'PUBLISH_NO_DRAFT'` to distinguish this from a generic not-found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the draft's base version is stale. `error.sub_code = 'PUBLISH_CONFLICT'`; `error.details` contains `current_head_version_id`, `current_head_version`, `draft_base_version_id`, and `draft_base_version` for 3-way merge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/documents/{documentId}/ai-pref": { "get": { "operationId": "proveDocsGetDocumentAiPref", "summary": "Get per-document AI-check preference", "description": "Returns the calling user's AI-check preference override for the given document. `enable_ai_check` is `null` when no per-document override row exists (the effective setting falls back to the per-project default). Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "Document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The user's AI-check preference for this document.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_DocumentAiPref" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "proveDocsSetDocumentAiPref", "summary": "Set per-document AI-check preference", "description": "Upserts the calling user's AI-check preference override for the given document. The SP is idempotent — setting the same value twice is a no-op. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "Document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveDocs_DocumentAiPrefSetRequest" } } } }, "responses": { "200": { "description": "The updated AI-check preference record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveDocs_DocumentAiPref" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `enable_ai_check` (boolean) is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "proveDocsClearDocumentAiPref", "summary": "Clear per-document AI-check preference", "description": "Removes the calling user's per-document AI-check override row so the effective setting reverts to the per-user-per-project preference, then the project default. Idempotent — deleting a non-existent row returns `{ was_present: false }`. Requires an active Backbuild Prove entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "Document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Preference cleared (or was not present). `was_present` indicates whether an override existed before this call.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "was_present": { "type": "boolean", "description": "True if an override row existed and was deleted." } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FEATURE_DISABLED` — active Backbuild Prove entitlement required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/entitlement": { "get": { "operationId": "proveIndexGetEntitlement", "summary": "Get Backbuild Prove entitlement", "description": "Returns the organization's current Backbuild Prove subscription state (enabled, tier, status, included languages, add-ons). Any authenticated org member may call this endpoint without needing an active subscription — it is used by the UI to gate feature rendering. Returns a disabled stub when no subscription exists; returns `503` when the database is transiently unavailable.", "tags": [ "Prove, Science & Studio" ], "responses": { "200": { "description": "Entitlement record. `enabled: false` with `status: 'none'` when no active subscription exists.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_Entitlement" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — the database is transiently unavailable. Retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbprove/lean4/health": { "get": { "operationId": "proveIndexLean4Health", "summary": "Probe Lean 4 verification service health", "description": "Checks whether the platform's Lean 4 cross-validation service is reachable and responsive. Any authenticated org member may call this without an active subscription. The response is always `200` — the `status` field (`ok` or `error`) inside `data` conveys liveness; an `error` value means the service is unreachable or not configured. The `configured` flag distinguishes \"not provisioned\" from \"provisioned but unhealthy\".", "tags": [ "Prove, Science & Studio" ], "responses": { "200": { "description": "Health probe result. `status: 'error'` does NOT cause a non-2xx HTTP status — the outer envelope is always `success: true`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_Lean4HealthResult" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/languages": { "get": { "operationId": "proveIndexListLanguages", "summary": "List activated proof languages", "description": "Returns the set of proof languages activated for the caller's organization. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "responses": { "200": { "description": "List of language records for the organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_Language" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` — no active Backbuild Prove subscription. `BILLING_SUBSCRIPTION_PAST_DUE` — subscription is past due. `BILLING_SUBSCRIPTION_CANCELLED` — subscription has been cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — the database is transiently unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "proveIndexSetLanguage", "summary": "Activate or deactivate a proof language", "description": "Activates or deactivates a proof language for the caller's organization. `mode` defaults to `activate` when omitted. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_LanguageSetRequest" } } } }, "responses": { "200": { "description": "Language record after the activation/deactivation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_Language" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `language` is missing or exceeds 64 characters; `mode` is not `activate` or `deactivate`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED` — active subscription required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/issues": { "get": { "operationId": "proveIndexListIssues", "summary": "List proof issues for a project", "description": "Returns paginated proof issues (type errors, failing theorems, lint warnings) for the project, with optional filters by file path, language, and domain. Page/page_size pagination (default page 1, page_size 50). Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1).", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (default 50, max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "file_path", "in": "query", "required": false, "description": "Filter to issues in a specific source file path.", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Filter to issues for a specific proof language.", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "description": "Filter to issues in a specific proof domain.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of proof issues.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_Issue" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId` or query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/contracts": { "get": { "operationId": "proveIndexListContracts", "summary": "List proof contracts for a project", "description": "Returns the formal contracts (pre/post-conditions, invariants) associated with source files in the project, optionally filtered by `file_path`. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "file_path", "in": "query", "required": false, "description": "Filter to contracts defined in a specific source file.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of proof contracts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_Contract" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/third-party": { "get": { "operationId": "proveIndexListThirdPartyContracts", "summary": "List third-party contracts for a project", "description": "Returns third-party (external dependency) contracts registered for the project — formal specifications imported from upstream libraries or packages. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "List of third-party contract records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_Contract" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/dependency-tree": { "get": { "operationId": "proveIndexGetDependencyTree", "summary": "Get project proof dependency tree", "description": "Returns the directed dependency graph of theorems, lemmas, and axioms for the project. Nodes are the individual proof artifacts; edges represent `requires` / `imports` relationships. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Proof dependency tree (nodes + edges).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_DependencyTree" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/certifications": { "get": { "operationId": "proveIndexListCertifications", "summary": "List project certifications", "description": "Returns the certification bundles published to the project, ordered most recent first. A certification records a cryptographically signed snapshot of the project's proof state at a point in time. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "List of certification records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_Certification" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "proveIndexCreateCertification", "summary": "Create (publish) a certification", "description": "Publishes a new certification for the project by recording the signed bundle metadata. The bundle bytes must already be in storage (uploaded via the `upload-relay` endpoint). The request body carries the Ed25519 public key, signature, storage key, SHA-256 digest, file hashes, and theorem counts. A `bundle_published` notification is emitted to all Prove notification subscribers for the project. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_CertificationCreateRequest" } } } }, "responses": { "200": { "description": "Created certification record identifier.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the newly created certification." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId` or body validation failure (e.g. `ed25519_pubkey_hex` not 64 hex chars, missing required fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — a certification with this bundle SHA already exists for the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/certifications/upload-url": { "post": { "operationId": "proveIndexGetCertificationUploadUrl", "summary": "Get a bundle upload URL", "description": "Issues a pre-authenticated upload URL for a certification bundle. The caller provides the SHA-256 hex digest of the bundle; the server returns the relay upload URL and the storage key to use in the subsequent `certificationCreate` call. The upload must be completed via the corresponding `PUT` relay endpoint within the returned `expires_in` window (3600 seconds). Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bundle_sha256_hex" ], "additionalProperties": false, "properties": { "bundle_sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hex digest (64 lowercase hex chars) of the bundle to be uploaded." } } } } } }, "responses": { "200": { "description": "Upload slot issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "r2_key", "upload_url", "expires_in" ], "properties": { "r2_key": { "type": "string", "description": "Storage key to supply in the subsequent `certificationCreate` call." }, "upload_url": { "type": "string", "format": "uri", "description": "Relay upload URL. PUT the bundle bytes to this URL within the `expires_in` window." }, "expires_in": { "type": "integer", "description": "Seconds until the upload slot expires (3600)." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `bundle_sha256_hex` missing or not a 64-character hex digest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — the bundle storage binding is not configured or is temporarily inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbprove/projects/{projectId}/certifications/upload-relay/{sha}": { "put": { "operationId": "proveIndexUploadBundleRelay", "summary": "Upload a certification bundle via relay", "description": "Receives a `.tar.gz` certification bundle and writes it to storage after running these server-side checks in order: (1) SHA-256 digest verification against the URL `sha` parameter, (2) gzip magic-byte presence (first two bytes must be `0x1f 0x8b`), (3) PDF active-content marker scan on the first 5 MiB, (4) decompression-bomb guard (absolute expansion cap and 100:1 ratio cap), (5) suppression-list check. Payloads that fail any check are rejected with an appropriate `4xx` code. Bundles exceeding 50 MiB are rejected with `413`. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "sha", "in": "path", "required": true, "description": "Expected SHA-256 hex digest of the bundle (64 lowercase hex chars). The server rejects the upload if the received bytes do not match.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw `.tar.gz` bundle bytes. Maximum 50 MiB." } } } }, "responses": { "200": { "description": "Bundle written to storage.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "r2_key", "size_bytes" ], "properties": { "r2_key": { "type": "string", "description": "Storage key where the bundle was written." }, "size_bytes": { "type": "integer", "description": "Exact size of the accepted bundle in bytes." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId` or `sha`, empty body, SHA-256 mismatch, gzip magic absent, malformed gzip stream, or PDF active-content marker detected (`PDF_CONTAINS_JS_ACTION`). `UPLOAD_SUPPRESSED` — bundle hash matches the operator deny-list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — the bundle exceeds 50 MiB, or the gzip expands beyond the absolute cap, or the expansion ratio exceeds 100:1 (decompression-bomb guard).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — the bundle storage binding is not configured or is temporarily inaccessible, or the suppression-list service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbprove/projects/{projectId}/certifications/{certificationId}": { "delete": { "operationId": "proveIndexRevokeCertification", "summary": "Revoke a certification", "description": "Revokes a published certification. A revocation reason is REQUIRED and must describe the specific grounds. Revoked certifications are flagged on the public verification page. A `bundle_revoked` notification is emitted to all project notification subscribers. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "certificationId", "in": "path", "required": true, "description": "Certification identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revocation_reason" ], "additionalProperties": false, "properties": { "revocation_reason": { "type": "string", "minLength": 1, "description": "Human-readable reason for revoking this certification." } } } } } }, "responses": { "200": { "description": "Certification revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `certificationId` or `projectId`, or `revocation_reason` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project or lacks revoke permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/handoff-contracts": { "get": { "operationId": "proveIndexGetHandoffContracts", "summary": "Get handoff contract report", "description": "Generates a handoff contract report for the project: a structured, machine-readable summary of all proven contracts suitable for passing to an external system, audit, or release gate. Pass `include_unaudited=false` to exclude contracts that have not completed the audit workflow (defaults to including them). Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "include_unaudited", "in": "query", "required": false, "description": "Whether to include contracts in the `unaudited` proof class. Defaults to `true`.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Handoff contract report.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_HandoffContractReport" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/enable": { "post": { "operationId": "proveIndexEnableProject", "summary": "Enable Backbuild Prove for a project", "description": "Initializes Backbuild Prove on an existing project, creating the necessary database rows and default settings. Idempotent — calling it on an already-enabled project is a no-op. Requires an active Backbuild Prove subscription and membership in the project.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Project Prove enablement record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_ProjectEnableResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `projectId` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/source-tree": { "get": { "operationId": "proveIndexGetSourceTree", "summary": "Get project source file tree", "description": "Returns the hierarchical tree of registered source files for the project, including per-file metadata (language, theorem counts, coverage). Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Source file tree for the project.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_SourceTree" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/source/{filePath}": { "get": { "operationId": "proveIndexGetSourceFile", "summary": "Get a registered source file", "description": "Returns metadata for a registered source file, identified by its path within the project. Pass `include_content=true` to also stream the file's bytes from storage; the content is base64-encoded in the response. The file path is canonicalized server-side — path traversal sequences (e.g. `../`, null bytes, absolute paths) are rejected with `400 VALIDATION_ERROR`. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "filePath", "in": "path", "required": true, "description": "Relative path of the source file within the project (e.g. `src/Foo.lean`). The path is canonicalized server-side; traversal sequences are rejected.", "schema": { "type": "string", "minLength": 1, "maxLength": 4096 } }, { "name": "include_content", "in": "query", "required": false, "description": "When `true`, streams the source file bytes from storage and includes them in the response. Defaults to `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Source file metadata, optionally with content.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_SourceFile" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId` or `filePath` failed canonicalization (path traversal, null bytes, absolute path, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — file not registered, or file registered but the underlying storage object is absent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — the source-file storage binding is not configured or is temporarily inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbprove/projects/{projectId}/source": { "post": { "operationId": "proveIndexRegisterSourceFile", "summary": "Register a source file", "description": "Registers (or updates) a source file in the project's Prove catalog after the file has been uploaded to storage. The caller provides the storage key, SHA-256 digest, and optional symbol-level metadata derived from the language parser. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_SourceRegisterRequest" } } } }, "responses": { "200": { "description": "Source file registration record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_SourceFile" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`, or the request body failed validation (e.g. `sha256_hex` not a 64-char hex digest, `r2_key` missing).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/paired-documents/sync": { "post": { "operationId": "proveIndexSyncPairedDocuments", "summary": "Sync a paired-repository document manifest", "description": "Bulk-syncs the document manifest from a paired external repository into the platform's document catalog. The `org_id` is always derived from the authenticated session — the body must not include it. A manifest may contain up to 5 000 file entries. Each entry's `rel_path` is re-canonicalized server-side for path confinement. Pass `prune: true` to remove catalog entries for files absent from the manifest. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_PairedDocumentSyncRequest" } } } }, "responses": { "200": { "description": "Sync result with counts of inserted, updated, and optionally pruned entries.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_PairedDocumentSyncResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`, malformed body, `pairing_id` not a UUID, `files` array exceeds 5 000 entries, or a `rel_path` fails canonicalization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/governance/library": { "get": { "operationId": "proveIndexListGovernanceLibrary", "summary": "List governance theorem catalog", "description": "Returns the platform-wide governance theorem catalog, optionally filtered by `category`, `language`, or `compliance_framework`. Gated by the `governance` feature flag within the Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Filter by theorem category (e.g. `security`, `invariant`, `audit`).", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Filter by proof language (e.g. `lean4`, `coq`, `isabelle`).", "schema": { "type": "string" } }, { "name": "compliance_framework", "in": "query", "required": false, "description": "Filter by compliance framework (e.g. `pci_dss`, `iso27001`, `soc2`, `hipaa`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of governance theorem catalog entries.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_GovernanceTheorem" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED` — active Prove subscription with the `governance` feature flag required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `governance` feature is not enabled on the organization's plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/governance/library/{id}": { "get": { "operationId": "proveIndexGetGovernanceTheorem", "summary": "Get a governance theorem", "description": "Returns a single governance theorem from the platform catalog, including its full formal specification, compliance mappings, and associated proof artifacts. Gated by the `governance` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Governance theorem catalog identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Governance theorem detail.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_GovernanceTheorem" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `governance` feature is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/governance": { "get": { "operationId": "proveIndexListProjectGovernance", "summary": "List governance theorems attached to a project", "description": "Returns the governance theorem attachments for the project, including the severity override and current compliance status. Gated by the `governance` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "List of governance theorem attachments.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_GovernanceAttachment" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `governance` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "proveIndexAttachGovernanceTheorem", "summary": "Attach a governance theorem to a project", "description": "Attaches a governance theorem from the platform catalog to the project. An optional `severity_override` controls whether violations are reported as `warning`, `error`, or `ignored`; the catalog default is used when omitted. Gated by the `governance` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_GovernanceAttachRequest" } } } }, "responses": { "200": { "description": "Created governance attachment record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_GovernanceAttachment" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`, missing `governance_theorem_id`, or `severity_override` not one of `warning`, `error`, `ignored`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `governance` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — project or governance theorem not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/governance/{attachmentId}": { "delete": { "operationId": "proveIndexDetachGovernanceTheorem", "summary": "Detach a governance theorem from a project", "description": "Removes a governance theorem attachment from the project. Gated by the `governance` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "attachmentId", "in": "path", "required": true, "description": "Governance attachment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Governance theorem detached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `governance` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/governance/violations": { "get": { "operationId": "proveIndexListGovernanceViolations", "summary": "List governance violations for a project", "description": "Returns paginated governance violations — instances where the project's proof state does not satisfy an attached governance theorem. Optionally filtered by `attachment_id` and whether to include resolved violations. Gated by the `violations` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1).", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (default 50, max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "attachment_id", "in": "query", "required": false, "description": "Filter to violations for a specific governance attachment (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_resolved", "in": "query", "required": false, "description": "When `true`, includes violations that have already been resolved or suppressed. Defaults to `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Paginated list of governance violations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "violations": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_GovernanceViolation" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `violations` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/governance/violations/{id}/suppress": { "post": { "operationId": "proveIndexSuppressGovernanceViolation", "summary": "Suppress (accept exception for) a governance violation", "description": "Marks a governance violation as suppressed (accepted exception), recording the justification reason. Suppressed violations are excluded from default violation counts but remain in the audit trail. A `reason` of 1–2000 characters is required. Gated by the `violations` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "id", "in": "path", "required": true, "description": "Governance violation identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Justification for accepting this governance exception." } } } } } }, "responses": { "200": { "description": "Violation suppressed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid violation `id` or `reason` missing/empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `violations` feature is not enabled. `FORBIDDEN` — caller lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/proof-class": { "post": { "operationId": "proveIndexSetProofClass", "summary": "Set proof class for theorems", "description": "Bulk-updates the proof class of theorems to `unaudited`, `audited`, or `public_api`. Exactly one of `theorem_ids` (array of UUIDv7s) or `theorem_names` (array of strings) must be supplied. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_SetProofClassRequest" } } } }, "responses": { "200": { "description": "Proof class update result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_SetProofClassResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`, neither `theorem_ids` nor `theorem_names` supplied, or `proof_class` is not one of the allowed values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project or lacks write permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/runs": { "get": { "operationId": "proveIndexListVerificationRuns", "summary": "List verification runs for a project", "description": "Returns paginated verification run records for the project, most recent first. Each run captures the kernel's execution: theorems checked, time taken, outcome, and per-file coverage snapshot. Page/page_size pagination. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1).", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Paginated list of verification run records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_VerificationRun" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/settings": { "get": { "operationId": "proveIndexGetProjectSettings", "summary": "Get project Prove settings", "description": "Returns the Prove-specific settings stored for the project (e.g. default proof language, auto-run policy, notification thresholds). Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Project Prove settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_ProjectSettings" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "proveIndexUpdateProjectSettings", "summary": "Update project Prove settings", "description": "Updates the Prove-specific settings for the project. The `settings` object is merged with the existing settings. Requires an active Backbuild Prove subscription and project admin access.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "settings" ], "additionalProperties": false, "properties": { "settings": { "type": "object", "additionalProperties": true, "description": "Partial settings object to merge into the project's Prove settings." } } } } } }, "responses": { "200": { "description": "Updated project Prove settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_ProjectSettings" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `settings` object is missing or not an object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a project admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/signing-key": { "get": { "operationId": "proveIndexGetActiveSigningKey", "summary": "Get the active signing key", "description": "Returns the organization's currently active Ed25519 signing key (public key hex and metadata). Private key material is never stored on the platform — only the public key is returned. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "responses": { "200": { "description": "Active signing key record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_SigningKey" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — no active signing key is registered for the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "proveIndexCreateSigningKey", "summary": "Register a new signing key", "description": "Registers a new active Ed25519 signing key for the organization. Only one active key is permitted at a time — if an active key already exists the call returns an error. Retire or revoke the existing key first. Private key material is never accepted or stored. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_SigningKeyCreateRequest" } } } }, "responses": { "200": { "description": "Registered signing key record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_SigningKey" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `public_key_hex` is missing or not a 64-character hex digest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — an active signing key already exists for this organization. Retire or revoke the current key before registering a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/signing-keys": { "get": { "operationId": "proveIndexListSigningKeys", "summary": "List all signing keys", "description": "Returns the full key history for the organization: active, retired, and revoked signing keys. Useful for audit trails and verifying which key signed a specific certification. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "responses": { "200": { "description": "List of all signing key records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_SigningKey" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/signing-key/{id}/retire": { "post": { "operationId": "proveIndexRetireSigningKey", "summary": "Retire a signing key (normal rotation)", "description": "Retires a signing key as part of normal rotation. Retired keys' past signatures remain valid — downstream verifiers see them as signed by a retired (not compromised) key. No reason is required because retirement is informational. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Signing key identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signing key retired.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_SigningKey" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid signing key `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — the key is already retired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/signing-key/{id}/revoke": { "post": { "operationId": "proveIndexRevokeSigningKey", "summary": "Revoke a signing key (compromise response)", "description": "Revokes a signing key in response to a suspected compromise. A `revocation_reason` of 10–2000 characters is REQUIRED and must describe the actual compromise event. Revoking a key flags all certifications previously signed by that key as `SIGNING KEY COMPROMISED` on their public verification pages. A `signing_key_revoked` notification is emitted to all Prove subscribers in the organization. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Signing key identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_SigningKeyRevokeRequest" } } } }, "responses": { "200": { "description": "Signing key revoked. `bundles_affected` is the count of certifications now flagged as compromised.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "bundles_affected": { "type": "integer", "description": "Number of certifications that were signed by this key and are now flagged as compromised." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `id` or `revocation_reason` does not meet the 10-character minimum.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — the key is already revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/lean4-reports": { "get": { "operationId": "proveIndexListLean4Reports", "summary": "List Lean 4 verification reports", "description": "Returns Lean 4 verifier reports for the project, with optional filtering by `filter` (e.g. `errors`, `warnings`, `all`) and `file_path`. Gated by the `lean4` feature flag within the Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "filter", "in": "query", "required": false, "description": "Narrow the report set (e.g. `errors`, `warnings`, `all`). Defaults to `all`.", "schema": { "type": "string" } }, { "name": "file_path", "in": "query", "required": false, "description": "Restrict to reports for a specific source file.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of Lean 4 verifier reports.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_Lean4Report" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `lean4` feature is not enabled on the subscription. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/reports/coverage-over-time": { "get": { "operationId": "proveIndexReportCoverageOverTime", "summary": "Proof coverage over time report", "description": "Returns a time-series of proof coverage metrics (proven, failing, total theorems) over the specified lookback window (`days`, default 30). Gated by the `reports` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "days", "in": "query", "required": false, "description": "Lookback window in days (default 30).", "schema": { "type": "integer", "minimum": 1, "default": 30 } } ], "responses": { "200": { "description": "Coverage time-series data points.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_CoverageTimeSeries" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `reports` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/reports/domain-breakdown": { "get": { "operationId": "proveIndexReportDomainBreakdown", "summary": "Proof domain breakdown report", "description": "Returns a breakdown of theorem coverage grouped by proof domain (e.g. `security`, `concurrency`, `memory_safety`). Gated by the `reports` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Domain breakdown data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_DomainBreakdownItem" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `reports` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/reports/language-breakdown": { "get": { "operationId": "proveIndexReportLanguageBreakdown", "summary": "Proof language breakdown report", "description": "Returns a breakdown of theorem coverage grouped by proof language. Gated by the `reports` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Language breakdown data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_LanguageBreakdownItem" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `reports` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/reports/verification-runs": { "get": { "operationId": "proveIndexReportVerificationRunsTimeseries", "summary": "Verification runs time-series report", "description": "Returns a daily time-series of verification run counts and average duration over the specified lookback window. Gated by the `reports` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "days", "in": "query", "required": false, "description": "Lookback window in days (default 30).", "schema": { "type": "integer", "minimum": 1, "default": 30 } } ], "responses": { "200": { "description": "Verification runs time-series.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_CoverageTimeSeries" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `reports` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/compliance": { "get": { "operationId": "proveIndexGetComplianceDashboard", "summary": "Get compliance dashboard", "description": "Returns the project's compliance posture across all attached governance frameworks: overall score, per-framework control status, and top violations. Gated by the `compliance` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Compliance dashboard data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_ComplianceDashboard" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `compliance` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/search": { "post": { "operationId": "proveIndexSearchTheorems", "summary": "Search theorems", "description": "Full-text and semantic search over theorems. `query` must be 2–500 characters. `scope` limits the search to `all` (default), `project` (requires `project_id`), `system` (platform-provided theorems), or `governance` catalog. Results are returned with limit/offset pagination (default limit 50, max 200). Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_SearchRequest" } } } }, "responses": { "200": { "description": "Search results with pagination.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "results", "pagination" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_SearchResult" } }, "pagination": { "type": "object", "required": [ "total", "limit", "offset", "has_more" ], "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "truncated": { "type": "boolean", "description": "Whether the result set was truncated to the requested limit." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `query` is missing or less than 2 characters; `scope` is invalid; `project` scope requires `project_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/proof-printout": { "get": { "operationId": "proveIndexGetProofPrintout", "summary": "Get proof printout", "description": "Returns the structured proof printout for the project: a canonical, signed-ready listing of theorems filtered by proof class (`all`, `verified`, `audited`) and optionally a specific `file_path`. The printout is used as the attestation payload for signing. Gated by the `proof-printout` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "filter", "in": "query", "required": false, "description": "Proof class filter: `all` (default), `verified`, or `audited`.", "schema": { "type": "string", "enum": [ "all", "verified", "audited" ], "default": "all" } }, { "name": "file_path", "in": "query", "required": false, "description": "Restrict to theorems in a specific source file.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Proof printout data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_ProofPrintout" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `proof-printout` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/proof-printout/signature": { "get": { "operationId": "proveIndexGetProofPrintoutSignature", "summary": "Get proof printout attestation signature", "description": "Returns the latest stored Ed25519 attestation signature for the project's proof printout, optionally filtered by `content_sha256_hex` to retrieve the signature for a specific printout snapshot. Gated by the `proof-printout` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "content_sha256_hex", "in": "query", "required": false, "description": "Retrieve the signature for a specific printout content hash (64 lowercase hex chars).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "responses": { "200": { "description": "Attestation signature record, or null if none exists for the requested snapshot.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_ProofPrintoutSignature" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `proof-printout` feature is not enabled. `FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "proveIndexStoreProofPrintoutSignature", "summary": "Store a proof printout attestation signature", "description": "Stores an Ed25519 attestation signature computed by the CLI over a canonical proof printout payload. Requires an active org signing key (`prove.publish` permission enforced inside the stored procedure). The public key referenced must match the organization's registered active key. Gated by the `proof-printout` feature flag.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_ProofPrintoutSignRequest" } } } }, "responses": { "200": { "description": "Attestation signature stored.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_ProofPrintoutSignature" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid UUID, `content_sha256_hex` not 64 hex chars, `signature_hex` not 128 hex chars, or `filter` not one of `all`, `verified`, `audited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FEATURE_DISABLED` — the `proof-printout` feature is not enabled. `FORBIDDEN` — caller lacks `prove.publish` permission or the referenced public key does not match the active signing key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — no active signing key is registered for the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/notification-settings": { "get": { "operationId": "proveIndexGetNotificationSettings", "summary": "Get project notification settings", "description": "Returns the notification channel configuration and event filters for the project. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Notification settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_NotificationSettings" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "proveIndexUpdateNotificationSettings", "summary": "Update project notification settings", "description": "Updates the notification channel configuration and event filters for the project. All fields are optional — only provided fields are updated. `cooldown_minutes` controls the minimum gap between repeated notifications for the same event type (0–1440). Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_NotificationSettingsUpdateRequest" } } } }, "responses": { "200": { "description": "Updated notification settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_NotificationSettings" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `cooldown_minutes` out of range [0, 1440] or `min_severity` invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project or lacks settings-write permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/webhooks": { "get": { "operationId": "proveIndexListWebhooks", "summary": "List Prove webhooks", "description": "Returns the Prove outbound webhook registrations for the organization, optionally filtered by `project_id`. Webhook secrets are never returned — only metadata is exposed. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Filter to webhooks scoped to a specific project (UUIDv7). Omit for all organization-level webhooks.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of webhook registrations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_Webhook" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "proveIndexCreateWebhook", "summary": "Register a Prove webhook", "description": "Registers a new outbound webhook for Prove events. The `url` must be HTTPS. The `secret` (16–256 chars) is stored encrypted and used to sign outgoing deliveries — it is never returned after registration. `event_types` controls which Prove event types trigger delivery; omit to receive all events. `project_id` scopes the webhook to a single project; omit for org-level delivery. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_WebhookCreateRequest" } } } }, "responses": { "200": { "description": "Webhook registration record. The plaintext secret is not returned — store it before calling this endpoint.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_Webhook" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `url` is not HTTPS, `secret` is fewer than 16 characters or more than 256 characters, or `project_id` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — webhook secrets cannot be encrypted due to a server-side configuration issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbprove/webhooks/{id}": { "delete": { "operationId": "proveIndexDeleteWebhook", "summary": "Delete a Prove webhook", "description": "Permanently deletes a Prove webhook registration. Deliveries in flight at the time of deletion may still be attempted once. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/webhooks/{id}/rotate-secret": { "post": { "operationId": "proveIndexRotateWebhookSecret", "summary": "Rotate a webhook secret", "description": "Rotates the signing secret for a Prove webhook with a grace-overlap window. The new secret replaces the current one; the current secret is kept as a secondary for `grace_days` (1–30, default 7) so in-flight deliveries and receivers being rolled forward can still verify against either secret. If `secret` is omitted, the server generates a fresh 64-character base64url secret. The plaintext new secret is returned exactly once in the response — it cannot be recovered afterward.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_WebhookRotateRequest" } } } }, "responses": { "200": { "description": "Secret rotated. The plaintext `secret` is returned exactly once.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/ProveIndex_Webhook" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "The new plaintext webhook signing secret. Present exactly once in this response; store it immediately." } } } ] } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid webhook `id`, `secret` less than 16 or more than 256 characters, or `grace_days` out of range [1, 30].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — webhook secrets cannot be encrypted due to a server-side configuration issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbprove/projects/{projectId}/hypotheses": { "post": { "operationId": "proveIndexRegisterHypothesis", "summary": "Register a hypothesis", "description": "Registers a named hypothesis with its discharge obligations, `\\impliedfrom` links, and `\\dischargedby` declarations. `source_file_path` is canonicalized server-side for path confinement. `obligations` carries the structured formal conditions that must be discharged for the hypothesis to be promoted to a theorem. `implied_from` lists hypothesis labels that imply this one. `dischargedby` can reference existing labels or forward references (by kind + name). Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_HypothesisRegisterRequest" } } } }, "responses": { "200": { "description": "Hypothesis registered with counts of inserted obligations and links.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_HypothesisRegisterResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`, missing required fields, `source_file_path` failed canonicalization (path traversal, null bytes, absolute path), or arrays exceed their limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/theorems/with-dischargedby": { "post": { "operationId": "proveIndexRegisterTheoremWithDischargedby", "summary": "Record \\dischargedby declarations on a theorem", "description": "Records explicit `\\dischargedby` declarations on a freshly registered theorem and triggers auto-discharge of any hypothesis obligation whose forward reference (kind + name) now resolves to this theorem. Returns the counts of auto-discharged and explicitly-discharged obligations. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveIndex_TheoremWithDischargedByRequest" } } } }, "responses": { "200": { "description": "Discharge records stored.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_TheoremWithDischargedByResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`, `theorem_id` not a UUID, missing `conclusion_term`, or `dischargedby` array exceeds 1024 entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/check-promotions": { "post": { "operationId": "proveIndexCheckPromotions", "summary": "Run hypothesis-to-theorem promotion engine", "description": "Runs the cascading promotion engine for the project: any hypothesis whose obligations are all discharged is promoted to a theorem, which may in turn discharge obligations on other hypotheses. Returns the list of promoted hypothesis IDs and the total count. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Promotion engine result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_CheckPromotionsResult" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/hypothesis-status": { "get": { "operationId": "proveIndexGetHypothesisStatus", "summary": "Get hypothesis discharge status graph", "description": "Returns the full hypothesis/obligation/implication/promotion graph for the project: each hypothesis with its discharge obligations, current promotion state, and `\\impliedfrom`/`\\dischargedby` edges. Used by the dashboard to render the hypothesis discharge state. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Hypothesis status graph.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_HypothesisStatusGraph" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbprove/projects/{projectId}/dashboard": { "get": { "operationId": "proveIndexGetDashboard", "summary": "Get project Prove dashboard", "description": "Returns aggregated proof coverage metrics for the project dashboard: total theorems, proven/failing/partial counts, coverage percentage, recent run history, and top-level domain breakdown. Requires an active Backbuild Prove subscription.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Dashboard metrics for the project.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveIndex_Dashboard" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid `projectId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`BILLING_SUBSCRIPTION_REQUIRED` / `BILLING_SUBSCRIPTION_PAST_DUE` / `BILLING_SUBSCRIPTION_CANCELLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/prove/projects/{projectId}/dag/register": { "post": { "operationId": "proveProjectsRegisterNode", "summary": "Register a theorem into the project DAG", "description": "Registers a theorem node into the caller's project DAG. The body mirrors the `bbprove-serializer::NodeRequest` wire format (§3.1 of the DAG state-cache spec). `orgId` and `projectId` are derived from the JWT claim and the URL path; they are never accepted in the request body (`.strict()` rejects unknown top-level keys with `VALIDATION_ERROR`). The project is pre-flight validated before dispatching to the project-serializer Durable Object — an unknown or inactive project, or a project the caller cannot access, is reported as `403`/`404`. Requires an active Backbuild Prove subscription and the `dag-project` feature entitlement. `prove.write` permission on the project is enforced inside the DO-backed stored procedure.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveProjects_RegisterNodeRequest" } } } }, "responses": { "200": { "description": "Theorem admitted. The admitted DAG node is returned under `data.node`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveProjects_RegisterNodeResponse" }, "requestId": { "type": "string", "format": "uuid", "description": "Correlation id for tracing." } } } ] } } } }, "400": { "description": "`INVALID_JSON` — the request body is not parseable JSON or is not a JSON object. `VALIDATION_ERROR` — a required field is missing, a field fails its type/bounds/enum constraint, or an unknown top-level key is present (strict schema).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller does not have `prove.write` permission on this project, or the project pre-flight access check denied access. `BILLING_SUBSCRIPTION_REQUIRED` — the organization has no active Backbuild Prove subscription. `BILLING_TIER_UPGRADE_REQUIRED` — the `dag-project` feature requires a higher plan tier. `BILLING_ADDON_REQUIRED` — the SQL Verification add-on is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the project does not exist, is inactive, or is not accessible to the caller (uniform 404; no existence oracle).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a node with the same name already exists in the project DAG. `CONCURRENT_MODIFICATION` — a concurrent write to the same DAG cell created a contention conflict; the caller should re-fetch and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "description": "`NOT_IMPLEMENTED` — the project-serializer Durable Object is not yet wired for this environment (Phase-3 scaffolding). The validation and authorization envelope is exercised; only the final DO dispatch is pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — the project-serializer Durable Object binding is not configured for this environment, or the DO is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/prove/projects/{projectId}/dag/manifest": { "get": { "operationId": "proveProjectsGetDagManifest", "summary": "Get the project DAG manifest", "description": "Returns the current project DAG manifest (`headHash`, `nodeCount`, `lastFlushAt`, and optionally the node list). When the `since` query parameter is supplied the response includes only nodes admitted after that head hash (incremental sync). Project members with `prove.read` permission can call this endpoint. Requires an active Backbuild Prove `dag-project` entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "since", "in": "query", "required": false, "description": "Optional DAG head hash. When supplied, only nodes admitted after this hash are returned (incremental sync). Omit to receive the full manifest.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current project DAG manifest.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveProjects_DagManifest" }, "requestId": { "type": "string", "format": "uuid" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller does not have `prove.read` permission on this project. `BILLING_SUBSCRIPTION_REQUIRED`, `BILLING_TIER_UPGRADE_REQUIRED`, or `BILLING_ADDON_REQUIRED` — entitlement check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the project does not exist, is inactive, or is not accessible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "description": "`NOT_IMPLEMENTED` — the project-serializer Durable Object is not yet wired (Phase-3 scaffolding).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — the project-serializer Durable Object binding is not configured or is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/prove/projects/{projectId}/dag/node/{name}": { "get": { "operationId": "proveProjectsGetDagNode", "summary": "Get a single DAG node by name", "description": "Returns a single DAG node by its theorem name. The `name` path segment is captured greedily so multi-segment names containing `/` (e.g. `algebra/group/group_assoc`) round-trip correctly. The name must match the §3.1 byte set (`a-zA-Z0-9/_:.-`), be at most 256 UTF-8 bytes, and may not contain `.` or `..` path segments. Project members with `prove.read` permission can call this endpoint. Requires an active Backbuild Prove `dag-project` entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "name", "in": "path", "required": true, "description": "Theorem name. Must match the §3.1 byte set (`a-zA-Z0-9/_:.-`), be at most 256 UTF-8 bytes, and must not contain `.` or `..` path segments. Multi-segment names separated by `/` are captured as a single parameter.", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[a-zA-Z0-9/_:.\\-]+$" } } ], "responses": { "200": { "description": "The DAG node record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveProjects_DagNode" }, "requestId": { "type": "string", "format": "uuid" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the `name` path parameter does not match the §3.1 byte set, exceeds 256 UTF-8 bytes, or contains a `.` or `..` segment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller does not have `prove.read` permission on this project. Entitlement errors: `BILLING_SUBSCRIPTION_REQUIRED`, `BILLING_TIER_UPGRADE_REQUIRED`, `BILLING_ADDON_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the project or the named node does not exist, or is not accessible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "description": "`NOT_IMPLEMENTED` — the project-serializer Durable Object is not yet wired (Phase-3 scaffolding).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — the project-serializer Durable Object binding is not configured or is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/prove/projects/{projectId}/dag/sync": { "post": { "operationId": "proveProjectsSyncDag", "summary": "Force an immediate DAG state flush", "description": "Triggers an operator-initiated immediate flush of the project serializer's dirty in-memory state to durable storage. Project-admin (or org-admin/owner) only — enforced by the `prove.write` permission check and an org-admin role check inside the stored procedure. A non-admin member with `prove.read` will receive `403`. Requires an active Backbuild Prove `dag-project` entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Sync completed (or state was already clean — `flushed: false`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveProjects_SyncResponse" }, "requestId": { "type": "string", "format": "uuid" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller lacks project-admin (or org-admin/owner) access. Entitlement errors: `BILLING_SUBSCRIPTION_REQUIRED`, `BILLING_TIER_UPGRADE_REQUIRED`, `BILLING_ADDON_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the project does not exist, is inactive, or is not accessible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a concurrent flush is already in progress; retry after the current flush completes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "description": "`NOT_IMPLEMENTED` — the project-serializer Durable Object is not yet wired (Phase-3 scaffolding).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — the project-serializer Durable Object binding is not configured or is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/prove/projects/{projectId}/dag/deverify-all": { "post": { "operationId": "proveProjectsDeverifyAll", "summary": "Bulk-reset all project theorems to provisional", "description": "Bulk-flips every theorem in the project DAG back to provisional status and enqueues a fresh kernel replay pass. The optional `reason` field is appended to the audit row. Project-admin (or org-admin/owner) only — the `isAdmin` flag derived from the JWT is forwarded to the DO for enforcement. A non-admin member will receive `403`. The request body is optional; an absent `Content-Type` or empty body is treated as `{}`. A non-object body (e.g. an array or scalar) is rejected with `INVALID_JSON`. Requires an active Backbuild Prove `dag-project` entitlement.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveProjects_DeverifyAllRequest" } } } }, "responses": { "200": { "description": "Deverification completed. `affected` is the number of nodes reset to provisional.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveProjects_DeverifyAllResponse" }, "requestId": { "type": "string", "format": "uuid" } } } ] } } } }, "400": { "description": "`INVALID_JSON` — the request body is not a JSON object (e.g. it is an array or scalar). `VALIDATION_ERROR` — `reason` exceeds 2000 characters or an unknown key is present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller is not a project-admin, org-admin, or org-owner. Entitlement errors: `BILLING_SUBSCRIPTION_REQUIRED`, `BILLING_TIER_UPGRADE_REQUIRED`, `BILLING_ADDON_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the project does not exist, is inactive, or is not accessible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "description": "`NOT_IMPLEMENTED` — the project-serializer Durable Object is not yet wired (Phase-3 scaffolding).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — the project-serializer Durable Object binding is not configured or is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/prove/connect": { "get": { "operationId": "proveProjectsConnectWebSocket", "summary": "Open a Prove session WebSocket", "description": "Upgrades the connection to a WebSocket for a Backbuild Prove kernel session. The request must carry an `Upgrade: websocket` header. Authentication is handled inside the ProveControllerDO after the upgrade. Browser clients must supply a valid `Origin` header matching the platform's allowed origin list; CLI clients without an `Origin` header are accepted. Each call mints a fresh server-generated session identifier — clients never supply their own. The negotiated sub-protocol is `prove-v1`.", "tags": [ "Prove, Science & Studio" ], "security": [], "parameters": [ { "name": "Upgrade", "in": "header", "required": true, "description": "Must be `websocket`. Any other value returns `426 Upgrade Required`.", "schema": { "type": "string", "enum": [ "websocket" ] } } ], "responses": { "101": { "description": "WebSocket upgrade successful. The connection is handed off to the ProveControllerDO for the kernel session." }, "403": { "description": "Origin not allowed — the request came from a browser with an `Origin` header that is not on the platform's allowed origin list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveProjects_ProveSimpleError" } } } }, "426": { "description": "Upgrade Required — the `Upgrade: websocket` header was absent or did not equal `websocket`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveProjects_ProveSimpleError" } } } }, "500": { "description": "An unexpected error occurred while establishing the WebSocket connection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveProjects_ProveSimpleError" } } } }, "503": { "description": "The Prove controller service is not configured for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveProjects_ProveSimpleError" } } } } } } }, "/prove/health": { "get": { "operationId": "proveProjectsHealth", "summary": "Prove service health check", "description": "Returns a simple liveness response for the Backbuild Prove service. Not authenticated; always returns `200` with `status: healthy` when the Worker is up.", "tags": [ "Prove, Science & Studio" ], "security": [], "responses": { "200": { "description": "Service is healthy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveProjects_HealthResponse" } } } } } } }, "/prove/info": { "get": { "operationId": "proveProjectsInfo", "summary": "Prove service capability information", "description": "Returns static metadata about the Backbuild Prove service: version, supported languages, protocol details, primitive rule count, and connection limits. Not authenticated; the response is static and does not reveal per-tenant state.", "tags": [ "Prove, Science & Studio" ], "security": [], "responses": { "200": { "description": "Service capability information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveProjects_InfoResponse" } } } } } } }, "/v1/verify/{id}": { "get": { "operationId": "proveSystemVerifyBundle", "summary": "Verify a proof certificate bundle", "description": "Public, unauthenticated endpoint for verifying a Backbuild Prove proof-certificate bundle by its identifier. Returns a cryptographic verification verdict: the bundle's Ed25519 signature is replayed against the canonical manifest bytes and the signing key is checked against the operator-managed trusted-issuer registry before `verified: true` is reported. A revoked bundle is always `verified: false` regardless of signature validity. When the verifier has not been enabled by the operator, every request returns `503 VERIFICATION_OFFLINE` — the service never advertises a verdict it has not computed. Rate-limited to 60 requests per minute per IP (IPv6 addresses are bucketed to /64). Requires no authentication (`security: []`).", "tags": [ "Prove, Science & Studio" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proof certificate bundle identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Verification result. `verification.verified` is `true` only when the signature is valid AND the signing key is in the trusted-issuer registry AND the bundle has not been revoked. Check `verification.reason` for the specific outcome.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveSystem_BundleVerifyResult" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `id` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — no bundle with this identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — the IP has exceeded 60 requests per minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`VERIFICATION_OFFLINE` — the proof verifier is not currently enabled. This is NOT a transient error — the operator has not yet provisioned the trusted-issuer key registry. Retry only after the operator has enabled the verifier. Also returned when the rate-limiter service is unavailable (fail-closed) or the request arrived without a Cloudflare-provided IP header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/verify/binary": { "post": { "operationId": "proveSystemVerifyBinary", "summary": "Match a binary against the proof certificate catalog", "description": "Public, unauthenticated endpoint. Accepts either a JSON body with a pre-computed `sha256_hex` or a raw binary upload (`application/octet-stream`, max 50 MB). Returns all proof certificate bundles whose `bundle_sha256_hex` matches the supplied digest. An empty `matches` array means no published bundle records this binary's hash — it does not indicate the binary is untrustworthy. Subject to the same operator-enable gate and IP rate-limit as `GET /v1/verify/{id}`. Requires no authentication (`security: []`).", "tags": [ "Prove, Science & Studio" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProveSystem_BinaryVerifyJsonRequest" }, "description": "Preferred mode — supply the pre-computed SHA-256 hex digest without uploading the binary." }, "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw binary bytes. Maximum size is 50 MB. The server computes the SHA-256 digest." } } } }, "responses": { "200": { "description": "Lookup complete. `matched` is `true` when at least one bundle record contains this binary's hash.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProveSystem_BinaryVerifyResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — neither a valid `sha256_hex` (64-character hex) nor an octet-stream body was supplied. Also returned for an empty octet-stream body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — the uploaded binary exceeds 50 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — IP rate limit exceeded (60 req/min).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`VERIFICATION_OFFLINE` — the proof verifier is not currently enabled. Also returned when the rate-limiter service is unavailable (fail-closed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/billing": { "get": { "operationId": "billingGetOverview", "summary": "Get billing overview", "description": "Returns the billing overview for the authenticated organization, including subscription state, payment methods, and credit balance. Requires owner or admin role within the org; members without that role receive `403 FORBIDDEN`.", "tags": [ "Billing & Subscriptions" ], "responses": { "200": { "description": "Billing overview for the organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_Overview" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks owner or admin role within the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billing/subscription-status": { "get": { "operationId": "billingGetSubscriptionStatus", "summary": "Poll subscription activation status", "description": "Returns whether the organization's subscription has been activated. Intended for short-polling after Stripe Checkout redirect to confirm the Stripe webhook has been processed (typically called every 3 s for up to 2 min).", "tags": [ "Billing & Subscriptions" ], "responses": { "200": { "description": "Current activation state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_SubscriptionStatus" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billing/client-config": { "get": { "operationId": "billingGetClientConfig", "summary": "Get Stripe client configuration", "description": "Returns the Stripe publishable key required to initialize the Stripe.js client on the frontend. Returns `503 CHECKOUT_FAILED` if Stripe is not configured for the deployment.", "tags": [ "Billing & Subscriptions" ], "responses": { "200": { "description": "Stripe client configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_ClientConfig" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`CHECKOUT_FAILED` — Stripe is not configured for this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/billing/payment-methods": { "get": { "operationId": "billingListPaymentMethods", "summary": "List saved payment methods", "description": "Returns all saved Stripe payment methods for the authenticated organization.", "tags": [ "Billing & Subscriptions" ], "responses": { "200": { "description": "List of saved payment methods.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Billing_PaymentMethod" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "billingUpsertPaymentMethod", "summary": "Upsert a payment method", "description": "Records a Stripe payment method (`pm_*`) for the organization. The API verifies the payment method belongs to this organization's Stripe customer before writing; a cross-customer or unknown `pm_*` returns `400 PAYMENT_METHOD_NOT_OWNED`. All `pm_*` and billing-address string fields are capped at Stripe's documented field lengths.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_PaymentMethodUpsertRequest" } } } }, "responses": { "200": { "description": "Payment method upserted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_PaymentMethod" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` (invalid body fields), `PAYMENT_METHOD_NOT_OWNED` (the `pm_*` id does not belong to this org's Stripe customer or cannot be found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billing/credits": { "get": { "operationId": "billingGetCredits", "summary": "Get credit balance", "description": "Returns the current AI credit balance for the authenticated organization.", "tags": [ "Billing & Subscriptions" ], "responses": { "200": { "description": "Credit balance.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_CreditBalance" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billing/usage": { "get": { "operationId": "billingGetUsage", "summary": "Get billable usage summary", "description": "Returns billable usage rollup for the authenticated organization. When `env_id` is absent or `all`, the global aggregate across all environments is returned. The `window` parameter controls the time range (default `30d`).", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "env_id", "in": "query", "required": false, "description": "Environment UUID to scope usage to, or the literal `all` (default) for a global aggregate across all environments. Any other non-UUID value returns `400 VALIDATION_ERROR`.", "schema": { "type": "string" } }, { "name": "window", "in": "query", "required": false, "description": "Aggregation window. One of `24h`, `7d`, `30d` (default), `90d`, `all`.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d", "all" ], "default": "30d" } } ], "responses": { "200": { "description": "Usage summary.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_UsageSummary" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `env_id` is not a UUID or `all`; `window` is not one of the allowed values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billing/subscriptions": { "get": { "operationId": "billingListSubscriptions", "summary": "List subscriptions", "description": "Returns the organization's subscriptions with optional status filter and offset pagination. Default limit 25, max 100.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by subscription status. Must be one of the canonical values matching the underlying platform subscription state.", "schema": { "type": "string", "enum": [ "active", "trialing", "past_due", "canceled", "incomplete", "paused" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip for pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of subscriptions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Billing_Subscription" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "billingCreateSubscription", "summary": "Create a subscription", "description": "Creates a new subscription for the authenticated organization using a Stripe payment method. All Stripe identifier and billing-address fields are bounded at Stripe's documented field lengths.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_SubscriptionCreateRequest" } } } }, "responses": { "201": { "description": "Subscription created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_Subscription" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billing/subscriptions/{subscriptionId}": { "put": { "operationId": "billingUpdateSubscription", "summary": "Update a subscription", "description": "Updates an existing subscription's plan, seat count, or cancellation scheduling. At least one body field must be supplied. Returns `404 NOT_FOUND` when the subscription does not exist or belongs to another organization.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "description": "Subscription identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_SubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Updated subscription record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_Subscription" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (malformed `subscriptionId`), `VALIDATION_ERROR` (invalid body fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — subscription not found or belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billing/invoices": { "get": { "operationId": "billingListInvoices", "summary": "List invoices", "description": "Returns invoices for the authenticated organization with optional status and date-range filters. Default limit 25, max 100.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by invoice status.", "schema": { "type": "string", "enum": [ "draft", "open", "paid", "uncollectible", "void" ] } }, { "name": "from_date", "in": "query", "required": false, "description": "Inclusive start of the invoice date range (ISO 8601 datetime).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date", "in": "query", "required": false, "description": "Inclusive end of the invoice date range (ISO 8601 datetime).", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of invoices to return (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of invoices to skip for pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of invoices.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Billing_Invoice" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billing/create-checkout-session": { "post": { "operationId": "billingCreateCheckoutSession", "summary": "Create a hosted Stripe Checkout session", "description": "Creates a hosted Stripe Checkout session for a subscription plan. Returns a `checkout_url` to redirect the user to Stripe. `success_url` and `cancel_url` must be `https://` URLs targeting an allowlisted application domain; other values return `400 VALIDATION_ERROR`. `trial_period_days` is a client hint that is server-clamped against the plan's configured maximum — the effective value can be less than requested.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_CheckoutSessionCreateRequest" } } } }, "responses": { "201": { "description": "Checkout session created. Redirect the user to `checkout_url`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Billing_CheckoutSessionResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` (invalid fields, disallowed redirect domain, or invalid `trial_period_days`), `STRIPE_CREDENTIALS_MISSING` (Stripe not configured for the package).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "`CHECKOUT_FAILED` — Stripe session creation failed or server misconfiguration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/billing/create-embedded-checkout-session": { "post": { "operationId": "billingCreateEmbeddedCheckoutSession", "summary": "Create an embedded Stripe Checkout session", "description": "Creates an embedded Stripe Checkout session. Returns a `client_secret` for initializing Stripe.js Embedded Checkout on the page. Supports `mode=subscription` (default, requires `price_id`) and `mode=setup` (card collection without a charge). `return_url` must target an allowlisted application domain; other values return `400 VALIDATION_ERROR`.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_EmbeddedCheckoutSessionCreateRequest" } } } }, "responses": { "201": { "description": "Embedded checkout session created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Billing_EmbeddedCheckoutSessionResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` (invalid fields, disallowed redirect domain, or `price_id` missing for `mode=subscription`), `STRIPE_CREDENTIALS_MISSING` (Stripe not configured for the package).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "`CHECKOUT_FAILED` — Stripe session creation failed or server misconfiguration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/billing/credit-packs/{planId}/purchase": { "post": { "operationId": "billingPurchaseCreditPack", "summary": "Purchase a credit pack", "description": "Initiates a one-time Stripe Checkout session (`mode=payment`) to purchase an AI credit pack identified by `planId`. Returns `checkout_url` to redirect the user and an `order_id` for status polling. The plan must be of type `credit_pack` with a configured Stripe price. `return_url` and `cancel_url` must be `https://` URLs targeting an allowlisted application domain.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "planId", "in": "path", "required": true, "description": "Credit pack pricing plan identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_CreditPackPurchaseRequest" } } } }, "responses": { "201": { "description": "Credit pack checkout session created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Billing_CreditPackPurchaseResult" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (malformed `planId`), `VALIDATION_ERROR` (invalid redirect URLs or plan not eligible for credit-pack purchase).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks permission to purchase credit packs for the org.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — plan not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`CHECKOUT_FAILED` — Stripe session creation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`CHECKOUT_FAILED` — credit pack plan not yet synced to Stripe (missing `stripe_price_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/billing/credit-packs/orders/{orderId}": { "get": { "operationId": "billingGetCreditPackOrder", "summary": "Get credit pack order status", "description": "Returns the status and metadata of a one-time credit pack order. Used for post-checkout polling to confirm that credits have been provisioned after Stripe payment.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Credit pack order identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit pack order record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_CreditPackOrder" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed `orderId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — order does not belong to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/pricing": { "get": { "operationId": "billingListPricingPlans", "summary": "List public pricing plans", "description": "Returns pricing plans sourced from Stripe, optionally filtered by `package_id` and `environment`. This is a public endpoint — no authentication required. Results are KV-cached; `cached` and `cacheAge` indicate whether the response is from cache. Rate-limited to 50 requests per minute per IP (IPv6 normalized to /64).", "tags": [ "Billing & Subscriptions" ], "security": [], "parameters": [ { "name": "package_id", "in": "query", "required": false, "description": "Filter to a specific SaaS package (UUIDv7). When omitted all published packages are returned.", "schema": { "type": "string", "format": "uuid" } }, { "name": "environment", "in": "query", "required": false, "description": "Filter to a specific deployment environment.", "schema": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] } } ], "responses": { "200": { "description": "Pricing plans. The `cached` flag indicates whether the response was served from the KV cache.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Billing_PricingPlan" }, "description": "Pricing plan list." }, "meta": { "type": "object", "additionalProperties": true, "description": "Package and environment metadata." }, "cached": { "type": "boolean", "description": "True if the response was served from cache." }, "cacheAge": { "type": [ "integer", "null" ], "description": "Cache age in seconds (null when not cached)." } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/signup-checkout/intents": { "post": { "operationId": "billingCreateSignupCheckoutIntent", "summary": "Create a pre-auth signup checkout intent", "description": "Creates a signup checkout intent before the user authenticates, capturing plan and package selection. No authentication is required; rate-limiting (20/hour per IP) is enforced by the platform. A Cloudflare Turnstile token is required (supplied as `cf-turnstile-response` header by the frontend). Only `https://` requests traversing the Cloudflare edge are accepted (the source IP is derived exclusively from `cf-connecting-ip`). At least one of `org_id`, `org_slug_or_id`, or `domain` must be supplied as a resolved UUID; slug/domain resolution is not performed server-side on this endpoint.", "tags": [ "Billing & Subscriptions" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_SignupCheckoutIntentCreateRequest" } } } }, "responses": { "201": { "description": "Signup checkout intent created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_SignupCheckoutIntent" } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `VALIDATION_ERROR` (schema violation), `INVALID_PARAMETER` (source IP could not be determined — request must traverse Cloudflare edge).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — academic-verification prerequisite not met, or prerequisite plan not satisfied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the specified plan or package does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — org conflict or intent lifecycle state conflict (e.g. intent expired or already consumed). `error.details` may carry `intent_org_id` and `caller_org_id` for org-conflict disambiguation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — per-IP rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/signup-checkout/intents/{id}/resume": { "post": { "operationId": "billingResumeSignupCheckoutIntent", "summary": "Resume a signup checkout intent (authenticated)", "description": "Resumes a previously created signup checkout intent after user authentication. The caller must be an active member of the intent's owning organization. When `resolved_org_id` differs from the session's `org_id`, the caller's membership in `resolved_org_id` is pre-checked at the route layer before the underlying platform call.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Signup checkout intent identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_SignupCheckoutIntentResumeRequest" } } } }, "responses": { "200": { "description": "Intent resumed; checkout session details returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_SignupCheckoutIntent" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (malformed `id`), `INVALID_JSON` (unparseable body), `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller is not an active member of the resolved org.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — intent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — intent expired, already consumed, or org conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-connect": { "get": { "operationId": "billingGetStripeConnect", "summary": "Get legacy Stripe Connect configuration", "description": "Returns the Stripe Connect configuration for the given SaaS package and environment. Requires `stripe_connect.view` permission. This is the legacy per-(package, environment) endpoint; new integrations should use `/v1/stripe-profiles`.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "environment", "in": "query", "required": false, "description": "Deployment environment.", "schema": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] } } ], "responses": { "200": { "description": "Stripe Connect configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeConnect" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — Stripe Connect configuration not found for this package and environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "billingCreateStripeConnect", "summary": "Create legacy Stripe Connect configuration", "description": "Creates a Stripe Connect configuration for a SaaS package and environment. Requires `stripe_connect.create` permission. This is the legacy per-(package, environment) endpoint; new integrations should use `/v1/stripe-profiles`.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeConnectCreateRequest" } } } }, "responses": { "201": { "description": "Stripe Connect configuration created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeConnect" } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — a Stripe Connect configuration already exists for this package and environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "billingUpdateStripeConnect", "summary": "Update legacy Stripe Connect configuration", "description": "Updates the Stripe Connect configuration for a SaaS package and environment. At least one mutable field (beyond `saas_package_id` and `environment`) must be supplied. Requires `stripe_connect.update` permission. A body-supplied `stripe_account_id` that does not match the verified stored value is rejected with `403 FORBIDDEN`. This is the legacy endpoint; new integrations should use `/v1/stripe-profiles`.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeConnectUpdateRequest" } } } }, "responses": { "200": { "description": "Updated Stripe Connect configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeConnect" } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — missing permission or submitted `stripe_account_id` does not match the verified record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — configuration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-connect/onboard": { "post": { "operationId": "billingStripeConnectOnboard", "summary": "Start legacy Stripe Connect onboarding (deprecated — 410 Gone)", "description": "**Permanently retired.** This endpoint is disabled by default and returns `410 GONE` with `Sunset`, `Link`, and `Deprecation` headers pointing to the successor `/v1/stripe-profiles/:profileId/onboard/start`. It accepted a tenant-supplied `stripe_account_id`, making account-claim races possible. Use `POST /v1/stripe-profiles` and `POST /v1/stripe-profiles/:profileId/onboard/start` instead.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeConnectOnboardRequest" } } } }, "responses": { "200": { "description": "Onboarding started (only returned when the endpoint is explicitly re-enabled by the operator).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — a Stripe Connect record already exists for this package/environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "`GONE` — this endpoint is permanently retired. Use `POST /v1/stripe-profiles` + `POST /v1/stripe-profiles/:profileId/onboard/start`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-connect/onboard/complete": { "post": { "operationId": "billingStripeConnectOnboardComplete", "summary": "Complete legacy Stripe Connect onboarding", "description": "Marks the Stripe Connect onboarding as complete by recording the `charges_enabled`, `payouts_enabled`, and `details_submitted` states reported by Stripe. Requires `stripe_connect.update` permission. This is the legacy endpoint; prefer `/v1/stripe-profiles/:profileId/onboard/complete`.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeConnectOnboardCompleteRequest" } } } }, "responses": { "200": { "description": "Onboarding completion recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — Stripe Connect configuration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-connect/fees": { "put": { "operationId": "billingUpdateStripeConnectFees", "summary": "Update legacy Stripe Connect fee percentages", "description": "Updates the platform and/or client fee percentages for a Stripe Connect configuration. At least one fee field must be supplied. Requires `stripe_connect.update` permission. This is the legacy endpoint; prefer `/v1/stripe-profiles/:profileId/fees`.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeConnectUpdateFeesRequest" } } } }, "responses": { "200": { "description": "Fee percentages updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — configuration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-connect/sync": { "post": { "operationId": "billingStripeConnectSync", "summary": "Sync legacy Stripe Connect account status", "description": "Syncs Stripe account status fields (charges/payouts enabled, business profile, currency) for a legacy Stripe Connect configuration. Requires `stripe_connect.update` permission. This is the legacy endpoint; prefer `/v1/stripe-profiles/:profileId/sync`.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeConnectSyncRequest" } } } }, "responses": { "200": { "description": "Stripe Connect status synced.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — configuration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-profiles": { "get": { "operationId": "billingListStripeProfiles", "summary": "List Stripe Connect profiles", "description": "Returns the organization's Stripe Connect profiles with optional status filter and page/pageSize pagination. Permission gating is enforced inside the platform; the caller must hold `stripe.profiles.view` or equivalent.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by profile onboarding status.", "schema": { "type": "string", "enum": [ "pending", "onboarding", "restricted", "active", "disabled" ] } } ], "responses": { "200": { "description": "Paginated list of Stripe Connect profiles.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Billing_StripeProfile" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "billingCreateStripeProfile", "summary": "Create a Stripe Connect profile", "description": "Creates a new Stripe Connect profile for the organization. `stripe_account_id` may not be supplied on creation — the Stripe account is created server-side by calling `POST /v1/stripe-profiles/:profileId/onboard/start`. Permission gating is enforced inside the platform.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeProfileCreateRequest" } } } }, "responses": { "201": { "description": "Stripe Connect profile created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeProfile" } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR` (including rejection of a supplied `stripe_account_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — a profile with a conflicting constraint already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-profiles/{profileId}": { "get": { "operationId": "billingGetStripeProfile", "summary": "Get a Stripe Connect profile", "description": "Returns a single Stripe Connect profile by id. Returns `404 NOT_FOUND` for profiles not belonging to the caller's organization.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stripe Connect profile.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeProfile" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed `profileId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "billingUpdateStripeProfile", "summary": "Update a Stripe Connect profile", "description": "Updates mutable fields on a Stripe Connect profile (name, description, country, default currency, business profile). `expected_version` is required for optimistic concurrency. At least one mutable field (beyond `expected_version`) must be supplied.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeProfileUpdateRequest" } } } }, "responses": { "200": { "description": "Updated profile.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeProfile" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — `expected_version` is stale (concurrent modification).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "billingDeleteStripeProfile", "summary": "Delete (archive) a Stripe Connect profile", "description": "Soft-deletes a Stripe Connect profile. `expected_version` is required for optimistic concurrency. The platform enforces that the profile has no active subscriber dependencies before deletion.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeProfileDeleteRequest" } } } }, "responses": { "200": { "description": "Profile archived.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — `expected_version` is stale, profile has dependents, or profile is already archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-profiles/{profileId}/fees": { "patch": { "operationId": "billingUpdateStripeProfileFees", "summary": "Update Stripe Connect profile fee percentages", "description": "Updates the platform and/or client fee percentages for a Stripe Connect profile. Requires a fresh MFA step-up (the session's last MFA step-up must be within the configured window). `expected_version` is required for optimistic concurrency. At least one fee field must be supplied.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeProfileUpdateFeesRequest" } } } }, "responses": { "200": { "description": "Fee percentages updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeProfile" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_REQUIRED` or `MFA_STEPUP_REQUIRED` — a fresh MFA step-up is required for fee changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — `expected_version` is stale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-profiles/{profileId}/webhook-secret/rotate": { "post": { "operationId": "billingRotateStripeProfileWebhookSecret", "summary": "Rotate Stripe Connect profile webhook secret", "description": "Rotates the webhook signing secret for a Stripe Connect profile. Requires a fresh MFA step-up (PCI DSS Req 8.6 / SOC 2 CC6.6 key management control). `expected_version` is required for optimistic concurrency.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeProfileRotateWebhookSecretRequest" } } } }, "responses": { "200": { "description": "Webhook secret rotated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_REQUIRED` or `MFA_STEPUP_REQUIRED` — a fresh MFA step-up is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — `expected_version` is stale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-profiles/{profileId}/onboard/start": { "post": { "operationId": "billingStartStripeProfileOnboarding", "summary": "Start Stripe Connect profile onboarding", "description": "Orchestrates server-side Stripe account creation (if the profile has no `stripe_account_id` yet) and returns a fresh Stripe AccountLink URL for the operator to complete KYC. Uses a stable Idempotency-Key so a retry after a transient failure does not create a duplicate Stripe account. `refresh_url` and `return_url` must use `https://` and target the configured application domain.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeProfileOnboardStartRequest" } } } }, "responses": { "200": { "description": "Onboarding URL returned. Redirect the operator to `onboarding_url`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeProfileOnboardStartResult" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR` (disallowed redirect URL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — profile state conflict (e.g. `stripe_account_id` already claimed by another profile).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "description": "`EXTERNAL_SERVICE_ERROR` — Stripe account creation or AccountLink creation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — Stripe is not configured for this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/stripe-profiles/{profileId}/onboard/complete": { "post": { "operationId": "billingCompleteStripeProfileOnboarding", "summary": "Complete Stripe Connect profile onboarding", "description": "Syncs the Stripe account's current state (charges/payouts/details, onboarding status, tax info) from Stripe into the platform record. `expected_version` is required for optimistic concurrency.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeProfileOnboardCompleteRequest" } } } }, "responses": { "200": { "description": "Onboarding state synced from Stripe.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeProfile" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — profile has no Stripe account yet (call `/onboard/start` first) or `expected_version` is stale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "description": "`EXTERNAL_SERVICE_ERROR` — Stripe account lookup failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — Stripe is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/stripe-profiles/{profileId}/sync": { "post": { "operationId": "billingStripeProfileSync", "summary": "Queue Stripe Connect profile sync", "description": "Enqueues a re-sync of linked Stripe plans for this profile, optionally filtered to specific environments. Returns `202 Accepted`.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeProfileSyncRequest" } } } }, "responses": { "202": { "description": "Sync enqueued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — profile is not in a state that allows sync (e.g. onboarding not yet complete).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-profiles/{profileId}/links": { "get": { "operationId": "billingListStripeProfileLinks", "summary": "List package links for a Stripe Connect profile", "description": "Returns all (SaaS package, environment) links associated with this Stripe Connect profile.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of package links.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Billing_StripeProfileLink" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "billingLinkStripeProfilePackage", "summary": "Link a package to a Stripe Connect profile", "description": "Associates a (SaaS package, environment) combination with this Stripe Connect profile.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_StripeProfileLinkPackageRequest" } } } }, "responses": { "201": { "description": "Package linked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_StripeProfileLink" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — link already exists or live/test mode conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/stripe-profiles/{profileId}/links/{pkgId}/{env}": { "delete": { "operationId": "billingUnlinkStripeProfilePackage", "summary": "Unlink a package from a Stripe Connect profile", "description": "Removes the link between a (SaaS package, environment) combination and this Stripe Connect profile. The `archive_stripe_products` query parameter controls whether linked Stripe products are archived.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "profileId", "in": "path", "required": true, "description": "Stripe Connect profile identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "pkgId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "env", "in": "path", "required": true, "description": "Deployment environment.", "schema": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] } }, { "name": "archive_stripe_products", "in": "query", "required": false, "description": "When `true`, archive the associated Stripe products/prices for this link.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Package unlinked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (malformed `profileId` or `pkgId`), `INVALID_PARAMETER` (invalid `env` value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — link has active subscribers or active Stripe products (archive first or use `archive_stripe_products=true`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/api-keys": { "get": { "operationId": "billingListApiKeys", "summary": "List organization API keys", "description": "Returns the API keys for the authenticated organization. Raw key values are never returned — only the key prefix, name, scopes, and metadata. The organization and RLS scope are derived from the session.", "tags": [ "Billing & Subscriptions" ], "responses": { "200": { "description": "List of API keys.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/Billing_ApiKeyListItem" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "billingCreateApiKey", "summary": "Create an API key", "description": "Creates a new organization API key with the specified name, scopes, expiry, and optional rate limit. The raw key (`bb_live__`) is returned ONCE in the response and never stored — if lost it cannot be retrieved. Requires recent authentication (token issued within 5 minutes). Organization API key cap (100) is enforced before creation.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_ApiKeyCreateRequest" } } } }, "responses": { "201": { "description": "API key created. The `key` field contains the raw key; store it now as it will not be shown again.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_ApiKeyCreated" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid JSON, invalid `name`, disallowed `scopes`, out-of-range `expires_in_days` or `rate_limit_rpm`, or malformed `pinned_env_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_REQUIRED`, `REAUTH_REQUIRED` — a recent (within 5 min) session token is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller lacks permission to create keys or the `pinned_env_id` would escalate privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`QUOTA_EXCEEDED` — organization has reached the 100-key limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/api-keys/{id}": { "delete": { "operationId": "billingRevokeApiKey", "summary": "Revoke an API key", "description": "Immediately revokes an API key, preventing any future use. Requires recent authentication (token issued within 5 minutes).", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "API key revoked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revoked": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — malformed key `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_REQUIRED`, `REAUTH_REQUIRED` — a recent session token is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/api-keys/{id}/rotate": { "post": { "operationId": "billingRotateApiKey", "summary": "Rotate an API key", "description": "Atomically revokes the existing key and creates a replacement with the same name and scopes. The new raw key is returned once. An optional `grace_period_minutes` (0–60, default 5) keeps the old key valid for a short overlap window so in-flight requests are not disrupted. Requires recent authentication (token issued within 5 minutes).", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_ApiKeyRotateRequest" } } } }, "responses": { "200": { "description": "API key rotated. The `key` field contains the new raw key; store it now as it will not be shown again.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_ApiKeyRotated" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — malformed key `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_REQUIRED`, `REAUTH_REQUIRED` — a recent session token is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/academic-verifications/start": { "post": { "operationId": "billingStartAcademicVerification", "summary": "Start an academic verification", "description": "Initiates an academic verification for the authenticated user. Optionally scoped to a specific SaaS package and verification provider.", "tags": [ "Billing & Subscriptions" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_AcademicVerificationStartRequest" } } } }, "responses": { "201": { "description": "Academic verification started.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_AcademicVerification" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — the specified package or provider not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — concurrent verification submission quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/academic-verifications": { "get": { "operationId": "billingListAcademicVerifications", "summary": "List academic verifications (reviewer queue)", "description": "Returns the org-scoped reviewer queue of pending and submitted academic verifications. Filtered by optional `status` and paginated by `page`/`page_size`.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by verification status.", "schema": { "type": "string", "enum": [ "pending", "submitted" ] } } ], "responses": { "200": { "description": "Paginated reviewer queue.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Billing_AcademicVerification" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/academic-verifications/{id}": { "get": { "operationId": "billingGetAcademicVerification", "summary": "Get an academic verification", "description": "Returns a single academic verification by id. Accessible by the subject user or a reviewer.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Academic verification identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Academic verification record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_AcademicVerification" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/academic-verifications/{id}/submit": { "post": { "operationId": "billingSubmitAcademicVerification", "summary": "Submit evidence for academic verification", "description": "Attaches institution name, role, and optional evidence URL to an in-progress academic verification.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Academic verification identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_AcademicVerificationSubmitRequest" } } } }, "responses": { "200": { "description": "Evidence submitted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_AcademicVerification" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — resubmission quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/academic-verifications/{id}/review": { "post": { "operationId": "billingReviewAcademicVerification", "summary": "Review an academic verification", "description": "Approves or rejects an academic verification. Callers must hold the reviewer role. `rejection_reason` is required when `decision=rejected`.", "tags": [ "Billing & Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Academic verification identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing_AcademicVerificationReviewRequest" } } } }, "responses": { "200": { "description": "Verification reviewed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Billing_AcademicVerification" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR` (including missing `rejection_reason` when decision=rejected).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/ws": { "get": { "operationId": "commsMailWsUpgrade", "summary": "Open mailbox WebSocket", "description": "Upgrades an HTTP connection to a WebSocket channel connected to the caller's mailbox Durable Object. The caller must supply a one-time `token` query parameter (a short-lived JWT minted by the session) and the `mailboxId` to connect to. The server verifies the token, checks revocation, and runs the mailbox effective-access gate before forwarding the upgrade. A connection without `Upgrade: websocket` receives `426 Upgrade Required`. The capability (`read` or `write`) is derived from the access verdict and forwarded to the Durable Object, which re-verifies independently.\n\nAuthentication is via the `token` query parameter (`oneTimeTicket` scheme) — a standard `Authorization` header is not supported on WebSocket upgrades.", "tags": [ "Communications & Productivity" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "One-time mailbox connection ticket (short-lived JWT). Minted by an authenticated REST call; redeemable once.", "schema": { "type": "string", "minLength": 1 } }, { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7) to connect to.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "101": { "description": "WebSocket handshake accepted. The connection is proxied to the mailbox Durable Object. Messages follow the BB Mail WS protocol." }, "400": { "description": "`VALIDATION_ERROR` — `token` or `mailboxId` query parameter is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_TOKEN_INVALID` or `AUTH_TOKEN_EXPIRED` — the one-time token is malformed, expired, or has been revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`PERMISSION_DENIED` — the caller has no read access to this mailbox (uniform deny; does not distinguish absent from forbidden).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "426": { "description": "`VALIDATION_ERROR` — the request did not include `Upgrade: websocket`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/mailboxes": { "get": { "operationId": "commsMailListMailboxes", "summary": "List mailboxes", "description": "Returns the mailboxes the caller owns or has been delegated access to within the authenticated organization.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "List of mailboxes.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommsMail_Mailbox" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "commsMailCreateMailbox", "summary": "Create a mailbox", "description": "Creates a new mailbox under a verified sending domain in the caller's organization. The organization is taken from the authenticated session and is never accepted in the request body.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_MailboxCreateRequest" } } } }, "responses": { "201": { "description": "Mailbox created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_Mailbox" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — the referenced domain does not exist or is not visible to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a mailbox with that local-part already exists on this domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/settings": { "get": { "operationId": "commsMailGetSettings", "summary": "Get mailbox settings", "description": "Returns the caller's per-user preferences for the specified mailbox.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current mailbox settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_MailboxSettings" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `mailboxId` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "commsMailUpdateSettings", "summary": "Update mailbox settings", "description": "Upserts the caller's per-user preferences for the specified mailbox. All fields are optional; only supplied fields are updated.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_MailboxSettingsUpdateRequest" } } } }, "responses": { "200": { "description": "Updated mailbox settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_MailboxSettings" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/messages": { "get": { "operationId": "commsMailListMessages", "summary": "List messages", "description": "Returns a paginated list of messages in the specified mailbox, optionally filtered by direction.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "direction", "in": "query", "required": false, "description": "Filter by message direction.", "schema": { "type": "string", "enum": [ "in", "out", "draft" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum messages to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of messages to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated message list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommsMail_MessageSummary" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/messages/send": { "post": { "operationId": "commsMailSendMessage", "summary": "Send a message", "description": "Sends an outbound email from the specified mailbox. The `From` identity is resolved server-side from the mailbox record; callers cannot override it. All attachments must be pre-uploaded via `POST /v1/bbmail/attachments`; only content-addressed references (`sha256`) are accepted here. The combined `to + cc + bcc` count must not exceed the platform MAX_RECIPIENTS limit. In restricted (non-production) environments outbound recipients are checked against the org's verified domains and current org members. An optional `Idempotency-Key` header (max 256 chars) enables safe retries.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_MessageSendRequest" } } } }, "responses": { "200": { "description": "Message accepted by the sending provider.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CommsMail_SendResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid recipients, `TOO_MANY_RECIPIENTS`, subject too long, too many attachments, or `ATTACHMENT_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`QUOTA_EXCEEDED` — send quota exceeded; top up credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — cannot send from this mailbox or `RESTRICTED_ENV` recipient refusal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — mailbox not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — all recipients suppressed or daily send cap reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "description": "`DATABASE_ERROR` — provider dispatch error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — email sending not configured, suppression check unavailable, or runtime unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbmail/messages/{messageId}": { "get": { "operationId": "commsMailGetMessage", "summary": "Get a message", "description": "Returns a single message by id. The `mailboxId` query parameter is required. A message the caller cannot access is reported as `404 NOT_FOUND`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "description": "Message identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The message record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_MessageSummary" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/messages/{messageId}/move": { "post": { "operationId": "commsMailMoveMessage", "summary": "Move a message (WebSocket-only operation)", "description": "Message-folder moves are performed over the mailbox WebSocket (`GET /v1/bbmail/ws`), not via REST. Connect to the mailbox socket and send the `MSG_MOVE` operation; the change is applied in the mailbox Durable Object and durably audited via the signed audit flush. This REST endpoint exists to return a machine-readable error rather than silently returning `404`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "description": "Message identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "description": "`INVALID_ID_FORMAT` — invalid `messageId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "`VALIDATION_ERROR` with `ws_only: true` — this operation must be performed over the mailbox WebSocket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbmail/messages/{messageId}/labels": { "post": { "operationId": "commsMailApplyMessageLabel", "summary": "Apply or remove a message label (WebSocket-only operation)", "description": "Message label mutations are performed over the mailbox WebSocket (`GET /v1/bbmail/ws`), not via REST. Connect to the mailbox socket and send the `MSG_LABEL` operation; the change is applied in the mailbox Durable Object and durably audited via the signed audit flush. This REST endpoint exists to return a machine-readable error rather than silently returning `404`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "description": "Message identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "description": "`INVALID_ID_FORMAT` — invalid `messageId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "`VALIDATION_ERROR` with `ws_only: true` — this operation must be performed over the mailbox WebSocket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbmail/attachments": { "post": { "operationId": "commsMailUploadAttachment", "summary": "Upload an attachment", "description": "Content-addresses an attachment to object storage under the caller's org/mailbox prefix. The caller must pass `mailboxId` as a query parameter and send the raw file bytes as the request body (`application/octet-stream`). Returns the SHA-256 content hash and byte length; pass the `sha256` in a subsequent send request. The per-file limit is 25 MiB. Returns `413 Payload Too Large` when the declared `Content-Length` or actual body exceeds 25 MiB.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7) that will own the attachment. Caller must have `can_write` on this mailbox.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw attachment bytes (≤ 25 MiB). Non-empty required." } } } }, "responses": { "201": { "description": "Attachment stored. Returns the SHA-256 hash and byte length for use in send requests.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_AttachmentUploadResponse" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — empty body or `INVALID_ID_FORMAT` — invalid `mailboxId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — mailbox not found or caller lacks `can_write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — file exceeds 25 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — attachment storage not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbmail/attachments/{sha256}": { "get": { "operationId": "commsMailGetAttachment", "summary": "Stream an attachment", "description": "Streams a previously-uploaded attachment by its SHA-256 content hash. The `mailboxId` query parameter is required. Non-executable content types are served inline with `nosniff`; all others are served as `application/octet-stream` with `Content-Disposition: attachment`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "sha256", "in": "path", "required": true, "description": "SHA-256 hex digest of the attachment (64 lowercase hex characters).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/labels": { "get": { "operationId": "commsMailListLabels", "summary": "List labels", "description": "Returns all labels in the specified mailbox including their hierarchy.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of labels.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommsMail_Label" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "commsMailCreateLabel", "summary": "Create a label", "description": "Creates a new label in the specified mailbox. Labels can be nested by supplying a `parentId`.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_LabelCreateRequest" } } } }, "responses": { "201": { "description": "Label created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_Label" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/labels/{labelId}": { "patch": { "operationId": "commsMailUpdateLabel", "summary": "Update a label", "description": "Updates one or more label properties. `mailboxId` is required in the body. All other fields are optional.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "labelId", "in": "path", "required": true, "description": "Label identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_LabelPatchRequest" } } } }, "responses": { "200": { "description": "Updated label.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_Label" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "commsMailDeleteLabel", "summary": "Delete a label", "description": "Deletes a label from a mailbox. The `mailboxId` query parameter is required.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "labelId", "in": "path", "required": true, "description": "Label identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Label deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/filters": { "get": { "operationId": "commsMailListFilters", "summary": "List message filters", "description": "Returns all message filters defined for the specified mailbox, ordered by `ordinal`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of filters.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommsMail_Filter" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "commsMailCreateFilter", "summary": "Create a message filter", "description": "Creates a new message filter rule in the specified mailbox. `criteria` and `actions` are structured JSON objects validated server-side.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_FilterCreateRequest" } } } }, "responses": { "201": { "description": "Filter created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_Filter" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/filters/{filterId}": { "patch": { "operationId": "commsMailUpdateFilter", "summary": "Update a message filter", "description": "Updates one or more filter properties. `mailboxId` is required in the body.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "filterId", "in": "path", "required": true, "description": "Filter identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_FilterPatchRequest" } } } }, "responses": { "200": { "description": "Updated filter.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_Filter" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "commsMailDeleteFilter", "summary": "Delete a message filter", "description": "Deletes a message filter. The `mailboxId` query parameter is required.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "filterId", "in": "path", "required": true, "description": "Filter identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Filter deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/filters/{filterId}/run": { "post": { "operationId": "commsMailRunFilter", "summary": "Run a message filter", "description": "Authorizes and returns the validated filter specification so the mailbox Durable Object can apply it over its hot message index. The route does not mutate message state directly — mutation is handled via the WebSocket protocol in the Durable Object.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "filterId", "in": "path", "required": true, "description": "Filter identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "mailboxId", "in": "query", "required": true, "description": "Mailbox identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Filter spec authorized. The payload contains the filter spec for the Durable Object to execute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/domains": { "get": { "operationId": "commsMailListDomains", "summary": "List sending domains", "description": "Returns all mail sending domains linked to the caller's organization.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "List of domains.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommsMail_Domain" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "commsMailLinkDomain", "summary": "Link a sending domain", "description": "Links a domain to the caller's organization for use as a mail sending domain. Returns the domain record with the DNS records that must be published to verify ownership and configure routing.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_DomainLinkRequest" } } } }, "responses": { "201": { "description": "Domain linked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_Domain" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — domain already linked or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/domains/{domainId}": { "get": { "operationId": "commsMailGetDomain", "summary": "Get a sending domain", "description": "Returns a single sending domain including its verification status and required DNS records.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "description": "Domain identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_Domain" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/domains/{domainId}/verify": { "post": { "operationId": "commsMailVerifyDomain", "summary": "Verify domain ownership via DNS TXT", "description": "Triggers an ownership verification check by performing a DNS-over-HTTPS lookup for the `_bbmail-verify.` TXT record and passing the observed value to the server. The server (not the route) makes the ownership decision. Returns the updated domain record with the new verification status.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "description": "Domain identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Verification check completed. The body contains the updated domain record; inspect `ownership_verified_at` to determine if ownership was confirmed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsMail_Domain" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/domains/{domainId}/verify-dns": { "post": { "operationId": "commsMailVerifyDomainDns", "summary": "Re-check published DNS records", "description": "Re-checks the live DNS records (MX, SPF, DKIM CNAME, DMARC) for a domain whose ownership has already been verified, and advances the per-record-class verification flags so the setup wizard can display per-step status. Requires `ownership_verified_at` to be set on the domain; returns `409 CONFLICT` otherwise.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "description": "Domain identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DNS check completed. The body contains the updated verification flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — domain ownership must be verified before DNS verification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/domains/{domainId}/provision": { "post": { "operationId": "commsMailProvisionDomain", "summary": "Auto-provision Cloudflare DNS and email routing", "description": "Drives Cloudflare DNS and Email-Routing provisioning for a Cloudflare-hosted domain. Attempts provider-based ownership proof via the organization's connected Cloudflare account before provisioning. Returns a structured per-step result in all cases; inspect the `code` field to determine the outcome (`OK`, `PARTIAL`, `OWNERSHIP_NOT_PROVEN`, `DOMAIN_NOT_ON_CLOUDFLARE`, `NEEDS_PROVIDER_CONNECTION`, `DOMAIN_ALREADY_CLAIMED`).", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "description": "Domain identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Provisioning succeeded or partially succeeded. Inspect `data.code` for the per-step result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The domain is already claimed by another organization (`DOMAIN_ALREADY_CLAIMED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`OWNERSHIP_NOT_PROVEN` or `NEEDS_PROVIDER_CONNECTION`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "422": { "description": "Domain is not present in the organization's connected Cloudflare account (`DOMAIN_NOT_ON_CLOUDFLARE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbmail/domains/{domainId}/ses-onboard": { "post": { "operationId": "commsMailSesOnboard", "summary": "Onboard domain to AWS SES for sending", "description": "Drives SES identity creation, Easy-DKIM, and MAIL-FROM configuration for a verified domain. Requires a proven ownership timestamp on the domain. Returns a structured per-step result; `503` when SES is not configured server-side.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "description": "Domain identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SES onboarding succeeded or partially succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`DOMAIN_NOT_FOUND` — domain does not exist in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — ownership not proven or an immutable state precondition was not met.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — SES onboarding is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbmail/domains/{domainId}/ses-verify": { "post": { "operationId": "commsMailSesVerify", "summary": "Poll SES verification status", "description": "Polls SES for send-readiness (DKIM, MAIL-FROM) and performs an MX reachability probe for receive-readiness, persisting the results. Requires proven ownership. Returns `409` when ownership is not proven.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "description": "Domain identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SES verification polling completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — ownership not proven.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — SES is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbmail/inbound-smtp": { "post": { "operationId": "commsMailInboundSmtp", "summary": "Receive inbound message via SMTP hook (public webhook)", "description": "Public MTA-hook endpoint called by the self-hosted Stalwart inbound SMTP fleet at the DATA stage. Accepts a JSON envelope containing the raw RFC 822 message, SMTP envelope, and edge-computed SPF/DKIM/DMARC verdicts signed with an HMAC. After signature verification the handler resolves the recipient address to a mailbox, durably writes the raw message to object storage (the commit point), then asynchronously writes the catalog row and projects the message index. Returns `{ action: \"discard\" }` on success to instruct the MTA to drop the message from its spool. A `503` response signals a temporary failure; the MTA or its local spool should retry.", "tags": [ "Communications & Productivity" ], "security": [ { "webhookSignature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_InboundSmtpRequest" } } } }, "responses": { "200": { "description": "Message accepted. `action: discard` instructs the MTA to remove the message from its spool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_InboundSmtpResponse" } } } }, "400": { "description": "Malformed request body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "HMAC signature verification failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "411": { "description": "Content-Length header is absent or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "413": { "description": "Request body exceeds the 25 MiB per-message limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Service not configured or temporary upstream failure. The MTA should retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/calendar/ws": { "get": { "operationId": "commsCalWsUpgrade", "summary": "Open calendar WebSocket", "description": "Upgrades to a WebSocket channel connected to the calendar Durable Object. The caller supplies a one-time `token` (JWT) and the `calendarId`. The server verifies the token, checks revocation, and runs the four-bit calendar access gate (`can_read_freebusy` / `can_read_details` / `can_write` / `can_admin`) before forwarding the upgrade. The derived capability (`freebusy`, `read`, or `write`) is passed to the Durable Object, which re-verifies independently. A request without `Upgrade: websocket` receives `426`.", "tags": [ "Communications & Productivity" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "One-time calendar connection ticket (short-lived JWT).", "schema": { "type": "string", "minLength": 1 } }, { "name": "calendarId", "in": "query", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "101": { "description": "WebSocket handshake accepted." }, "400": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_TOKEN_INVALID` or `AUTH_TOKEN_EXPIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`PERMISSION_DENIED` — no calendar access (uniform deny).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "426": { "description": "`VALIDATION_ERROR` — not a WebSocket upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/calendars": { "get": { "operationId": "commsCalListCalendars", "summary": "List calendars", "description": "Returns the calendars visible to the caller in their organization. Pass `include_hidden=true` to include hidden calendars.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "include_hidden", "in": "query", "required": false, "description": "Include hidden calendars when `true`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of calendars.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommsCalendar_Calendar" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "commsCalCreateCalendar", "summary": "Create a calendar", "description": "Creates a new calendar in the caller's organization. All fields are optional; defaults are assigned by the platform.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_CalendarCreateRequest" } } } }, "responses": { "201": { "description": "Calendar created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsCalendar_Calendar" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/calendars/{calendarId}": { "get": { "operationId": "commsCalGetCalendar", "summary": "Get a calendar", "description": "Returns a single calendar. A calendar the caller cannot see is reported as `404 NOT_FOUND`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Calendar record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsCalendar_Calendar" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "commsCalUpdateCalendar", "summary": "Update a calendar", "description": "Updates calendar properties. All fields are optional; `name: null` clears the name.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_CalendarUpdateRequest" } } } }, "responses": { "200": { "description": "Updated calendar.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommsCalendar_Calendar" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "commsCalDeleteCalendar", "summary": "Delete a calendar", "description": "Deletes a calendar.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Calendar deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/calendars/{calendarId}/acl": { "get": { "operationId": "commsCalListCalendarAcl", "summary": "List calendar ACL entries", "description": "Returns the access-control list for a calendar. Pass `include_revoked=true` to include revoked grants.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_revoked", "in": "query", "required": false, "description": "Include revoked grants when `true`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "ACL entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "commsCalSetCalendarAcl", "summary": "Grant or revoke a calendar share", "description": "Adds, updates, or revokes a share grant for a calendar. Requires `can_admin` on the calendar.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_ShareSetRequest" } } } }, "responses": { "200": { "description": "Share grant applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/calendars/{calendarId}/settings": { "get": { "operationId": "commsCalGetCalendarSettings", "summary": "Get per-calendar settings", "description": "Returns the caller's per-calendar settings.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Per-calendar settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "commsCalUpdateCalendarSettings", "summary": "Update per-calendar settings", "description": "Updates the caller's per-calendar settings. Body is a free-form JSON object; `org_id` and `calendar_id` are pinned from the session and path.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Key-value settings bag; validated server-side.", "additionalProperties": true } } } }, "responses": { "200": { "description": "Updated settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/access-requests": { "post": { "operationId": "commsCalCreateAccessRequest", "summary": "Request calendar access", "description": "Submits an access request for a calendar by id or owner email. An optional email notification can be sent to the calendar owner.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_AccessRequestRequest" } } } }, "responses": { "201": { "description": "Access request submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/events": { "get": { "operationId": "commsCalListEvents", "summary": "List events in a time window", "description": "Returns events across the caller's visible calendars within the `[from, to]` ISO-8601 window. Recurring event masters are expanded server-side into concrete occurrences within the window. `calendars` is an optional comma-separated list of calendar UUIDs to restrict the query.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Window start (ISO-8601 timestamp).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "Window end (ISO-8601 timestamp).", "schema": { "type": "string", "format": "date-time" } }, { "name": "calendars", "in": "query", "required": false, "description": "Comma-separated calendar UUIDs to restrict the query.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Events in the window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "commsCalCreateEvent", "summary": "Create an event", "description": "Creates a new event (or recurring series master / override) in the specified calendar. Timing, attendees, RRULE, reminders, and conferencing are validated server-side.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_EventCreateRequest" } } } }, "responses": { "201": { "description": "Event created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/events/{eventId}": { "get": { "operationId": "commsCalGetEvent", "summary": "Get an event", "description": "Returns a single event. The `calendar_id` query parameter is required.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "description": "Event identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "calendar_id", "in": "query", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `eventId` or `calendar_id` is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "commsCalUpdateEvent", "summary": "Update an event", "description": "Updates event fields. `calendar_id` query parameter is required. For recurring events, `scope` controls whether the edit applies to `this` occurrence, `this_and_following`, or `all`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "description": "Event identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "calendar_id", "in": "query", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "scope", "in": "query", "required": false, "description": "Recurrence edit scope (`this`, `this_and_following`, `all`).", "schema": { "type": "string", "enum": [ "this", "this_and_following", "all" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_EventUpdateRequest" } } } }, "responses": { "200": { "description": "Updated event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "commsCalDeleteEvent", "summary": "Delete an event", "description": "Deletes an event. `calendar_id` query parameter is required. For recurring events, `scope` and `recurrence_id` control which occurrences are removed.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "description": "Event identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "calendar_id", "in": "query", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "scope", "in": "query", "required": false, "description": "Recurrence delete scope.", "schema": { "type": "string", "enum": [ "this", "this_and_following", "all" ] } }, { "name": "recurrence_id", "in": "query", "required": false, "description": "Specific recurrence occurrence id.", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "Event deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/events/{eventId}/move": { "post": { "operationId": "commsCalMoveEvent", "summary": "Move event to another calendar", "description": "Moves an event from one calendar to another within the same organization.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "description": "Event identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_EventMoveRequest" } } } }, "responses": { "200": { "description": "Event moved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/events/{eventId}/rsvp": { "post": { "operationId": "commsCalRsvpEvent", "summary": "RSVP to an event", "description": "Records the caller's RSVP response for an event invitation. Supports proposing an alternative time.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "description": "Event identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_RsvpRequest" } } } }, "responses": { "200": { "description": "RSVP recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/events/{eventId}/reminders": { "put": { "operationId": "commsCalSetReminders", "summary": "Set event reminders", "description": "Replaces the caller's reminder settings for an event.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "description": "Event identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_ReminderSetRequest" } } } }, "responses": { "200": { "description": "Reminders updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/events/{eventId}/publish": { "post": { "operationId": "commsCalPublishEvent", "summary": "Publish or unpublish an event", "description": "Publishes an event to a public render token, or unpublishes it. `calendar_id` query parameter is required.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "description": "Event identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "calendar_id", "in": "query", "required": true, "description": "Calendar identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_EventPublishRequest" } } } }, "responses": { "200": { "description": "Event publish state updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/freebusy": { "get": { "operationId": "commsCalFreeBusy", "summary": "Query free/busy", "description": "Returns busy intervals for one or more calendars or users within the `[from, to]` window. `calendars` and `users` are optional comma-separated UUID lists.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Window start (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "Window end (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "calendars", "in": "query", "required": false, "description": "Comma-separated calendar UUIDs.", "schema": { "type": "string" } }, { "name": "users", "in": "query", "required": false, "description": "Comma-separated user UUIDs.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Free/busy intervals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/search": { "get": { "operationId": "commsCalSearchEvents", "summary": "Search events", "description": "Full-text search across the caller's visible events. `q` is required; `who`, `where`, `from`, `to`, and `limit` (1–200) are optional filters.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query string.", "schema": { "type": "string", "minLength": 1 } }, { "name": "who", "in": "query", "required": false, "description": "Filter by attendee name or email.", "schema": { "type": "string" } }, { "name": "where", "in": "query", "required": false, "description": "Filter by location.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Search window start (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Search window end (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (1–200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/settings": { "get": { "operationId": "commsCalGetUserSettings", "summary": "Get account-wide calendar settings", "description": "Returns the caller's account-wide calendar preferences.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Account calendar settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "commsCalUpdateUserSettings", "summary": "Update account-wide calendar settings", "description": "Updates the caller's account-wide calendar preferences. Body is a free-form JSON object; `org_id` is pinned from the session.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Settings key-value bag.", "additionalProperties": true } } } }, "responses": { "200": { "description": "Updated settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/task-lists": { "get": { "operationId": "commsCalListTaskLists", "summary": "List task lists", "description": "Returns the caller's task lists.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Task lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "commsCalSetTaskList", "summary": "Create, rename, or delete a task list", "description": "Upserts a task list. `action` must be `create`, `rename`, or `delete`. `list_id` is required for `rename` and `delete`; `title` is required for `create` and `rename`.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_TaskListSetRequest" } } } }, "responses": { "200": { "description": "Task list operation applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/tasks": { "post": { "operationId": "commsCalCreateTask", "summary": "Create a task", "description": "Creates a new task in the specified task list.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_TaskCreateRequest" } } } }, "responses": { "201": { "description": "Task created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/tasks/{taskId}": { "patch": { "operationId": "commsCalUpdateTask", "summary": "Update a task", "description": "Updates task fields. All fields are optional.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_TaskUpdateRequest" } } } }, "responses": { "200": { "description": "Updated task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "commsCalDeleteTask", "summary": "Delete a task", "description": "Deletes a task. Pass `cascade=true` to also delete sub-tasks.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "cascade", "in": "query", "required": false, "description": "Delete sub-tasks recursively.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Task deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/tasks/{taskId}/complete": { "post": { "operationId": "commsCalCompleteTask", "summary": "Complete or reopen a task", "description": "Marks a task completed or reopens it. Pass `{ \"completed\": false }` to reopen.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "completed": { "type": "boolean", "description": "Set `false` to reopen the task. Defaults to `true`." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Task completion state updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/tasks/{taskId}/move": { "post": { "operationId": "commsCalMoveTask", "summary": "Move a task", "description": "Moves a task to a different list and/or changes its ordinal position.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Task identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_TaskMoveRequest" } } } }, "responses": { "200": { "description": "Task moved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/sync": { "get": { "operationId": "commsCalListSyncConnections", "summary": "List calendar sync connections", "description": "Returns the caller's external calendar provider connections. Optionally filter by `provider`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "provider", "in": "query", "required": false, "description": "Filter by provider (`google`, `microsoft`, `caldav`).", "schema": { "type": "string", "enum": [ "google", "microsoft", "caldav" ] } } ], "responses": { "200": { "description": "Sync connections.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/sync/connect": { "post": { "operationId": "commsCalSyncConnect", "summary": "Connect a calendar sync provider", "description": "Stores encrypted provider credentials and creates a sync connection. For CalDAV, supply `caldav_password` (plaintext over HTTPS); it is encrypted server-side before storage and is never returned. For Google and Microsoft, use the OAuth flow (`/sync/oauth/{provider}/start`) to obtain tokens and call this endpoint with encrypted token fields, or complete the OAuth flow directly via the OAuth callback routes.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_SyncConnectRequest" } } } }, "responses": { "201": { "description": "Sync connection created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/sync/links": { "post": { "operationId": "commsCalCreateSyncLink", "summary": "Link a provider calendar to a BB calendar", "description": "Creates a sync link pairing an external provider calendar with a Backbuild calendar for bidirectional or one-way sync.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_SyncLinkCreateRequest" } } } }, "responses": { "201": { "description": "Sync link created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/sync/links/{linkId}": { "delete": { "operationId": "commsCalDeleteSyncLink", "summary": "Remove a calendar sync link", "description": "Removes the sync link between a provider calendar and a Backbuild calendar.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "description": "Sync link identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sync link removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/sync/oauth/google/start": { "get": { "operationId": "commsCalOauthGoogleStart", "summary": "Start Google Calendar OAuth flow", "description": "Generates the Google consent URL for the Calendar sync OAuth flow. Returns the authorization URL and a CSRF-bound state token. The client should redirect the user to the returned `url`. Requires the `calendar` feature flag.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Authorization URL generated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CommsCalendar_OauthStartResponse" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — Google calendar sync is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/calendar/sync/oauth/google/callback": { "get": { "operationId": "commsCalOauthGoogleCallbackGet", "summary": "Google Calendar OAuth callback (browser redirect)", "description": "Handles the Google OAuth authorization callback. Validates the CSRF `state` parameter and one-time nonce, exchanges the authorization code for tokens, encrypts them, and stores the connection. Redirects the browser to the calendar settings page with `connected=google` or `sync_error=` on failure. A `?error=access_denied` from the provider redirects immediately without a token exchange.", "tags": [ "Communications & Productivity" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "code", "in": "query", "required": false, "description": "Authorization code from Google.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "CSRF state token from the `/start` response.", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Provider error code (e.g. `access_denied`).", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to calendar settings page." }, "400": { "description": "`VALIDATION_ERROR` — missing/invalid `code`/`state`, or scope mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "commsCalOauthGoogleCallbackPost", "summary": "Google Calendar OAuth callback (SPA form post)", "description": "Same as the GET callback but for SPAs that capture the authorization code client-side and POST `{ code, state }` as a JSON body.", "tags": [ "Communications & Productivity" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "state": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "302": { "description": "Redirect to calendar settings page." }, "400": { "description": "`VALIDATION_ERROR` or `AUTH_OAUTH_FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/sync/oauth/microsoft/start": { "get": { "operationId": "commsCalOauthMicrosoftStart", "summary": "Start Microsoft Calendar OAuth flow", "description": "Generates the Microsoft identity platform consent URL for the Calendar sync OAuth flow. Returns the authorization URL and CSRF state token. Requires the `calendar` feature flag.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Authorization URL generated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CommsCalendar_OauthStartResponse" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — Microsoft calendar sync is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/calendar/sync/oauth/microsoft/callback": { "get": { "operationId": "commsCalOauthMicrosoftCallbackGet", "summary": "Microsoft Calendar OAuth callback (browser redirect)", "description": "Handles the Microsoft OAuth callback — same contract as the Google GET callback.", "tags": [ "Communications & Productivity" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to calendar settings page." }, "400": { "description": "`VALIDATION_ERROR` or `AUTH_OAUTH_FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "commsCalOauthMicrosoftCallbackPost", "summary": "Microsoft Calendar OAuth callback (SPA form post)", "description": "Same as the GET callback but accepts `{ code, state }` as a JSON body from an SPA.", "tags": [ "Communications & Productivity" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "state": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "302": { "description": "Redirect to calendar settings page." }, "400": { "description": "`VALIDATION_ERROR` or `AUTH_OAUTH_FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/sync/providers/{connectionId}/calendars": { "get": { "operationId": "commsCalListProviderCalendars", "summary": "List provider calendars for a connection", "description": "Fetches the list of calendars from the connected external provider (Google or Microsoft) for use in the sync picker. Refreshes the access token server-side if needed; the token is never returned to the caller. CalDAV connections are not supported by this endpoint.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "description": "Sync connection identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Provider calendar list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR` (CalDAV connection).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_OAUTH_FAILED` — the connection must be re-linked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "description": "`EXTERNAL_SERVICE_ERROR` — provider API request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — encryption not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/calendar/appointment-schedules": { "get": { "operationId": "commsCalListAppointmentSchedules", "summary": "List appointment schedules", "description": "Returns the caller's appointment booking schedules. Optionally filter by `calendar_id`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "calendar_id", "in": "query", "required": false, "description": "Filter by calendar (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Appointment schedules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "commsCalSetAppointmentSchedule", "summary": "Create or update an appointment schedule", "description": "Upserts an appointment booking schedule. Supply `id` to update an existing schedule; omit to create a new one. Returns `201` on create, `200` on update.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_AppointmentScheduleSetRequest" } } } }, "responses": { "200": { "description": "Appointment schedule updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "201": { "description": "Appointment schedule created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/appointment-schedules/{scheduleId}": { "get": { "operationId": "commsCalGetAppointmentSchedule", "summary": "Get an appointment schedule", "description": "Returns a single appointment booking schedule.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "description": "Appointment schedule identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Appointment schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/feeds/{token}/basic.ics": { "get": { "operationId": "commsCalGetIcsFeed", "summary": "Download ICS calendar feed (public)", "description": "Resolves a secret or public ICS feed token and returns a well-formed `text/calendar` iCalendar document. The token is validated constant-time; an invalid, revoked, or visibility-`none` token returns `404 NOT_FOUND` with no distinguishing information. Rate-limited per IP at 120 requests per minute.", "tags": [ "Communications & Productivity" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "High-entropy feed token (16–256 URL-safe characters).", "schema": { "type": "string", "minLength": 16, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]{16,256}$" } } ], "responses": { "200": { "description": "iCalendar feed.", "content": { "text/calendar": { "schema": { "type": "string", "description": "RFC 5545 VCALENDAR document." } } } }, "404": { "description": "`NOT_FOUND` — feed token not found or visibility is `none`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/calendar/public/{render_token}": { "get": { "operationId": "commsCalGetPublishedEvent", "summary": "Get a published event (public)", "description": "Resolves a high-entropy render token and returns the published, server-redacted event JSON. The token is validated constant-time; an invalid, revoked, or missing token returns `404`. The raw token is never echoed in the response.", "tags": [ "Communications & Productivity" ], "security": [], "parameters": [ { "name": "render_token", "in": "path", "required": true, "description": "High-entropy render token (16–256 URL-safe characters).", "schema": { "type": "string", "minLength": 16, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]{16,256}$" } } ], "responses": { "200": { "description": "Published event.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "event": { "type": "object", "additionalProperties": true, "description": "Server-redacted event fields." } } } } } ] } } } }, "404": { "description": "`NOT_FOUND` — token not found or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/calendar/book/{slug}": { "get": { "operationId": "commsCalGetBookingPage", "summary": "Get public booking page (public)", "description": "Returns the public-safe appointment schedule metadata for a booking page slug, including optionally the freebusy-level busy intervals for a `[from, to]` window (clamped server-side to 62 days). An unknown slug returns `404`. Rate-limited per IP.", "tags": [ "Communications & Productivity" ], "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Appointment schedule slug.", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,254}$" } }, { "name": "from", "in": "query", "required": false, "description": "Busy-window start (ISO-8601). Required if `to` is provided.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Busy-window end (ISO-8601). Required if `from` is provided.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Booking page data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — slug not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "commsCalCreateBooking", "summary": "Create a booking (public)", "description": "Creates an appointment booking via the public booking page. Requires a valid Cloudflare Turnstile token in `cf-turnstile-response` (evaluated server-side; the field is stripped before storage). The server resolves the schedule by slug, conflict-checks the slot, and creates the event and confirmation email.", "tags": [ "Communications & Productivity" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_BookRequest" } } } }, "responses": { "201": { "description": "Booking created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "description": "`NOT_FOUND` — slug not found or schedule is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the requested time slot is no longer available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/calendar/book/manage/{booking_token}": { "get": { "operationId": "commsCalGetBookingManage", "summary": "Get booking details for management (public)", "description": "Resolves a per-booking management token and returns the booker-safe booking details. Internal fields (`org_id`, owner user id, created event id) are never returned. Rate-limited per IP.", "tags": [ "Communications & Productivity" ], "security": [], "parameters": [ { "name": "booking_token", "in": "path", "required": true, "description": "Per-booking management token (16–256 URL-safe characters).", "schema": { "type": "string", "minLength": 16, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]{16,256}$" } } ], "responses": { "200": { "description": "Booking details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CommsCalendar_BookingManageResponse" } } } ] } } } }, "404": { "description": "`NOT_FOUND` — token not found or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "commsCalManageBooking", "summary": "Cancel or reschedule a booking (public)", "description": "Cancels or reschedules a booking via the per-booking management token. Requires a valid Cloudflare Turnstile token in `cf-turnstile-response`. `reschedule` requires `starts_at`.", "tags": [ "Communications & Productivity" ], "security": [], "parameters": [ { "name": "booking_token", "in": "path", "required": true, "description": "Per-booking management token (16–256 URL-safe characters).", "schema": { "type": "string", "minLength": 16, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]{16,256}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsCalendar_BookManageRequest" } } } }, "responses": { "200": { "description": "Booking updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "description": "`NOT_FOUND` — token not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — requested reschedule slot is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/email/unsubscribe": { "get": { "operationId": "commsEmailUnsubscribeConfirmPage", "summary": "Unsubscribe confirmation page (public)", "description": "Browser-clickable GET endpoint for the RFC 2369 `List-Unsubscribe` header. Verifies the HMAC-signed `token` query parameter and renders a confirmation HTML page with a submit button. Does NOT mutate state — the form POSTs the verified token back to this endpoint to trigger the actual unsubscription. Link prefetchers and crawlers that follow the link will see only the confirmation page and cannot unsubscribe the recipient.", "tags": [ "Communications & Productivity" ], "security": [], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "HMAC-SHA256-signed unsubscribe token (≤ 4096 chars).", "schema": { "type": "string", "maxLength": 4096 } } ], "responses": { "200": { "description": "Confirmation page HTML.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Missing, oversized, or cryptographically invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Unsubscribe endpoint not configured.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "operationId": "commsEmailUnsubscribe", "summary": "One-click unsubscribe (public)", "description": "RFC 8058 one-click `List-Unsubscribe-Post` endpoint and confirmation form submission handler. Verifies the HMAC-signed token (via `?token=` query param, `application/x-www-form-urlencoded` body field, or JSON `token` field), then sets the marketing objection flag on the email address and adds it to the suppression list. Returns `{ unsubscribed: true, email: \"...\" }` on success. Per-IP rate-limited before any HMAC or database work.", "tags": [ "Communications & Productivity" ], "security": [], "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string", "maxLength": 4096 } } } }, "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "maxLength": 4096 } } } } } }, "parameters": [ { "name": "token", "in": "query", "required": false, "description": "HMAC-SHA256-signed unsubscribe token (≤ 4096 chars). Can alternatively be supplied in the request body.", "schema": { "type": "string", "maxLength": 4096 } } ], "responses": { "200": { "description": "Unsubscription recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsMail_UnsubscribeResponse" } } } }, "400": { "description": "Missing, oversized, or cryptographically invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Endpoint not configured.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/integrations/github/authorize": { "get": { "operationId": "commsOtherGithubAuthorize", "summary": "Get GitHub OAuth authorization URL", "description": "Returns the GitHub OAuth authorization URL the client should redirect the user to. The `state` is a signed CSRF JWT (HS256, 10-minute expiry) that must be round-tripped back to `/v1/integrations/github/callback`. Feature-flag gated; returns 503 when the GitHub OAuth application is not configured.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Authorization URL generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_OAuthAuthorizeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "GitHub OAuth not configured. `error.code`: `SERVICE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/github/callback": { "get": { "operationId": "commsOtherGithubCallback", "summary": "Handle GitHub OAuth callback", "description": "Completes the GitHub OAuth flow. Exchanges `code` for an access token, stores the encrypted credential, and returns the connection record. `state` is validated against the signed CSRF JWT issued by the authorize endpoint. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "code", "in": "query", "required": true, "description": "OAuth authorization code from GitHub.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "description": "CSRF state value from the authorize redirect.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "GitHub connection created or updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_GitHubConnectionResponse" } } } }, "400": { "description": "Missing or invalid query parameters. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "CSRF state validation failed. `error.code`: `AUTH_OAUTH_FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GitHub OAuth not configured. `error.code`: `SERVICE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/github/connect": { "post": { "operationId": "commsOtherGithubConnect", "summary": "Connect GitHub via authorization code", "description": "Exchanges a GitHub OAuth authorization code for a stored connection. Validates the `state` CSRF JWT, stores the encrypted OAuth token, and links the connection to the caller's organization. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_GitHubConnectBody" } } } }, "responses": { "200": { "description": "GitHub connection established.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_GitHubConnectionResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR` or `INVALID_JSON`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "CSRF state validation failed or feature disabled. `error.code`: `AUTH_OAUTH_FAILED` or `FEATURE_DISABLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GitHub OAuth not configured. `error.code`: `SERVICE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/github/disconnect": { "post": { "operationId": "commsOtherGithubDisconnect", "summary": "Disconnect GitHub integration", "description": "Revokes the stored GitHub OAuth credential and removes the connection record for the caller's organization.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "GitHub integration disconnected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/integrations/github/repos": { "get": { "operationId": "commsOtherGithubListRepos", "summary": "List accessible GitHub repositories", "description": "Returns repositories accessible via the caller's connected GitHub account. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Repository list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_GitHubRepoListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "GitHub not connected or not configured. `error.code`: `SERVICE_UNAVAILABLE` or `PROVIDER_NOT_CONNECTED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/github/repos/attach": { "post": { "operationId": "commsOtherGithubAttachRepo", "summary": "Attach a GitHub repository to the organization", "description": "Links a GitHub repository (identified by owner, name, and full name) to the caller's organization. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_RepoAttachBody" } } } }, "responses": { "200": { "description": "Repository attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR` or `INVALID_JSON`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/integrations/github/repos/detach": { "post": { "operationId": "commsOtherGithubDetachRepo", "summary": "Detach a GitHub repository from the organization", "description": "Removes a previously linked GitHub repository from the caller's organization.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "repo_id" ], "properties": { "repo_id": { "type": "string", "format": "uuid", "description": "ID of the repository attachment to remove." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Repository detached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/integrations/google/authorize": { "get": { "operationId": "commsOtherGoogleAuthorize", "summary": "Get Google OAuth authorization URL", "description": "Returns the Google OAuth authorization URL. Accepts an optional `?products=` comma-separated list of Backbuild product keys to tailor the requested scopes. The `state` is a signed CSRF JWT. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "products", "in": "query", "required": false, "description": "Comma-separated Backbuild product keys to scope the Google OAuth request.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authorization URL generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_OAuthAuthorizeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "Google OAuth not configured. `error.code`: `SERVICE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/google/connect": { "post": { "operationId": "commsOtherGoogleConnect", "summary": "Connect Google via authorization code", "description": "Completes the Google OAuth flow. Validates the CSRF `state` JWT, exchanges `code` for tokens, and stores the encrypted credential. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_OAuthCodeBody" } } } }, "responses": { "200": { "description": "Google connection established.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR` or `INVALID_JSON`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "CSRF state validation failed. `error.code`: `AUTH_OAUTH_FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Google OAuth not configured. `error.code`: `SERVICE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/google/disconnect": { "post": { "operationId": "commsOtherGoogleDisconnect", "summary": "Disconnect Google integration", "description": "Revokes and removes the stored Google OAuth credential for the caller's organization.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Google integration disconnected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/integrations/cloudflare/authorize": { "get": { "operationId": "commsOtherCloudflareAuthorize", "summary": "Get Cloudflare OAuth authorization URL", "description": "Returns the Cloudflare OAuth (PKCE) authorization URL. Accepts an optional `?purpose=` parameter (`dns` or `worker_sync`) to tailor the requested scopes. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "purpose", "in": "query", "required": false, "description": "Intended use of the Cloudflare connection; influences requested scopes.", "schema": { "type": "string", "enum": [ "dns", "worker_sync" ] } } ], "responses": { "200": { "description": "Authorization URL and PKCE challenge generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_OAuthAuthorizeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "Cloudflare OAuth not configured. `error.code`: `SERVICE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/cloudflare/connect": { "post": { "operationId": "commsOtherCloudflareConnect", "summary": "Connect Cloudflare via authorization code", "description": "Completes the Cloudflare PKCE OAuth flow. Validates the CSRF `state` JWT, exchanges `code` for tokens, and stores the encrypted credential. Applies a scope-allowlist to prevent scope-confusion attacks. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_OAuthCodeBody" } } } }, "responses": { "200": { "description": "Cloudflare connection established.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR` or `INVALID_JSON`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "CSRF state validation failed. `error.code`: `AUTH_OAUTH_FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Cloudflare OAuth not configured. `error.code`: `SERVICE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/integrations/cloudflare/disconnect": { "post": { "operationId": "commsOtherCloudflareDisconnect", "summary": "Disconnect Cloudflare integration", "description": "Revokes and removes the stored Cloudflare OAuth credential for the caller's organization.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Cloudflare integration disconnected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/notifications": { "get": { "operationId": "commsOtherListNotifications", "summary": "List notifications", "description": "Returns a paginated list of notifications for the authenticated user, optionally filtered by channel, type, read status, or time range. Supports `page`/`pageSize` pagination.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number (1-based)." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page." }, { "name": "channel", "in": "query", "schema": { "type": "string", "enum": [ "in_app", "email", "push", "slack" ] }, "description": "Filter by delivery channel." }, { "name": "notification_type", "in": "query", "schema": { "type": "string", "enum": [ "info", "success", "warning", "error", "action_required" ] }, "description": "Filter by notification type." }, { "name": "is_read", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Filter by read status." }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return notifications created after this ISO timestamp." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return notifications created before this ISO timestamp." } ], "responses": { "200": { "description": "Notification list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_NotificationListResponse" } } } }, "400": { "description": "Invalid query parameters. `error.code`: `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Database failure. `error.code`: `DATABASE_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "commsOtherCreateNotification", "summary": "Create a notification", "description": "Creates a notification for the caller or, with `notification.create` permission, for another user. `action_url` must be a Backbuild platform domain. Cross-user creation requires `notification.create` permission; otherwise `403 INSUFFICIENT_PERMISSIONS` is returned.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_NotificationCreateBody" } } } }, "responses": { "201": { "description": "Notification created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_NotificationResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR` or `INVALID_JSON`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Cross-user notification without permission. `error.code`: `INSUFFICIENT_PERMISSIONS`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Database failure. `error.code`: `DATABASE_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/notifications/{notificationId}": { "patch": { "operationId": "commsOtherMarkNotificationRead", "summary": "Mark a notification read/unread", "description": "Toggles the read status of a single notification. Only the notification's target user may update it.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Notification ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_read" ], "properties": { "is_read": { "type": "boolean", "description": "Set to `true` to mark as read, `false` to mark as unread." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Notification updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_NotificationResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "Database failure. `error.code`: `DATABASE_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "commsOtherDeleteNotification", "summary": "Delete a notification", "description": "Permanently deletes a notification. Only the notification's target user may delete it.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Notification ID." } ], "responses": { "200": { "description": "Notification deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "Database failure. `error.code`: `DATABASE_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/notifications/bulk-mark-read": { "post": { "operationId": "commsOtherBulkMarkNotificationsRead", "summary": "Bulk mark notifications as read", "description": "Marks up to 100 notifications as read in a single operation. Only the caller's own notifications may be targeted.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "notification_ids" ], "properties": { "notification_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Array of notification IDs to mark as read." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Notifications marked as read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Database failure. `error.code`: `DATABASE_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/tickets": { "post": { "operationId": "commsOtherCreateTicket", "summary": "Create a support ticket", "description": "Creates a new helpdesk support ticket. Request body is capped at 768 KB. An optional `repro` object attaches a structured issue-reproduction recording to the ticket.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketCreateBody" } } } }, "responses": { "201": { "description": "Ticket created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR` or `INVALID_JSON`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "description": "Request body exceeds the 768 KB limit. `error.code`: `PAYLOAD_TOO_LARGE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "commsOtherListTickets", "summary": "List support tickets", "description": "Returns a paginated list of helpdesk tickets for the caller's organization. Supports limit/offset pagination and optional status/priority filters.", "tags": [ "Communications & Productivity" ], "parameters": [ { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "triage", "in_progress", "waiting_customer", "resolved", "closed" ] }, "description": "Filter by ticket status." }, { "name": "priority", "in": "query", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "description": "Filter by ticket priority." } ], "responses": { "200": { "description": "Ticket list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tickets/{ticketId}": { "get": { "operationId": "commsOtherGetTicket", "summary": "Get a support ticket", "description": "Returns full ticket details including messages and metadata.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "responses": { "200": { "description": "Ticket details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "commsOtherUpdateTicket", "summary": "Update a support ticket", "description": "Updates mutable ticket fields (priority, category). All fields are optional.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketUpdateBody" } } } }, "responses": { "200": { "description": "Ticket updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/messages": { "post": { "operationId": "commsOtherAddTicketMessage", "summary": "Add a message to a ticket", "description": "Appends a message to an existing ticket. Supports `text` and `latex` body formats. Attachments can reference documents or sheets by ID. Up to 10 attachments are allowed.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketMessageBody" } } } }, "responses": { "201": { "description": "Message added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/mine": { "get": { "operationId": "commsOtherListMyTickets", "summary": "List the caller's own tickets", "description": "Returns tickets submitted by the authenticated user.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Maximum number of tickets to return." } ], "responses": { "200": { "description": "Caller's ticket list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tickets/requester-categories": { "get": { "operationId": "commsOtherListRequesterCategories", "summary": "List ticket categories for requesters", "description": "Returns the categories visible to a requester when filing a ticket. Supports optional `saas_package_id` filter.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "saas_package_id", "in": "query", "schema": { "type": "string" }, "description": "SaaS package scope." } ], "responses": { "200": { "description": "Requester category list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tickets/attach-documents": { "get": { "operationId": "commsOtherListAttachableDocuments", "summary": "Search documents attachable to a ticket", "description": "Returns a list of documents accessible to the caller that can be attached to a ticket message. Supports optional `q` search parameter.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query to filter documents." } ], "responses": { "200": { "description": "Attachable document list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tickets/categories/{categoryId}": { "delete": { "operationId": "commsOtherDeleteTicketCategory", "summary": "Delete a ticket category", "description": "Deletes a ticket category by ID.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "categoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Category ID." } ], "responses": { "200": { "description": "Category deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Invalid ID format. `error.code`: `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/canned-responses/{cannedId}": { "delete": { "operationId": "commsOtherDeleteCannedResponse", "summary": "Delete a canned response", "description": "Deletes a saved canned response by ID.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "cannedId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Canned response ID." } ], "responses": { "200": { "description": "Canned response deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Invalid ID format. `error.code`: `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/routing-rules/{ruleId}": { "put": { "operationId": "commsOtherUpdateRoutingRule", "summary": "Update a ticket routing rule", "description": "Replaces a routing rule definition.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Routing rule ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_RoutingRuleBody" } } } }, "responses": { "200": { "description": "Routing rule updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "commsOtherDeleteRoutingRule", "summary": "Delete a ticket routing rule", "description": "Deletes an existing ticket routing rule.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Routing rule ID." } ], "responses": { "200": { "description": "Routing rule deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/status": { "post": { "operationId": "commsOtherUpdateTicketStatus", "summary": "Update ticket status", "description": "Transitions a ticket to a new status.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "triage", "in_progress", "waiting_customer", "resolved", "closed" ], "description": "New ticket status." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Status updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/csat": { "post": { "operationId": "commsOtherSubmitTicketCsat", "summary": "Submit CSAT rating for a ticket", "description": "Records a customer satisfaction score (1–5) and optional comment for a resolved or closed ticket.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "score" ], "properties": { "score": { "type": "integer", "minimum": 1, "maximum": 5, "description": "CSAT score from 1 (very dissatisfied) to 5 (very satisfied)." }, "comment": { "type": "string", "maxLength": 2000, "description": "Optional free-text comment." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "CSAT recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/assign": { "patch": { "operationId": "commsOtherAssignTicket", "summary": "Assign a ticket", "description": "Assigns a ticket to a human agent, AI agent, virtual worker, or unassigns it.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assignee_kind" ], "properties": { "assignee_kind": { "type": "string", "enum": [ "human", "agent", "virtual_worker", "unassigned" ], "description": "Type of assignee." }, "assignee_id": { "type": "string", "format": "uuid", "description": "ID of the assignee. Required unless `assignee_kind` is `unassigned`." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Ticket assigned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/snooze": { "patch": { "operationId": "commsOtherSnoozeTicket", "summary": "Snooze or unsnooze a ticket", "description": "Sets or clears the snooze time on a ticket. Pass `snooze_until: null` to unsnooze.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "snooze_until": { "type": [ "string", "null" ], "maxLength": 40, "description": "ISO 8601 timestamp to snooze until, or `null` to unsnooze." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Snooze updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/merge": { "post": { "operationId": "commsOtherMergeTicket", "summary": "Merge a ticket into another", "description": "Merges this ticket into a target ticket identified by `target_id`. The source ticket is closed after merging.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID to merge from." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_id" ], "properties": { "target_id": { "type": "string", "format": "uuid", "description": "ID of the ticket to merge into." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tickets merged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/watchers": { "get": { "operationId": "commsOtherGetTicketWatchers", "summary": "Get ticket watchers", "description": "Returns the list of users watching this ticket.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "responses": { "200": { "description": "Watcher list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/watch": { "post": { "operationId": "commsOtherToggleTicketWatch", "summary": "Toggle watching a ticket", "description": "Toggles the caller's watch status on a ticket (watch/unwatch).", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "responses": { "200": { "description": "Watch status toggled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/agent": { "get": { "operationId": "commsOtherGetTicketAgent", "summary": "Get full ticket details (agent view)", "description": "Returns full ticket details including internal messages and agent metadata. Intended for helpdesk agents.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "responses": { "200": { "description": "Full ticket (agent view).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/{ticketId}/repro": { "get": { "operationId": "commsOtherGetTicketRepro", "summary": "Get ticket issue-reproduction recording", "description": "Returns the structured issue-reproduction recording (ZA appendix) attached to the ticket at creation.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Ticket ID." } ], "responses": { "200": { "description": "Reproduction recording.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tickets/routing-rules": { "get": { "operationId": "commsOtherListRoutingRules", "summary": "List ticket routing rules", "description": "Returns all routing rules defined for the caller's organization.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Routing rule list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "commsOtherCreateRoutingRule", "summary": "Create a ticket routing rule", "description": "Creates a new routing rule for automatic ticket assignment based on category and priority.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_RoutingRuleBody" } } } }, "responses": { "201": { "description": "Routing rule created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tickets/categories": { "get": { "operationId": "commsOtherListTicketCategories", "summary": "List ticket categories", "description": "Returns the ticket category taxonomy for the caller's organization.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Category list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "commsOtherCreateTicketCategory", "summary": "Create a ticket category", "description": "Creates a new ticket category.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_TicketCategoryBody" } } } }, "responses": { "201": { "description": "Category created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tickets/canned-responses": { "get": { "operationId": "commsOtherListCannedResponses", "summary": "List canned responses", "description": "Returns saved canned responses for the caller's organization.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Canned response list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "commsOtherCreateCannedResponse", "summary": "Create a canned response", "description": "Creates a new canned response for use in ticket replies.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_CannedResponseBody" } } } }, "responses": { "201": { "description": "Canned response created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/helpdesk/categories/effective": { "get": { "operationId": "commsOtherHelpdeskListEffectiveCategories", "summary": "List effective helpdesk categories", "description": "Returns the merged effective category set for a given `saas_package_id` and/or `project_id` tuple. This is the single source of truth for the ticket editor. SP self-gates on `support.read`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "saas_package_id", "in": "query", "schema": { "type": "string" }, "description": "SaaS package ID (hex UUID) to scope effective categories." }, { "name": "project_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Project ID to scope effective categories." } ], "responses": { "200": { "description": "Effective category list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/helpdesk/categories": { "post": { "operationId": "commsOtherHelpdeskSetCategory", "summary": "Create or update a helpdesk dispatch category", "description": "Creates or updates a helpdesk category configuration entry, including inheritance columns, auto-dispatch settings, and dispatch-policy overrides. SP self-gates on `support.config` / `org.update`.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_HelpdeskCategorySetBody" } } } }, "responses": { "200": { "description": "Category saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/helpdesk/categories/{categoryId}": { "delete": { "operationId": "commsOtherHelpdeskDeleteCategory", "summary": "Delete a helpdesk category", "description": "Deletes a helpdesk category row by ID. SP self-gates on `support.config`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "categoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Category ID." } ], "responses": { "200": { "description": "Category deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Invalid ID format. `error.code`: `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/helpdesk/category-workers": { "get": { "operationId": "commsOtherHelpdeskListCategoryWorkers", "summary": "List VW-to-category assignments", "description": "Returns virtual worker assignments for helpdesk categories. Supports optional `category_key`, `saas_package_id`, and `project_id` filters.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "category_key", "in": "query", "schema": { "type": "string", "maxLength": 64 } }, { "name": "saas_package_id", "in": "query", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Worker assignment list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "commsOtherHelpdeskAssignCategoryWorker", "summary": "Assign a virtual worker to a helpdesk category", "description": "Associates a virtual worker with a helpdesk dispatch category. Optionally scoped to a SaaS package or project. The virtual worker must be accessible to the caller (cross-org reject enforced at SP).", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_HelpdeskWorkerAssignBody" } } } }, "responses": { "201": { "description": "Worker assigned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/helpdesk/category-workers/{assignmentId}": { "delete": { "operationId": "commsOtherHelpdeskUnassignCategoryWorker", "summary": "Remove a VW-to-category assignment", "description": "Removes a virtual worker assignment by assignment ID. SP self-gates on `support.config`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assignment ID." } ], "responses": { "200": { "description": "Assignment removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Invalid ID format. `error.code`: `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/helpdesk/auto-dispatch": { "post": { "operationId": "commsOtherHelpdeskSetAutoDispatch", "summary": "Set auto-dispatch for a category", "description": "Enables or disables automatic dispatch for a helpdesk category. ELEVATED: requires MFA step-up (human path); SP enforces elevated grant floor for API-key path.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_HelpdeskAutoDispatchBody" } } } }, "responses": { "200": { "description": "Auto-dispatch setting saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required. `error.code`: `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/helpdesk/pool-status": { "get": { "operationId": "commsOtherHelpdeskGetPoolStatus", "summary": "Get live container pool status", "description": "Returns live per-virtual-worker container and slot occupancy. Optionally filtered by `virtual_worker_id`. SP self-gates on `support.read`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "virtual_worker_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter to a single virtual worker." } ], "responses": { "200": { "description": "Pool status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/helpdesk/slot-config": { "get": { "operationId": "commsOtherHelpdeskGetSlotConfig", "summary": "Get container slot configuration", "description": "Returns the per-worker container slot count configuration.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Slot configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "commsOtherHelpdeskSetSlotConfig", "summary": "Set container slot count for a worker", "description": "Configures the maximum number of concurrent container slots for a virtual worker (1–16). Requires MFA step-up.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "virtual_worker_id", "slot_count" ], "properties": { "virtual_worker_id": { "type": "string", "format": "uuid", "description": "Virtual worker ID." }, "slot_count": { "type": "integer", "minimum": 1, "maximum": 16, "description": "Maximum number of concurrent slots for this worker." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Slot config saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required. `error.code`: `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/helpdesk/pool-policy/get": { "get": { "operationId": "commsOtherHelpdeskGetPoolPolicy", "summary": "Get container pool policy", "description": "Returns the organization's container pool policy (max slots, idle grace period, pool floor, etc.). Read-only; no MFA step-up required.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Pool policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/helpdesk/pool-policy": { "post": { "operationId": "commsOtherHelpdeskSetPoolPolicy", "summary": "Set container pool policy", "description": "Configures the container pool limits and timing policy for the organization's helpdesk workers. Requires MFA step-up.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_HelpdeskPoolPolicyBody" } } } }, "responses": { "200": { "description": "Pool policy saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required. `error.code`: `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/themes": { "get": { "operationId": "commsOtherListThemes", "summary": "List themes", "description": "Returns all themes available to the caller's organization, including system themes and custom org themes.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Theme list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_ThemeListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "commsOtherCreateTheme", "summary": "Create a theme", "description": "Creates a new custom theme. The request must include either `theme_data` (a complete theme object) or all three of `colors`, `typography`, and `layout`. The `name` is required and must be 1–255 characters.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_ThemeMutationBody" } } } }, "responses": { "201": { "description": "Theme created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_ThemeResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR` or `INVALID_JSON`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/themes/{themeId}": { "get": { "operationId": "commsOtherGetTheme", "summary": "Get a theme", "description": "Returns the full definition of a theme by ID.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "themeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Theme ID." } ], "responses": { "200": { "description": "Theme details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_ThemeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "commsOtherUpdateTheme", "summary": "Update a theme", "description": "Replaces a theme's definition. Only custom org themes may be modified. The same `theme_data` vs `colors+typography+layout` rule applies as on create.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "themeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Theme ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_ThemeMutationBody" } } } }, "responses": { "200": { "description": "Theme updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_ThemeResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Attempting to modify a system theme. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Duplicate theme name. `error.code`: `CONFLICT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/secrets/init": { "post": { "operationId": "commsOtherSecretsInit", "summary": "Initialize the secrets vault for a user", "description": "One-time initialization that creates the caller's zero-knowledge identity in the secrets vault. Requires MFA step-up and MFA verification. Rate-limited to 5 requests per 15 minutes per user/IP. The `kdf` parameters must meet the platform floor: `mem_kib` ≥ 19456, `iters` ≥ 2.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_SecretsInitBody" } } } }, "responses": { "200": { "description": "Vault initialized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error or KDF below floor. `error.code`: `VALIDATION_ERROR` or `CRYPTO_FLOOR_VIOLATION`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required. `error.code`: `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/secrets/unlock": { "post": { "operationId": "commsOtherSecretsUnlock", "summary": "Unlock the secrets vault session", "description": "Authenticates the caller's zero-knowledge vault session using their sealed private-key blob. Returns an encrypted session token. Requires MFA step-up and MFA verification. Rate-limited to 12 requests per minute per user/IP. On failure always returns 401 with no oracle information.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_SecretsUnlockBody" } } } }, "responses": { "200": { "description": "Vault unlocked; encrypted session token returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_SecretsUnlockResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Authentication required or unlock failed. `error.code`: `UNAUTHORIZED` or `AUTH_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "MFA step-up required. `error.code`: `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/secrets/lock": { "post": { "operationId": "commsOtherSecretsLock", "summary": "Lock the secrets vault session", "description": "Invalidates the current secrets session, clearing the vault unlock state.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Vault locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/secrets/identity": { "get": { "operationId": "commsOtherSecretsGetIdentity", "summary": "Get secrets identity for the caller", "description": "Returns the caller's encrypted secrets identity blob (sealed private key, salt, KDF parameters). Used by the client to re-derive the vault key without reinitializing.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Secrets identity blob.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_SecretsIdentityResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Identity not initialized. `error.code`: `NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/secrets/master-password": { "put": { "operationId": "commsOtherSecretsChangeMasterPassword", "summary": "Change the master password", "description": "Re-wraps the sealed private-key blob with a new KDF-derived key. Requires MFA step-up and MFA verification. Rate-limited to 12 requests per minute. The new `kdf` parameters must meet the platform KDF floor.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_SecretsMasterPasswordBody" } } } }, "responses": { "200": { "description": "Master password changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error or KDF below floor. `error.code`: `VALIDATION_ERROR` or `CRYPTO_FLOOR_VIOLATION`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required. `error.code`: `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/secrets/vaults": { "get": { "operationId": "commsOtherSecretsListVaults", "summary": "List secrets vaults", "description": "Returns all vaults the caller is a member of within the active environment. Only metadata is returned — no ciphertext.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Vault list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_VaultListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "commsOtherSecretsCreateVault", "summary": "Create a secrets vault", "description": "Creates a new secrets vault in the active environment. Vaults are zero-knowledge by default; a `virtual_worker` vault also carries a server-escrow key wrap for automated substitution.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_VaultCreateBody" } } } }, "responses": { "201": { "description": "Vault created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_VaultResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/secrets/vaults/{vaultId}": { "get": { "operationId": "commsOtherSecretsGetVault", "summary": "Get vault metadata", "description": "Returns metadata for a specific vault. Membership is required to access the vault. No ciphertext is returned.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "responses": { "200": { "description": "Vault metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_VaultResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "commsOtherSecretsUpdateVault", "summary": "Update vault metadata", "description": "Updates the name or description of a vault. Requires vault owner or manager role.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Vault display name." }, "description": { "type": "string", "maxLength": 2000, "description": "Optional vault description." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Vault updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_VaultResponse" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient vault role. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "commsOtherSecretsDeleteVault", "summary": "Delete a vault", "description": "Permanently deletes a vault and all its encrypted items. Requires vault owner role. Requires MFA step-up.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "responses": { "200": { "description": "Vault deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required or insufficient vault role. `error.code`: `MFA_STEPUP_REQUIRED` or `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/vaults/{vaultId}/members": { "get": { "operationId": "commsOtherSecretsListVaultMembers", "summary": "List vault members", "description": "Returns the membership list for a vault. Only vault members may view this list. Non-human members cannot be added.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "responses": { "200": { "description": "Vault member list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "commsOtherSecretsAddVaultMember", "summary": "Add a member to a vault", "description": "Adds a user to a vault with an assigned role (`member`, `manager`, or `owner`). Requires vault manager or owner role. Non-human accounts cannot be added (`403 TARGET_NOT_ELIGIBLE`).", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_id", "role", "sealed_vault_key" ], "properties": { "user_id": { "type": "string", "format": "uuid", "description": "User to add." }, "role": { "type": "string", "enum": [ "member", "manager", "owner" ], "description": "Vault role." }, "sealed_vault_key": { "type": "string", "description": "Client-encrypted vault key sealed to the new member's public key." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Member added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Non-human target or insufficient role. `error.code`: `TARGET_NOT_ELIGIBLE` or `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/vaults/{vaultId}/members/{userId}": { "delete": { "operationId": "commsOtherSecretsRemoveVaultMember", "summary": "Remove a member from a vault", "description": "Removes a user from a vault. Requires vault manager or owner role.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "User ID to remove." } ], "responses": { "200": { "description": "Member removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient vault role. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/vaults/{vaultId}/items": { "get": { "operationId": "commsOtherSecretsListVaultItems", "summary": "List vault items (metadata only)", "description": "Returns item metadata for all items in a vault. The server never returns ciphertext from the AI-accessible metadata endpoint — only name, type, created-at, and tags.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "responses": { "200": { "description": "Item metadata list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "commsOtherSecretsCreateVaultItem", "summary": "Create a vault item", "description": "Stores an encrypted vault item. The encrypted content blob is passed through opaque — the server never decrypts it. Requires vault membership.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_VaultItemCreateBody" } } } }, "responses": { "201": { "description": "Item created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not a vault member. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/vaults/{vaultId}/items/{itemId}": { "get": { "operationId": "commsOtherSecretsGetVaultItem", "summary": "Get an encrypted vault item", "description": "Returns the encrypted content blob for a vault item. Only vault members may retrieve items. The server does not decrypt the content.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Item ID." } ], "responses": { "200": { "description": "Encrypted item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not a vault member. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "commsOtherSecretsUpdateVaultItem", "summary": "Update a vault item", "description": "Replaces the encrypted content blob of an existing vault item. Requires vault membership.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Item ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_VaultItemCreateBody" } } } }, "responses": { "200": { "description": "Item updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not a vault member. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "commsOtherSecretsDeleteVaultItem", "summary": "Delete a vault item", "description": "Moves an item to the trash. Requires vault membership.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Item ID." } ], "responses": { "200": { "description": "Item moved to trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not a vault member. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/trash": { "get": { "operationId": "commsOtherSecretsListTrash", "summary": "List trashed vault items", "description": "Returns all items in the caller's trash across their vaults.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Trash item list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/secrets/trash/{itemId}/restore": { "post": { "operationId": "commsOtherSecretsRestoreTrashItem", "summary": "Restore a trashed vault item", "description": "Restores a previously trashed vault item back to its vault.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Trashed item ID." } ], "responses": { "200": { "description": "Item restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/trash/empty": { "delete": { "operationId": "commsOtherSecretsEmptyTrash", "summary": "Empty the trash", "description": "Permanently deletes all trashed vault items. Requires MFA step-up.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Trash emptied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required. `error.code`: `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/secrets/purge": { "delete": { "operationId": "commsOtherSecretsPurgeIdentity", "summary": "Purge the caller's secrets identity", "description": "Permanently deletes the caller's zero-knowledge secrets identity and all associated vault memberships. Irreversible. Requires MFA step-up and MFA verification.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Identity purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required. `error.code`: `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/secrets/ai/vaults": { "get": { "operationId": "commsOtherSecretsAiListVaults", "summary": "List vault metadata (AI-accessible)", "description": "Returns vault names and types for the caller's organization. No ciphertext or key material is ever included. Intended for AI agents to enumerate available vaults without decrypting content.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Vault metadata list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/secrets/ai/vaults/{vaultId}/items": { "get": { "operationId": "commsOtherSecretsAiListVaultItems", "summary": "List vault item metadata (AI-accessible)", "description": "Returns item names, types, and field names for a vault — never ciphertext or decrypted values. Intended for AI agents to discover available secret slots.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "responses": { "200": { "description": "Item metadata list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/admin-recovery/{targetUserId}": { "get": { "operationId": "commsOtherSecretsAdminRecoveryGet", "summary": "Get admin recovery materials for a user", "description": "Returns the recovery materials needed to re-seal a user's secrets identity during an admin-initiated password reset. Requires `org.manage_members` or `secrets.recover` permission and MFA step-up.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "targetUserId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target user ID." } ], "responses": { "200": { "description": "Recovery materials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions or MFA step-up required. `error.code`: `PERMISSION_DENIED` or `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/admin-recovery/{targetUserId}/reset": { "post": { "operationId": "commsOtherSecretsAdminRecoveryReset", "summary": "Reset a user's secrets vault (admin recovery)", "description": "Re-seals a user's secrets identity with a new sealed private-key blob. Used to reset access when the user has lost their master password. Requires `org.manage_members` or `secrets.recover` permission and MFA step-up. The new `kdf` parameters must meet the platform floor.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "targetUserId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target user ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_SecretsAdminResetBody" } } } }, "responses": { "200": { "description": "Identity reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error or KDF below floor. `error.code`: `VALIDATION_ERROR` or `CRYPTO_FLOOR_VIOLATION`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions or MFA step-up required. `error.code`: `PERMISSION_DENIED` or `MFA_STEPUP_REQUIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/server-escrow-pubkey": { "get": { "operationId": "commsOtherSecretsServerEscrowPubkey", "summary": "Get server escrow public key", "description": "Returns the server's KEM public key used to wrap the vault key for VW (Virtual Worker) vaults. Enables placeholder substitution without exposing human-vault ciphertext.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Server escrow public key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "kemPublic": { "type": "string", "description": "Base64-encoded KEM public key." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Escrow key unavailable. `error.code`: `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/secrets/substitute": { "post": { "operationId": "commsOtherSecretsSubstitute", "summary": "Substitute secret placeholders in text", "description": "Resolves `{{secret://}}` placeholders in the provided text with their decrypted values from VW (Virtual Worker) vaults. Human ZK vaults are never server-decryptable and their placeholders are left intact. Requires `secrets.substitute` scope (container/VW token). The returned text is never logged or re-stored by the server. Input text must be ≤ 100,000 characters.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 100000, "description": "Input text containing `{{secret:...}}` placeholders to resolve." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Text with placeholders resolved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string", "description": "Text with resolved placeholders." }, "substituted": { "type": "integer", "description": "Number of placeholders successfully resolved." } } } } } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/secrets/sync/providers": { "get": { "operationId": "commsOtherSecretsSyncListProviders", "summary": "List secret sync providers", "description": "Returns available secret sync providers (e.g., Cloudflare Workers Secrets) and the caller's connection status for each. No secret values are included.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Provider list with connection status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/secrets/sync/cloudflare/scripts": { "get": { "operationId": "commsOtherSecretsSyncListCfScripts", "summary": "List Cloudflare Workers scripts", "description": "Returns script names from the connected Cloudflare account for use as sync binding targets. Returns an empty list if not connected or lacking `workers:read` scope.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "Script name list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/secrets/sync/bindings": { "get": { "operationId": "commsOtherSecretsSyncListBindings", "summary": "List secret sync bindings", "description": "Returns sync bindings for a vault (and optionally a specific item). Requires `vaultId` (UUID) as a query parameter; callers without vault membership receive 404. Any vault member may read bindings; write operations require manager or owner role.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "vaultId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID (required; membership-gates the listing)." }, { "name": "itemId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Narrow results to a specific vault item." } ], "responses": { "200": { "description": "Binding list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error or missing vaultId. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Vault not found or caller is not a member. `error.code`: `NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "commsOtherSecretsSyncCreateBinding", "summary": "Create or update a secret sync binding", "description": "Creates or updates a binding that maps a vault item field to a provider destination (e.g., a Cloudflare Workers secret). Requires vault manager or owner role and MFA step-up. The `connectionId` must be the caller's own active connection for the provider. The `locator` must lie within the connection's pinned scope (TOCTOU-validated).", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_SyncBindingUpsertBody" } } } }, "responses": { "200": { "description": "Binding created or updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation or locator scope error. `error.code`: `VALIDATION_ERROR`, `PROVIDER_UNAVAILABLE`, or `LOCATOR_SCOPE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required, insufficient vault role, or connection mismatch. `error.code`: `MFA_STEPUP_REQUIRED`, `FORBIDDEN`, or `PROVIDER_NOT_CONNECTED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/secrets/sync/bindings/{bindingId}": { "delete": { "operationId": "commsOtherSecretsSyncDeleteBinding", "summary": "Delete a secret sync binding", "description": "Soft-deletes a sync binding. Requires vault manager or owner role and MFA step-up.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "bindingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Binding ID." } ], "responses": { "200": { "description": "Binding deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required or insufficient vault role. `error.code`: `MFA_STEPUP_REQUIRED` or `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/secrets/sync/push": { "post": { "operationId": "commsOtherSecretsSyncPush", "summary": "Push secret field values to external providers", "description": "Sends client-decrypted field values to their configured external provider destinations (Mode A interactive sync). Each binding is processed independently — one failure does not stop others. The `value` field is write-only: it is never logged, audited, or returned. Requires vault manager or owner role and MFA step-up. Up to 50 syncs per request.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_SyncPushBody" } } } }, "responses": { "200": { "description": "Sync results per binding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "bindingId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "code": { "type": "string", "description": "Error code when status is `error`." } } } } } } } } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "MFA step-up required or insufficient vault role. `error.code`: `MFA_STEPUP_REQUIRED` or `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/devices": { "get": { "operationId": "commsOtherRdpListDevices", "summary": "List registered RDP devices", "description": "Returns registered RDP devices for the caller's organization. Supports optional filters `include_inactive`, `host_only`, and `viewer_only`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "include_inactive", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Include deregistered devices." }, { "name": "host_only", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Return only host-capable devices." }, { "name": "viewer_only", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Return only viewer-capable devices." } ], "responses": { "200": { "description": "Device list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "commsOtherRdpRegisterDevice", "summary": "Register an RDP device", "description": "Registers a device for use with remote desktop. The device submits its post-quantum identity bundle including KEM and signature algorithm IDs. Feature-flag gated for write operations.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_RdpRegisterDeviceBody" } } } }, "responses": { "201": { "description": "Device registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR` or `INVALID_JSON`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Feature not enabled. `error.code`: `FEATURE_DISABLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/devices/{deviceId}": { "delete": { "operationId": "commsOtherRdpDeregisterDevice", "summary": "Deregister an RDP device", "description": "Removes a device from the RDP registry. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Device ID." } ], "responses": { "200": { "description": "Device deregistered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Feature not enabled. `error.code`: `FEATURE_DISABLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/rdp/devices/{hostId}/trust": { "post": { "operationId": "commsOtherRdpTrustDevice", "summary": "Grant viewer trust to a host device", "description": "Grants a viewer device permission to connect to the specified host device, binding the trust to an expected public-key hash. Feature-flag gated.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "hostId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Host device ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_RdpTrustDeviceBody" } } } }, "responses": { "200": { "description": "Trust granted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Feature not enabled. `error.code`: `FEATURE_DISABLED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Public key mismatch detected. `error.code`: `PUBKEY_MISMATCH`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "commsOtherRdpUntrustDevice", "summary": "Revoke viewer trust from a host device", "description": "Removes a viewer device's trust relationship with a host device.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "hostId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Host device ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "viewer_device_id" ], "properties": { "viewer_device_id": { "type": "string", "format": "uuid", "description": "Viewer device to untrust." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Trust revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/rdp/sessions": { "post": { "operationId": "commsOtherRdpAuthorizeSession", "summary": "Authorize an RDP session", "description": "Creates and authorizes a remote desktop session between a host and viewer device. Validates the post-quantum algorithm negotiation. Returns `409 CRYPTO_FLOOR_VIOLATION` (HTTP 426 Upgrade Required) if the negotiated cipher suites fall below the organization's security floor.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_RdpSessionAuthorizeBody" } } } }, "responses": { "201": { "description": "Session authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions. `error.code`: `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "426": { "description": "Negotiated cipher suite below org security floor. `error.code`: `CRYPTO_FLOOR_VIOLATION`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/sessions/{sessionId}": { "delete": { "operationId": "commsOtherRdpEndSession", "summary": "End an RDP session", "description": "Terminates an active RDP session, recording the end reason and final byte counters.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_RdpSessionEndBody" } } } }, "responses": { "200": { "description": "Session ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/rdp/sessions/{sessionId}/consent": { "post": { "operationId": "commsOtherRdpRespondConsent", "summary": "Respond to a session consent request (host)", "description": "Host grants or denies a pending viewer connection. The session's `host_consent_status` transitions to `granted` or `denied`. Returns `409` with `consent_already_decided` if a decision was already made, or `410` with `session_ended` if the session is terminated.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "granted", "denied" ], "description": "Host consent decision." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consent decision recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Caller is not the session host. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Consent already decided. `error.code`: `consent_already_decided`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "Session has ended. `error.code`: `session_ended`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "commsOtherRdpGetConsentStatus", "summary": "Poll session consent status (viewer)", "description": "Returns the current host consent status for a session. Used by the viewer to poll whether the host has granted or denied access. Includes seconds remaining in the consent window.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "responses": { "200": { "description": "Consent status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Caller is not a session participant. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/sessions/{sessionId}/heartbeat": { "post": { "operationId": "commsOtherRdpSessionHeartbeat", "summary": "Send a session heartbeat", "description": "Keeps a session alive and records incremental byte counters. TURN relay usage is attributed from the canonical ICE connection type recorded by the server, not the client-supplied value.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bytes_in_delta", "bytes_out_delta" ], "properties": { "ice_connection_type": { "type": "string", "maxLength": 32, "description": "ICE connection type (e.g., `relay`, `srflx`, `host`)." }, "bytes_in_delta": { "type": "integer", "minimum": 0, "description": "Bytes received since last heartbeat." }, "bytes_out_delta": { "type": "integer", "minimum": 0, "description": "Bytes sent since last heartbeat." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Heartbeat recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/rdp/sessions/{sessionId}/signaling-token": { "post": { "operationId": "commsOtherRdpIssueSignalingToken", "summary": "Issue a WebRTC signaling token", "description": "Issues an HMAC-signed one-time signaling token for joining the RDP signaling DO. The token encodes the caller's role (`host` or `viewer`), a unique `jti`, and the DO session ID. Returns `403 CONSENT_PENDING` if the host has not yet responded to the consent prompt, or `403 CONSENT_DENIED` if access was denied.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "host", "viewer" ], "description": "The role the caller will play in the signaling session." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Signaling token issued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string", "description": "Signed signaling token." }, "expires_at": { "type": "string", "format": "date-time" }, "do_session_id": { "type": "string", "description": "Durable Object session ID." }, "ws_url": { "type": "string", "description": "WebSocket upgrade path for the signaling connection." } } } } } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Consent pending or denied. `error.code`: `CONSENT_PENDING` or `CONSENT_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/sessions/{sessionId}/turn-credentials": { "post": { "operationId": "commsOtherRdpIssueTurnCredentials", "summary": "Issue TURN relay credentials", "description": "Issues RFC 5766 TURN credentials for the session. Checks the per-org 24-hour bandwidth quota (fail-closed); returns `429 quota_exceeded` if exhausted. Credentials are bound to the caller's user ID and source IP — mismatched heartbeats will not attribute relay bytes to prevent credential-sharing abuse.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "responses": { "200": { "description": "TURN credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "username": { "type": "string", "description": "TURN username (bound to expiry, session, user, and IP)." }, "credential": { "type": "string", "description": "HMAC-derived TURN credential." }, "ttl": { "type": "integer", "description": "Credential TTL in seconds." }, "uris": { "type": "array", "items": { "type": "string" }, "description": "TURN server URIs (`turn:` or `turns:` scheme only)." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Org context missing. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "24-hour TURN bandwidth quota exceeded. `error.code`: `quota_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TURN quota DO unreachable or relay not configured. `error.code`: `INTERNAL_ERROR` or `SERVICE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/sessions/{sessionId}/diagnostics": { "get": { "operationId": "commsOtherRdpGetSessionDiagnostics", "summary": "Get RDP session diagnostics", "description": "Returns session diagnostics including ICE connection stats and byte counters. Accessible by session participants and admins.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "responses": { "200": { "description": "Session diagnostics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not a session participant or admin. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/signal/{doSessionId}": { "get": { "operationId": "commsOtherRdpSignalingUpgrade", "summary": "Upgrade to WebRTC signaling WebSocket", "description": "Upgrades the connection to a WebSocket for WebRTC signaling. The caller must present a valid HMAC-signed signaling token via the `?token=` query parameter, the `X-RDP-Signaling-Token` header, or the `X-RDP-Token` header. The token must be bound to the requested `doSessionId`. Returns `426` if the `Upgrade: websocket` header is absent.", "tags": [ "Communications & Productivity" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "doSessionId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Durable Object signaling session ID (org-scoped: `:`)." }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "HMAC-signed signaling token (alternative to header)." } ], "responses": { "101": { "description": "WebSocket upgrade accepted; signaling session established." }, "400": { "description": "Invalid session ID format. `error.code`: `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing, invalid, or expired signaling token. `error.code`: `UNAUTHORIZED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "426": { "description": "WebSocket upgrade header missing. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/audit-log": { "get": { "operationId": "commsOtherRdpListAuditLog", "summary": "List RDP audit log entries", "description": "Returns paginated RDP audit log entries. Requires `rdp.admin` permission. Supports cursor-based pagination (base64url-encoded JSON `{occurred_at, id}`) and optional filters. Response carries `Cache-Control: no-store`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024 }, "description": "Pagination cursor (opaque base64url-encoded value)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Maximum results to return." }, { "name": "action", "in": "query", "schema": { "type": "string", "maxLength": 128 }, "description": "Filter by audit action name." }, { "name": "device_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by device ID." }, { "name": "actor_user_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by actor user ID." }, { "name": "session_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by session ID." }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return entries after this timestamp." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return entries before this timestamp." } ], "responses": { "200": { "description": "Audit log entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Invalid parameter or cursor. `error.code`: `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/audit-log/export": { "post": { "operationId": "commsOtherRdpExportAuditLog", "summary": "Export RDP audit log as CSV", "description": "Exports up to 5,000 RDP audit log entries as a CSV file. Supports the same filters as the list endpoint. CSV values are sanitized against formula-injection (OWASP). Requires `rdp.admin` permission.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommsOther_RdpAuditExportBody" } } } }, "responses": { "200": { "description": "CSV file attachment.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Validation error. `error.code`: `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/turn-quota": { "get": { "operationId": "commsOtherRdpGetTurnQuota", "summary": "Get TURN relay bandwidth quota", "description": "Returns the organization's current TURN relay bandwidth usage within the rolling 24-hour window. Requires `rdp.admin` permission.", "tags": [ "Communications & Productivity" ], "responses": { "200": { "description": "TURN quota status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "bytes_used_24h": { "type": "integer", "description": "Bytes used in the rolling 24-hour window." }, "bytes_cap": { "type": "integer", "description": "Per-org 24-hour byte cap." }, "issuances_24h": { "type": "integer", "description": "Number of TURN credential issuances in the window." }, "window_ms": { "type": "integer", "description": "Window duration in milliseconds." }, "window_started_at": { "type": "integer", "description": "Window start timestamp (Unix ms)." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient permissions. `error.code`: `FORBIDDEN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rdp/my-data-export": { "get": { "operationId": "commsOtherRdpMyDataExport", "summary": "Export the caller's RDP data (GDPR Art. 15)", "description": "Returns all RDP device registrations, sessions, and audit events for the authenticated caller. GDPR Article 15 self-service data access. Response carries `Cache-Control: no-store, private`.", "tags": [ "Communications & Productivity" ], "parameters": [ { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Export data after this timestamp." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Export data before this timestamp." }, { "name": "max_rows", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000 }, "description": "Maximum number of records to include." } ], "responses": { "200": { "description": "Caller's RDP data export.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Invalid parameter. `error.code`: `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/rdp/my-data-forget": { "post": { "operationId": "commsOtherRdpMyDataForget", "summary": "Erase the caller's RDP data (GDPR Art. 17)", "description": "Pseudonymizes or deletes the caller's RDP device registrations, sessions, and audit records. GDPR Article 17 self-service erasure. Optionally scoped to a single organization.", "tags": [ "Communications & Productivity" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Optional: scope erasure to a single organization." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Erasure completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/containers/.well-known/jwks.json": { "get": { "operationId": "containersGetJwks", "summary": "Get container token JWKS", "description": "Returns the Ed25519 public key set (JWKS) used to verify container connect tokens and data tokens offline (alg=EdDSA). Serves the public key only — the private signing key is never reachable here. Returns an empty key set (200) when no key is configured so a verifier always receives a well-formed JWKS. Cache-Control is set to `public, max-age=300`; verifiers should refresh after that window.", "tags": [ "Containers & Virtual Workers" ], "security": [], "responses": { "200": { "description": "The JWKS. `keys` contains zero or one Ed25519 public key entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_Jwks" } } } } } } }, "/v1/containers/policy": { "get": { "operationId": "containersGetPolicy", "summary": "Get org container execution policy", "description": "Returns the organization-wide container execution policy (allowed backends, sizes, default backend/size, idle settings, billing mode, residency constraints, and the master on/off toggle). The organization is resolved from the session.", "tags": [ "Containers & Virtual Workers" ], "responses": { "200": { "description": "The org container execution policy.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Containers_ExecutionPolicy" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "containersSetPolicy", "summary": "Set org container execution policy", "description": "Replaces the organization-wide container execution policy. All fields are optional; absent fields are left unchanged. `containers_enabled: false` disables container provisioning for every member of the org and environment.", "tags": [ "Containers & Virtual Workers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_SetPolicyRequest" } } } }, "responses": { "200": { "description": "Policy updated. Returns the updated policy.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Containers_ExecutionPolicy" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/policy/projects/{projectId}": { "get": { "operationId": "containersGetProjectPolicy", "summary": "Get per-project container policy override", "description": "Returns the per-project container execution policy override. When no override is set all fields are null, meaning the project inherits the org policy.", "tags": [ "Containers & Virtual Workers" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "The per-project policy override (null fields = inherit org policy).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Containers_ProjectPolicy" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "containersSetProjectPolicy", "summary": "Set per-project container policy override", "description": "Replaces the per-project container execution policy override. Pass `clear: true` to delete the override and fall back to the org policy. Setting a field to `null` means \"inherit the org value\". `allowed_backends` and `allowed_sizes` must be subsets of the org policy's allow-sets (validated server-side).", "tags": [ "Containers & Virtual Workers" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_SetProjectPolicyRequest" } } } }, "responses": { "200": { "description": "Per-project override updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Containers_ProjectPolicy" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/sizes": { "get": { "operationId": "containersListSizes", "summary": "List container size catalog", "description": "Returns the container size catalog entries available to the caller's organization, including CPU, memory, and per-hour credit cost for each size and backend combination.", "tags": [ "Containers & Virtual Workers" ], "responses": { "200": { "description": "The size catalog entries.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Containers_SizeCatalogEntry" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers": { "post": { "operationId": "containersSpinUp", "summary": "Spin up a container session", "description": "Provisions a new container session on the requested backend and size. The organization and environment are resolved from the session; the caller never passes `org_id`. The backend and size must be within the org/project execution policy. Optionally binds the session to a project (applies the per-project policy override). Returns immediately with the session record; the container transitions to `running` asynchronously.", "tags": [ "Containers & Virtual Workers" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_SpinUpRequest" } } } }, "responses": { "201": { "description": "Session provisioned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Containers_Session" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`PERMISSION_DENIED` (missing required permission), `FORBIDDEN` (containers disabled by org/project policy), `BILLING_TIER_UPGRADE_REQUIRED` (plan does not include containers), or `BILLING_ADDON_REQUIRED` (container add-on not purchased).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`QUOTA_EXCEEDED` — the org's `max_concurrent` container limit is reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/{sessionId}": { "get": { "operationId": "containersGetSession", "summary": "Get container session status", "description": "Returns the current status and metadata for a container session. Sessions belonging to another organization are reported as `404 NOT_FOUND` (anti-enumeration).", "tags": [ "Containers & Virtual Workers" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Container session identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The session record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Containers_Session" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "containersTeardown", "summary": "Tear down a container session", "description": "Gracefully stops the container and marks the session as torn down. An optional `reason` query parameter is recorded in the audit trail.", "tags": [ "Containers & Virtual Workers" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Container session identifier (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "reason", "in": "query", "required": false, "description": "Human-readable teardown reason recorded in the audit trail.", "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Session torn down.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Containers_Session" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/{sessionId}/connect": { "post": { "operationId": "containersConnect", "summary": "Issue a connect ticket and UI token", "description": "Issues a one-time WebSocket connect ticket and a short-TTL Ed25519 UI connect token for the specified session. The ticket is a single-use opaque capability redeemed by the in-container gateway on the WebSocket upgrade; the connect token is an Ed25519 JWT presented to the gateway. Both are bound to the calling user and the session id. The session must be in `running` or `idle` state and must belong to the calling user's org/env. Also returns the public gateway URL (`endpoint`) when the ingress domain is configured.", "tags": [ "Containers & Virtual Workers" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Container session identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Connect ticket and UI token issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Containers_ConnectResponse" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`PERMISSION_DENIED` (not the session owner) or `FORBIDDEN` (session not in a live state).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/saas/{packageId}/config": { "get": { "operationId": "containersGetSaasConfig", "summary": "Get SaaS package container config", "description": "Returns the container configuration for a SaaS package, including whether containers are enabled and which backends and sizes the package's subscribers may use.", "tags": [ "Containers & Virtual Workers" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SaaS package container configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Containers_SaasConfig" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "containersSetSaasConfig", "summary": "Set SaaS package container config", "description": "Replaces the container configuration for a SaaS package. Controls which backends and sizes the package's subscribers may use and whether containers are enabled for that package at all.", "tags": [ "Containers & Virtual Workers" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_SetSaasConfigRequest" } } } }, "responses": { "200": { "description": "SaaS package container config updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Containers_SaasConfig" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/saas/{packageId}/resale": { "post": { "operationId": "containersSetResalePrice", "summary": "Set container resale pricing for a SaaS package", "description": "Sets the per-hour resale credit cost for a specific backend + size combination for a SaaS package. This markup is charged to the package's subscribers when they use containers with that combination.", "tags": [ "Containers & Virtual Workers" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_SetResalePriceRequest" } } } }, "responses": { "200": { "description": "Resale pricing updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/gw/{sizeKey}/{sessionId}/code-api-config": { "get": { "operationId": "containersGatewayCodeApiConfig", "summary": "Fetch code-API config for a CF sandbox container", "description": "Used by a Cloudflare sandbox container to retrieve its per-session code-API configuration (bridge URL and short-TTL bridge token). The container presents its `x-bb-config-fetch` credential in a request header; the API validates it against the session's stored hash via the backing Durable Object. Returns only `{ bridge_url, token }` — never the secret reference or refresh credential. `Cache-Control: no-store` is always set. Returns `401` for an invalid/missing credential and `404` for an unknown size or session.", "tags": [ "Containers & Virtual Workers" ], "security": [], "parameters": [ { "name": "sizeKey", "in": "path", "required": true, "description": "Canonical sandbox size key (e.g. `standard-1`). Used to route to the correct Durable Object namespace.", "schema": { "type": "string", "maxLength": 64 } }, { "name": "sessionId", "in": "path", "required": true, "description": "Container session identifier used as the Durable Object name.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "x-bb-config-fetch", "in": "header", "required": true, "description": "Per-session config-fetch credential injected into the container at provision time.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bridge URL and short-TTL token returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_CodeApiConfig" } } } }, "401": { "description": "`AUTH_REQUIRED` — the config-fetch credential is missing, invalid, or already used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — unknown `sizeKey` or no gateway bundle for this session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/containers/data/whoami": { "get": { "operationId": "containersDataWhoami", "summary": "Get the in-container agent's own identity", "description": "Returns the resolved identity of the in-container agent — user id, org id, environment id, session id, and delegated scope set — derived offline from the verified data token. No database call is made. Authorized by the container data token.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "containerDataToken": [] } ], "responses": { "200": { "description": "The agent's resolved identity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Containers_ContainerIdentity" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/containers/data/session": { "get": { "operationId": "containersDataGetOwnSession", "summary": "Get the agent's own container session status", "description": "Returns the container session record for the calling agent's own session. The session id is taken from the verified data token — the agent cannot read another session by guessing an id. Authorized by the container data token.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "containerDataToken": [] } ], "responses": { "200": { "description": "The container session record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Containers_Session" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/data/sizes": { "get": { "operationId": "containersDataListSizes", "summary": "List container sizes (data-plane, read context)", "description": "Returns the container size catalog for the calling agent's organization. Provisioning new containers is denied to delegated actors. Authorized by the container data token.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "containerDataToken": [] } ], "responses": { "200": { "description": "Size catalog entries.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Containers_SizeCatalogEntry" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/data/session-log": { "post": { "operationId": "containersDataAppendSessionLog", "summary": "Append a session-log chunk", "description": "Writes one immutable NDJSON chunk of `SessionLogEvent` records to the session's R2 log store. The org and session prefix are derived from the verified data token — the agent can only write under its own session prefix. Requires scope `terminal.activity.write`. An optional monotonic `chunk_seq` may be supplied as a query parameter or `x-session-log-chunk-seq` header to derive the object key; if omitted the key is the SHA-256 of the body (idempotent re-POST). Max size is enforced via `Content-Length` pre-check and a buffered re-check.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "containerDataToken": [] } ], "parameters": [ { "name": "chunk_seq", "in": "query", "required": false, "description": "Monotonic non-negative integer chunk sequence number.", "schema": { "type": "integer", "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/x-ndjson": { "schema": { "type": "string", "description": "NDJSON `SessionLogEvent` records (one per line) or a JSON array of the same shape. Max 1 MiB." } }, "application/json": { "schema": { "type": "array", "description": "Array of `SessionLogEvent` objects. Max 1 MiB total." } } } }, "responses": { "201": { "description": "Chunk stored.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Containers_SessionLogAppendResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the data token lacks scope `terminal.activity.write`, or the delegated denylist blocked this call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — the chunk exceeds the maximum allowed size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — session-log storage is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "containersDataGetSessionLog", "summary": "Read back the agent's own session log", "description": "Lists and concatenates the persisted NDJSON chunks for the calling agent's own session in chunk-sequence order. The org and session prefix are derived from the verified data token (IDOR guard). Bounded list pagination and a concatenation cap (32 MiB, 2000 chunks) prevent unbounded buffering; `truncated: true` signals that more chunks remain.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "containerDataToken": [] } ], "responses": { "200": { "description": "Session log chunks concatenated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Containers_SessionLogReadResponse" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — session-log storage is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/containers/data/terminal/activity": { "post": { "operationId": "containersDataAppendTerminalActivity", "summary": "Append a terminal activity batch", "description": "Writes one bounded batch of already-redacted terminal `ActivityEvent` records to the activity index. The batch's `containerSessionId` must match the principal's own session id. Requires scope `terminal.activity.write`.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "containerDataToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_TerminalActivityBatch" } } } }, "responses": { "200": { "description": "Activity batch recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — scope `terminal.activity.write` missing, `containerSessionId` mismatch, or delegated denylist blocked this call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — the batch exceeds the maximum allowed size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/data/terminal/transcript": { "post": { "operationId": "containersDataAppendTranscript", "summary": "Append a terminal bulk-transcript segment", "description": "Writes one immutable terminal bulk-transcript segment (redacted NDJSON, ≤16 MiB) to R2 keyed by the principal's org/session prefix, then records the R2 key and advances the monotonic segment watermark in the database. `transcript_seq` is required; `terminal_id` is optional but recommended. Both may be supplied as query parameters or the `x-terminal-id` / `x-transcript-seq` headers. Requires scope `terminal.activity.write`.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "containerDataToken": [] } ], "parameters": [ { "name": "terminal_id", "in": "query", "required": false, "description": "Terminal identifier. Also accepted via `x-terminal-id` header.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "transcript_seq", "in": "query", "required": false, "description": "Monotonic non-negative integer segment sequence number. Also accepted via `x-transcript-seq` header.", "schema": { "type": "integer", "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/x-ndjson": { "schema": { "type": "string", "description": "Redacted NDJSON terminal transcript segment. Max 16 MiB." } } } }, "responses": { "200": { "description": "Segment persisted and watermark advanced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR` — `transcript_seq` is missing or invalid, body is empty or unreadable, or terminal id is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — scope `terminal.activity.write` missing, or delegated denylist blocked this call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — the segment exceeds 16 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — transcript storage is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/containers/data/agent/task": { "get": { "operationId": "containersDataGetAgentTask", "summary": "Pull the next agent task for a Virtual Worker session", "description": "The in-pod agentic CLI runner pulls the task dispatched to this session. The session is resolved from the verified data token (IDOR guard). Requires scope `agent.task.read`. Returns `null` when no task is pending.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "containerDataToken": [] } ], "responses": { "200": { "description": "The pending agent task, or null when no task is queued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Containers_AgentTask" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the data token lacks scope `agent.task.read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/containers/data/agent/task/complete": { "post": { "operationId": "containersDataCompleteAgentTask", "summary": "Report Virtual Worker task completion", "description": "The in-pod runner reports the task result. `virtual_worker_id` and `worker_task_id` come from the task pull; the server re-validates both belong to this session (any mismatch is a 4xx). Requires scope `agent.task.complete`. Bridges to the cron-gated completion stored procedure using a platform-side credential the agent never holds.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "containerDataToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_AgentTaskCompleteRequest" } } } }, "responses": { "200": { "description": "Task completion recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR` — `virtual_worker_id` or `worker_task_id` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the data token lacks scope `agent.task.complete`, or the delegated denylist blocked this call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the `virtual_worker_id` or `worker_task_id` does not belong to this session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — task completion is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sandbox": { "post": { "operationId": "containersProvisionSandbox", "summary": "Provision a sandbox container", "description": "Provision a new Cloudflare Container DO sandbox session. Generates a session ID, registers billing, and starts the container. The orgId is prepended to all R2 artifact paths to prevent cross-org IDOR.\n\nThe caller needs `project.update` permission when a `project_id` is provided.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sessionId": { "type": "string", "format": "uuid", "description": "Optional caller-supplied session ID. If omitted the server generates one." }, "size": { "type": "string", "enum": [ "small", "standard", "large" ], "description": "Container size class. Maps to `SandboxContainerSmall`, `SandboxContainerStandard`, or `SandboxContainerLarge`." }, "gitRepo": { "type": "string", "maxLength": 512, "description": "Optional Git repository to clone on startup." }, "gitBranch": { "type": "string", "maxLength": 256, "description": "Branch or ref to check out. Defaults to the repo default branch." }, "envVars": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Environment variables injected at container start." }, "language": { "type": "string", "maxLength": 64, "description": "Runtime language hint (e.g. `node`, `python`)." }, "project_id": { "type": "string", "format": "uuid", "description": "Optional project to attribute this session to." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Arbitrary metadata stored with the session." }, "timeout_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "Idle-timeout override in seconds." } } } } } }, "responses": { "201": { "description": "Sandbox provisioned successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Containers_Session" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/status/{sessionId}": { "get": { "operationId": "containersGetSandboxStatus", "summary": "Get sandbox session status", "description": "Returns the live status of a sandbox session, including container state, whether the session can be resumed, and sandbox-specific metadata.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." } ], "responses": { "200": { "description": "Session status retrieved.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "active": { "type": "boolean" }, "status": { "type": "string" }, "session": { "$ref": "#/components/schemas/Containers_Session" }, "container": { "type": [ "object", "null" ], "description": "Raw container state from the DO." }, "canResume": { "type": "boolean" }, "sandboxInfo": { "type": [ "object", "null" ], "additionalProperties": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/resume/{sessionId}": { "post": { "operationId": "containersResumeSandbox", "summary": "Resume a stopped sandbox session", "description": "Re-starts a previously stopped sandbox session and restores its last snapshot. Requires `project.update` permission.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." } ], "responses": { "200": { "description": "Session resume initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/teardown/{sessionId}": { "post": { "operationId": "containersTeardownSandbox", "summary": "Tear down a sandbox session", "description": "Stops the container, finalises billing, and deletes the session. Requires `project.update` permission.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." } ], "responses": { "200": { "description": "Sandbox torn down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/terminal/{sessionId}": { "post": { "operationId": "containersSandboxTerminal", "summary": "Sandbox terminal action", "description": "Perform a terminal action inside the sandbox: create a named multiplexed terminal, write input, read pending output, or execute a one-shot command. Requires `project.update` permission.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "create", "write", "read", "exec" ], "description": "Terminal sub-action." }, "sessionName": { "type": "string", "maxLength": 128, "description": "Named multiplexed terminal session (for `create`, `write`, `read`)." }, "input": { "type": "string", "description": "Input data to write (for `write`)." }, "command": { "type": "string", "maxLength": 4096, "description": "Shell command to execute (for `exec`)." }, "timeout": { "type": "integer", "minimum": 1, "maximum": 300, "description": "Execution timeout in seconds (for `exec`). Defaults to 30." }, "workdir": { "type": "string", "maxLength": 512, "description": "Working directory (for `exec`)." } } } } } }, "responses": { "200": { "description": "Terminal action succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/egress/{sessionId}": { "get": { "operationId": "containersSandboxEgressGet", "summary": "Sandbox egress proxy (GET)", "description": "Proxies an HTTP GET from the sandbox to an external domain. The target URL must be supplied via the `x-bb-egress-target` header or the `target` query parameter. The domain is validated against the org's egress allowlist, and egress byte usage is reserved before forwarding. Requires `project.update` permission.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." }, { "name": "x-bb-egress-target", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Full target URL to proxy the request to. Takes precedence over the `target` query parameter." }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Full target URL when the header is absent." } ], "responses": { "200": { "description": "Upstream response proxied transparently." }, "400": { "description": "Missing or invalid egress target. Error code: `INVALID_REQUEST`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Domain not in allowlist or egress quota exceeded. Error codes: `FORBIDDEN`, `LIMIT_EXCEEDED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "containersSandboxEgressPost", "summary": "Sandbox egress proxy (POST)", "description": "Proxies an HTTP POST from the sandbox to an external domain. Same domain allowlist and quota reservation as GET. Requires `project.update` permission.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." }, { "name": "x-bb-egress-target", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Full target URL." }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Full target URL when the header is absent." } ], "requestBody": { "required": false, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Upstream response proxied transparently." }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/proxy-session/revoke-all": { "post": { "operationId": "containersSandboxRevokeAllProxySessions", "summary": "Revoke all sandbox proxy cookies for the current user", "description": "Invalidates every active `__Secure-bb_sandbox_proxy` HttpOnly cookie previously issued to the authenticated user. Call this on logout or credential rotation.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "All proxy cookies revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/proxy-session/{sessionId}": { "post": { "operationId": "containersSandboxCreateProxySession", "summary": "Create a sandbox proxy cookie", "description": "Mints a short-lived (5-minute) `__Secure-bb_sandbox_proxy` cookie (HttpOnly, Secure, SameSite=None) that authorises transparent proxying through `/v1/sandbox/proxy/{sessionId}/*`. Rate-limited.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session to issue the proxy cookie for." } ], "responses": { "200": { "description": "Proxy cookie set in the `Set-Cookie` response header.", "headers": { "Set-Cookie": { "description": "`__Secure-bb_sandbox_proxy=; HttpOnly; Secure; SameSite=None; Path=/v1/sandbox/proxy/{sessionId}/; Max-Age=300`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/proxy/{sessionId}/{path}": { "get": { "operationId": "containersSandboxProxy", "summary": "Transparent proxy into sandbox container", "description": "Transparently proxies any HTTP method into the running Cloudflare Container DO for this session. Authentication is via the `__Secure-bb_sandbox_proxy` cookie issued by `POST /v1/sandbox/proxy-session/{sessionId}`. All traffic is org-scoped at the DO level — the orgId prefix in the container name prevents cross-org IDOR.", "tags": [ "Containers & Virtual Workers" ], "security": [], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Remainder of the path inside the container." } ], "responses": { "200": { "description": "Response from the container application proxied transparently." }, "401": { "description": "Missing or invalid proxy cookie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sandbox/vscode/{sessionId}": { "get": { "operationId": "containersSandboxVscode", "summary": "Redirect to VS Code server", "description": "302 redirect to the VS Code code-server endpoint proxied through `/v1/sandbox/proxy/{sessionId}/code-server/`. Requires the proxy cookie to be set first via `POST /v1/sandbox/proxy-session/{sessionId}`.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." } ], "responses": { "302": { "description": "Redirect to `/v1/sandbox/proxy/{sessionId}/code-server/`.", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/sandbox/jupyter/{sessionId}": { "get": { "operationId": "containersSandboxJupyter", "summary": "Redirect to Jupyter Lab", "description": "302 redirect to the Jupyter Lab endpoint proxied through `/v1/sandbox/proxy/{sessionId}/jupyter/lab`. Requires the proxy cookie to be set first.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." } ], "responses": { "302": { "description": "Redirect to `/v1/sandbox/proxy/{sessionId}/jupyter/lab`.", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/sandbox/display/{sessionId}": { "get": { "operationId": "containersSandboxDisplay", "summary": "Redirect to remote display (Xpra)", "description": "302 redirect to the Xpra remote-display endpoint proxied through `/v1/sandbox/proxy/{sessionId}/xpra/`. Requires the proxy cookie to be set first.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." } ], "responses": { "302": { "description": "Redirect to `/v1/sandbox/proxy/{sessionId}/xpra/`.", "headers": { "Location": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/sandbox/artifacts/{sessionId}": { "get": { "operationId": "containersSandboxListArtifacts", "summary": "List sandbox artifacts", "description": "Lists R2 artifact objects for this sandbox session. Each key is prefixed with the org ID to prevent cross-org object enumeration.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." } ], "responses": { "200": { "description": "Artifact list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "size": { "type": "integer" }, "uploaded": { "type": "string", "format": "date-time" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/artifacts/{sessionId}/{name}": { "get": { "operationId": "containersSandboxDownloadArtifact", "summary": "Download a sandbox artifact", "description": "Downloads a specific named artifact from R2. The `Content-Type` header is enforced based on safe file extension mapping — arbitrary types are not forwarded from R2 metadata to prevent content-type sniffing attacks.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 }, "description": "Artifact name (filename)." } ], "responses": { "200": { "description": "Artifact file contents.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sandbox/snapshot-info/{sessionId}": { "get": { "operationId": "containersSandboxSnapshotInfo", "summary": "Get sandbox snapshot metadata", "description": "Returns metadata for the most recent R2 snapshot of this sandbox session, if one exists.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox session ID." } ], "responses": { "200": { "description": "Snapshot metadata.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "snapshot_key": { "type": [ "string", "null" ] }, "snapshot_size": { "type": [ "integer", "null" ] }, "snapshot_uploaded": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/terminal/sessions": { "post": { "operationId": "containersCreateTerminalSession", "summary": "Create a terminal session", "description": "Registers a new CLI/IDE terminal session and returns a one-time producer ticket used to upgrade the WebSocket connection at `GET /v1/terminal/ws`.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "org_id", "cli_tool", "cwd", "host_machine_id" ], "additionalProperties": false, "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Organization to create the session under." }, "cli_tool": { "type": "string", "maxLength": 64, "description": "Identifier of the CLI tool creating the session (e.g. `bb-cli`, `vscode-extension`)." }, "cwd": { "type": "string", "maxLength": 4096, "description": "Current working directory on the host machine." }, "host_machine_id": { "type": "string", "maxLength": 128, "description": "Stable identifier of the host machine." }, "host_extension_id": { "type": "string", "maxLength": 128, "description": "Extension or plugin instance identifier on the host." }, "cli_session_id": { "type": "string", "format": "uuid", "description": "Optional caller-supplied session ID." }, "cli_args": { "type": "array", "items": { "type": "string" }, "maxItems": 64, "description": "CLI arguments passed to the tool." }, "cli_display_name": { "type": "string", "maxLength": 256, "description": "Human-readable name shown in the session list." }, "parent_session_id": { "type": "string", "format": "uuid", "description": "Optional parent terminal session for nested shells." } } } } } }, "responses": { "201": { "description": "Session created. The producer_ticket is single-use and short-lived.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "required": [ "session", "producer_ticket", "ticket_expires_in_seconds" ], "properties": { "session": { "type": "object", "description": "Created session record.", "additionalProperties": true }, "producer_ticket": { "type": "string", "description": "Single-use ticket to present as the WebSocket protocol on `GET /v1/terminal/ws`." }, "ticket_expires_in_seconds": { "type": "integer", "description": "TTL of the producer ticket." } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "containersListTerminalSessions", "summary": "List terminal sessions", "description": "Returns a filtered list of the user's terminal sessions for the authenticated org.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status_filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "terminated" ] }, "description": "Filter by session status." }, { "name": "host_machine_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Filter by host machine ID." }, { "name": "cli_tool", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Filter by CLI tool identifier." }, { "name": "include_terminated", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, include terminated sessions." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Maximum number of sessions to return. Defaults to 50." } ], "responses": { "200": { "description": "Session list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/terminal/sessions/{id}/resume": { "post": { "operationId": "containersResumeTerminalSession", "summary": "Resume a terminal session", "description": "Returns the resume argv and a fresh producer ticket to reconnect the producer WebSocket for a previously disconnected session.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Terminal session ID." } ], "responses": { "200": { "description": "Resume info with a fresh producer ticket.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "resume_argv": { "type": "array", "items": { "type": "string" } }, "producer_ticket": { "type": "string" }, "ticket_expires_in_seconds": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/terminal/sessions/{id}/mark-resumed": { "post": { "operationId": "containersMarkTerminalSessionResumed", "summary": "Mark a terminal session as active after resumption", "description": "Flips a previously-terminated session back to `active` status after the host extension has successfully reconnected. Optionally updates the extension instance ID.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Terminal session ID." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "host_extension_id": { "type": "string", "maxLength": 128, "description": "Updated extension instance identifier, if changed." } } } } } }, "responses": { "200": { "description": "Session flipped to active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/terminal/sessions/{id}/join": { "post": { "operationId": "containersJoinTerminalSession", "summary": "Join a terminal session as a consumer", "description": "Returns a single-use consumer ticket that authorises a read-only (or read-write if `can_input` is true) WebSocket connection to the terminal session DO.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Terminal session ID." } ], "responses": { "200": { "description": "Consumer ticket issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "required": [ "session_id", "can_input", "consumer_ticket", "ticket_expires_in_seconds" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "can_input": { "type": "boolean", "description": "Whether the consumer is permitted to send input." }, "consumer_ticket": { "type": "string", "description": "Single-use ticket for the WebSocket upgrade." }, "ticket_expires_in_seconds": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/terminal/sessions/{id}/terminate": { "post": { "operationId": "containersTerminateTerminalSession", "summary": "Terminate a terminal session", "description": "Marks a terminal session as terminated and closes the associated WebSocket connections.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Terminal session ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "additionalProperties": false, "properties": { "reason": { "type": "string", "enum": [ "user", "timeout", "host_exit", "error", "inactivity", "admin" ], "description": "Reason for termination." } } } } } }, "responses": { "200": { "description": "Session terminated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/terminal/ws": { "get": { "operationId": "containersTerminalWebSocket", "summary": "Terminal session WebSocket upgrade", "description": "Upgrades to a WebSocket connection routed to the `TerminalSessionDO` for the given session. The one-time ticket previously issued by `POST /v1/terminal/sessions` (producer) or `POST /v1/terminal/sessions/{id}/join` (consumer) must be passed as the `Sec-WebSocket-Protocol` header value. The ticket is single-use and short-lived; it is consumed on the first valid upgrade and cannot be reused.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "ticket", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Single-use session ticket." }, { "name": "Upgrade", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "websocket" ] }, "description": "Must be `websocket`." } ], "responses": { "101": { "description": "WebSocket upgrade successful. The connection is now routed to the TerminalSessionDO." }, "401": { "description": "Missing, expired, or already-used ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "426": { "description": "Upgrade required. The `Upgrade: websocket` header was not present." } } } }, "/v1/tools": { "get": { "operationId": "containersListTools", "summary": "List tools", "description": "Returns a paginated list of tools available to the authenticated org. Optionally filtered by `status`.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "draft" ] }, "description": "Filter by tool status." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page number (1-based). Defaults to 1." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per page. Defaults to 50." } ], "responses": { "200": { "description": "Tool list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Containers_Tool" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "containersCreateTool", "summary": "Create a tool", "description": "Creates a new callable tool for the authenticated org. The `endpoint_url` is validated to prevent SSRF — private IP ranges and localhost are rejected.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_ToolCreateRequest" } } } }, "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Containers_Tool" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/tools/{id}": { "get": { "operationId": "containersGetTool", "summary": "Get a tool", "description": "Returns the full definition of a specific tool by ID.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Tool ID." } ], "responses": { "200": { "description": "Tool record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Containers_Tool" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "containersUpdateTool", "summary": "Update a tool", "description": "Updates an existing tool definition. At least one field must be supplied. The `endpoint_url` is validated to prevent SSRF.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Tool ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_ToolUpdateRequest" } } } }, "responses": { "200": { "description": "Tool updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Containers_Tool" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "containersDeleteTool", "summary": "Delete a tool", "description": "Permanently deletes a tool. Any Virtual Workers that reference this tool will have it removed from their callable set.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Tool ID." } ], "responses": { "200": { "description": "Tool deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers": { "get": { "operationId": "containersListVirtualWorkers", "summary": "List Virtual Workers", "description": "Returns all Virtual Workers accessible to the authenticated user within the current org.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Worker list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Containers_VirtualWorker" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "containersCreateVirtualWorker", "summary": "Create a Virtual Worker", "description": "Creates a new Virtual Worker for the authenticated org. The worker is created in `paused` status and must be explicitly resumed before it will process tasks.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Containers_VirtualWorkerCreateRequest" } } } }, "responses": { "201": { "description": "Virtual Worker created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "$ref": "#/components/schemas/Containers_VirtualWorker" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/claude-link/start": { "post": { "operationId": "containersVirtualWorkerClaudeLinkStart", "summary": "Start Claude Max OAuth link (PKCE)", "description": "Initiates PKCE OAuth flow to link a Claude Max account to this Virtual Worker. Returns an authorization URL to redirect the user to, plus a `link_token` to present on completion.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "responses": { "200": { "description": "PKCE flow initiated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "required": [ "authorize_url", "link_token", "state" ], "properties": { "authorize_url": { "type": "string", "description": "Claude authorization URL. Redirect the user here." }, "link_token": { "type": "string", "description": "Opaque token to present when calling `/complete`." }, "state": { "type": "string", "description": "PKCE state parameter." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/claude-link/complete": { "post": { "operationId": "containersVirtualWorkerClaudeLinkComplete", "summary": "Complete Claude Max OAuth link", "description": "Completes the server-side PKCE token exchange using the authorization code returned by the Claude OAuth callback. The resulting access token is encrypted at rest.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link_token", "code" ], "additionalProperties": false, "properties": { "link_token": { "type": "string", "description": "Opaque token returned by `/start`." }, "code": { "type": "string", "description": "Authorization code from the Claude OAuth callback." }, "account_label": { "type": "string", "maxLength": 128, "description": "Human-readable label for this connection." } } } } } }, "responses": { "201": { "description": "Claude Max account linked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/claude-link": { "get": { "operationId": "containersListVirtualWorkerClaudeLinks", "summary": "List Claude Max connections", "description": "Returns all Claude Max OAuth connections linked to this Virtual Worker.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "responses": { "200": { "description": "Connection list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/claude-link/{connectionId}": { "delete": { "operationId": "containersRevokeVirtualWorkerClaudeLink", "summary": "Revoke a Claude Max connection", "description": "Revokes and deletes a Claude Max OAuth connection from this Virtual Worker.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Connection ID to revoke." } ], "responses": { "200": { "description": "Connection revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/status": { "post": { "operationId": "containersSetVirtualWorkerStatus", "summary": "Set Virtual Worker status", "description": "Pause, resume, or retire a Virtual Worker. A `retired` worker cannot be re-activated.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "pause", "resume", "retire" ] } } } } } }, "responses": { "200": { "description": "Status updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/bindings": { "post": { "operationId": "containersCreateWorkerChannelBinding", "summary": "Create a worker channel binding", "description": "Binds a Virtual Worker to an inbound channel (helpdesk, chat, email, SaaS package, or project). Tasks arriving on the bound channel are routed to this worker's dispatch queue.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "virtual_worker_id", "channel_kind" ], "additionalProperties": false, "properties": { "virtual_worker_id": { "type": "string", "format": "uuid" }, "channel_kind": { "type": "string", "maxLength": 64, "description": "Channel type (e.g. `helpdesk`, `chat`, `email`, `project`)." }, "channel_ref": { "type": "string", "maxLength": 256, "description": "Channel-specific reference (e.g. queue name or topic)." }, "saas_package_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SaaS package the binding is scoped to." }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project the binding is scoped to." }, "credential_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Vault credential to inject when this channel fires." } } } } } }, "responses": { "201": { "description": "Channel binding created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/email": { "post": { "operationId": "containersAssignWorkerEmail", "summary": "Assign an email mailbox to a Virtual Worker", "description": "Binds a bbmail mailbox to this Virtual Worker so incoming messages create tasks in the worker's dispatch queue.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mailbox_id" ], "additionalProperties": false, "properties": { "mailbox_id": { "type": "string", "format": "uuid", "description": "Mailbox ID to bind." } } } } } }, "responses": { "200": { "description": "Mailbox assigned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/shift": { "post": { "operationId": "containersSetWorkerShift", "summary": "Set Virtual Worker shift schedule", "description": "Configures the worker's active-hours schedule. Tasks outside the shift window are deferred until the next shift start.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 128, "description": "Shift name (e.g. `Business Hours`)." }, "timezone": { "type": "string", "maxLength": 64, "description": "IANA timezone identifier (e.g. `America/New_York`)." }, "work_days": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "maxItems": 7, "description": "ISO week days the worker is active (0=Sunday…6=Saturday)." }, "start_local": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "description": "Local start time in `HH:MM` format." }, "end_local": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "description": "Local end time in `HH:MM` format." }, "jitter_seconds": { "type": "integer", "minimum": 0, "maximum": 3600, "description": "Random jitter applied to the start time to prevent thundering-herd task storms." } } } } } }, "responses": { "200": { "description": "Shift schedule saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/usage-policy": { "post": { "operationId": "containersSetWorkerUsagePolicy", "summary": "Set Virtual Worker usage policy", "description": "Configures weekly credit targets and hard thresholds for this worker. When the hard threshold is reached, the worker is automatically paused.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "weekly_target": { "type": [ "integer", "null" ], "minimum": 0, "description": "Soft weekly credit target. A warning is emitted when exceeded." }, "hard_threshold": { "type": [ "integer", "null" ], "minimum": 0, "description": "Hard weekly credit ceiling. Worker auto-pauses when reached." } } } } } }, "responses": { "200": { "description": "Usage policy saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/holidays": { "get": { "operationId": "containersListWorkerHolidays", "summary": "List Virtual Worker holidays", "description": "Returns all configured holiday dates for a Virtual Worker. The worker will not process tasks on holiday dates.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "responses": { "200": { "description": "Holiday list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "containersAddWorkerHoliday", "summary": "Add a holiday to a Virtual Worker", "description": "Adds a specific date on which the Virtual Worker will not process tasks.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "holiday_date" ], "additionalProperties": false, "properties": { "holiday_date": { "type": "string", "format": "date", "description": "Holiday date in `YYYY-MM-DD` format." }, "label": { "type": "string", "maxLength": 128, "description": "Human-readable label for this holiday." }, "is_full_day": { "type": "boolean", "description": "Whether the full day is blocked. Defaults to true." } } } } } }, "responses": { "201": { "description": "Holiday added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/holidays/{holidayId}": { "delete": { "operationId": "containersDeleteWorkerHoliday", "summary": "Delete a Virtual Worker holiday", "description": "Removes a previously-added holiday date from the worker.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." }, { "name": "holidayId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Holiday entry ID." } ], "responses": { "200": { "description": "Holiday removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/shares": { "get": { "operationId": "containersListWorkerShares", "summary": "List Virtual Worker shares", "description": "Returns all active capability shares for this Virtual Worker, including cross-org shares.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "responses": { "200": { "description": "Share list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "containersCreateWorkerShare", "summary": "Create a Virtual Worker share", "description": "Grants a specific capability of this Virtual Worker to a target user, org, or public. Use `scope: 'public'` to enable org-external invocation.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scope" ], "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "user", "org", "public" ], "description": "Share scope." }, "target_id": { "type": "string", "format": "uuid", "description": "Target user or org ID. Required when `scope` is `user` or `org`." }, "capability": { "type": "string", "maxLength": 128, "description": "The capability being shared. Omit to share all capabilities." } } } } } }, "responses": { "201": { "description": "Share created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/shares/{shareId}": { "delete": { "operationId": "containersRevokeWorkerShare", "summary": "Revoke a Virtual Worker share", "description": "Revokes a previously-granted capability share. Effective immediately — in-flight tasks already dispatched via the share may still complete.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Share ID." } ], "responses": { "200": { "description": "Share revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/autonomy": { "post": { "operationId": "containersSetWorkerAutonomy", "summary": "Set Virtual Worker autonomy configuration", "description": "Configures the worker's autonomy level: which action classes require human approval, which are permitted autonomously, and escalation policies. Approval-required actions are queued to the `/v1/virtual-workers/approvals` surface.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Autonomy configuration record. Structure is validated strictly.", "properties": { "auto_approve": { "type": "array", "items": { "type": "string" }, "description": "Action capability keys the worker may execute without approval." }, "require_approval": { "type": "array", "items": { "type": "string" }, "description": "Action capability keys that always require human approval." }, "escalation_timeout_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "How long to wait for approval before escalating or auto-declining." } } } } } }, "responses": { "200": { "description": "Autonomy config saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/approvals": { "get": { "operationId": "containersListWorkerApprovals", "summary": "List pending worker approvals", "description": "Returns worker autonomy approval requests pending human decision. Filtered to the authenticated org. Optional `status` query parameter.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "declined", "expired" ] }, "description": "Filter by approval status." } ], "responses": { "200": { "description": "Approval list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/approvals": { "post": { "operationId": "containersRequestWorkerApproval", "summary": "Request an autonomy approval", "description": "Creates a pending approval request for an action that this worker's autonomy policy requires human sign-off on before proceeding.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "worker_task_id", "capability" ], "additionalProperties": false, "properties": { "worker_task_id": { "type": "string", "format": "uuid", "description": "The task ID requesting approval." }, "capability": { "type": "string", "maxLength": 128, "description": "The capability the worker wants to exercise." }, "reason": { "type": "string", "maxLength": 2048, "description": "Worker-supplied justification for the requested action." } } } } } }, "responses": { "201": { "description": "Approval request created and queued for review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/approvals/{approvalId}/decide": { "post": { "operationId": "containersDecideWorkerApproval", "summary": "Decide on a worker approval request", "description": "Approves or declines a pending worker approval request. A declined request causes the worker to receive an autonomy denial on the in-progress task.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Approval request ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "decision" ], "additionalProperties": false, "properties": { "decision": { "type": "string", "enum": [ "approved", "declined" ], "description": "Approval outcome." }, "reason": { "type": "string", "maxLength": 2048, "description": "Optional human-provided reason, sent back to the worker." } } } } } }, "responses": { "200": { "description": "Decision recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Approval already decided. Error code: `CONFLICT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/sessions": { "get": { "operationId": "containersListWorkerSessions", "summary": "List Virtual Worker sessions", "description": "Returns container sessions associated with Virtual Workers. Optionally filtered by `virtual_worker_id`.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "virtual_worker_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter to sessions for a specific worker." } ], "responses": { "200": { "description": "Session list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Containers_Session" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/run-task": { "post": { "operationId": "containersVirtualWorkerRunTask", "summary": "Run a task on a Virtual Worker (direct)", "description": "Synchronously runs a real AI turn against this Virtual Worker using the worker's system prompt, tools, and Claude Max connection. Records the turn via the worker session. Returns the AI response and token usage.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "additionalProperties": false, "properties": { "prompt": { "type": "string", "minLength": 1, "description": "User message to send to the worker." }, "task_id": { "type": "string", "format": "uuid", "description": "Optional task ID to associate with this run for billing and audit." } } } } } }, "responses": { "200": { "description": "Task run completed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "required": [ "conversation_id", "ok" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "ok": { "type": "boolean" }, "response": { "type": "string", "description": "AI text response." }, "usage": { "type": "object", "description": "Token usage counters.", "additionalProperties": true } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/virtual-workers/{id}/dispatch": { "post": { "operationId": "containersVirtualWorkerDispatch", "summary": "Dispatch next queued task to a Virtual Worker", "description": "Claims the next pending task from the worker's dispatch queue, runs the AI turn, records it, and optionally posts the result as a note. Returns `claimed: false` when the queue is empty.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Virtual Worker ID." } ], "responses": { "200": { "description": "Dispatch result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "properties": { "data": { "type": "object", "required": [ "claimed" ], "properties": { "claimed": { "type": "boolean", "description": "Whether a task was dequeued and run. False when the queue is empty." }, "task_id": { "type": "string", "format": "uuid", "description": "ID of the claimed task. Present when `claimed` is true." }, "source": { "type": "string", "description": "Task source (e.g. `ticket`, `chat`)." }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID for the AI run." }, "ok": { "type": "boolean", "description": "Whether the AI turn succeeded." }, "note_posted": { "type": "boolean", "description": "Whether a result note was posted back to the task source." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/cli/connect": { "get": { "operationId": "containersCliConnect", "summary": "CLI WebSocket connect", "description": "Upgrades to a WebSocket connection routed to the `CLIController` Durable Object. The JWT session token must be passed as the `Sec-WebSocket-Protocol` header value. This is the persistent control-channel connection used by the `bb` CLI and IDE extensions.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Upgrade", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "websocket" ] }, "description": "Must be `websocket`." } ], "responses": { "101": { "description": "WebSocket upgrade successful. The connection is now routed to the CLIController DO." }, "401": { "description": "Missing or invalid session token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "426": { "description": "Upgrade required. The `Upgrade: websocket` header was absent." } } } }, "/cli/health": { "get": { "operationId": "containersCliHealth", "summary": "CLI service health", "description": "Returns a lightweight liveness probe for the CLI WebSocket service. No authentication required.", "tags": [ "Containers & Virtual Workers" ], "security": [], "responses": { "200": { "description": "Service healthy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "ts": { "type": "string", "format": "date-time" } } } } } } } } }, "/cli/info": { "get": { "operationId": "containersCliInfo", "summary": "CLI service info", "description": "Returns service version and capability metadata used by the CLI to negotiate protocol versions. No authentication required.", "tags": [ "Containers & Virtual Workers" ], "security": [], "responses": { "200": { "description": "Service info.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "min_cli_version": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/cli/connections": { "get": { "operationId": "containersCliConnections", "summary": "List active CLI connections (admin)", "description": "Returns metadata about active CLIController DO connections. Requires administrator-level authentication.", "tags": [ "Containers & Virtual Workers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Active connection list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "connected_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/cli/test": { "get": { "operationId": "containersCliTest", "summary": "CLI WebSocket test page", "description": "Returns an HTML page for manually testing CLI WebSocket connections. Intended for development and diagnostics only. No authentication required.", "tags": [ "Containers & Virtual Workers" ], "security": [], "responses": { "200": { "description": "HTML test page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/files/ws": { "get": { "operationId": "fileBridgeWebSocket", "summary": "Open FileBridge WebSocket relay", "description": "Upgrades to a WebSocket connection routed through the FileBridge Durable Object. Used by the Backbuild IDE to synchronise file trees between a local producer and a remote consumer. Authentication is via a short-lived one-time ticket passed in the `token` query parameter — **no `Authorization` header is accepted on this endpoint**. The ticket encodes the allowed role and pairing identity.", "tags": [ "Files & Documents" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "Short-lived one-time ticket issued by the control plane. Must be supplied instead of an `Authorization` header.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": true, "description": "The role this connection plays in the pairing.", "schema": { "type": "string", "enum": [ "producer", "consumer" ] } }, { "name": "pairingId", "in": "query", "required": true, "description": "UUID that identifies the pairing session shared by producer and consumer.", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "query", "required": true, "description": "UUID of the project whose files are being shared.", "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "query", "required": false, "description": "UUID of the document being opened. Required when `role=consumer`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "deviceId", "in": "query", "required": false, "description": "Opaque client device identifier. Maximum 256 characters.", "schema": { "type": "string", "maxLength": 256 } }, { "name": "rootFingerprint", "in": "query", "required": false, "description": "Hash of the workspace root used by the producer for integrity checks. Maximum 256 characters.", "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "101": { "description": "Switching Protocols — WebSocket connection established." }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/bbprove/projects/{projectId}/files/{path}": { "get": { "operationId": "bbproveReadFile", "summary": "Read a confined project file (BBProve)", "description": "Returns a chunk of a file from the project's confined source repository managed by BBProve. Authentication is via the one-time ticket query parameter — the caller must have been granted `producer` or `consumer` role for this project. Responses are chunked; `eof=true` signals the final chunk.", "tags": [ "Files & Documents" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "path", "in": "path", "required": true, "description": "Project-relative file path (wildcard segment, may contain `/`).", "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": true, "description": "One-time ticket granting read access to this project's confined repository.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File chunk returned successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FilesDocs_FileChunk" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "description": "Ticket absent, expired, or invalid (`AUTH_REQUIRED`, `AUTH_TOKEN_EXPIRED`, `AUTH_TOKEN_INVALID`).", "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "bbproveWriteFile", "summary": "CAS-write a confined project file (BBProve)", "description": "Writes a file into the project's confined source repository using content-addressable storage (CAS). The `ifMatchSha256` field acts as an optimistic-concurrency guard — the write is rejected with `CONFLICT` if the current head hash differs. Authentication is via the one-time ticket query parameter.", "tags": [ "Files & Documents" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "path", "in": "path", "required": true, "description": "Project-relative file path (wildcard segment, may contain `/`).", "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": true, "description": "One-time ticket granting write access to this project's confined repository.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_WriteFileRequest" } } } }, "responses": { "200": { "description": "File written successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FilesDocs_WriteFileResult" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "CAS mismatch — `ifMatchSha256` does not match the current head hash (`CONFLICT`).", "$ref": "#/components/responses/Conflict" }, "413": { "description": "Payload exceeds the 16 MB file size limit (`FILE_SIZE_LIMIT_EXCEEDED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/documents": { "get": { "operationId": "listDocuments", "summary": "List documents", "description": "Returns a paginated list of documents visible to the authenticated user. Results can be filtered by project, parent folder, and free-text search, and sorted by various fields.", "tags": [ "Files & Documents" ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Filter documents belonging to this project.", "schema": { "type": "string", "format": "uuid" } }, { "name": "parent_id", "in": "query", "required": false, "description": "Filter documents whose immediate parent folder has this ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "required": false, "description": "Full-text search query. Maximum 200 characters.", "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" }, { "name": "sort_by", "in": "query", "required": false, "description": "Field to sort results by.", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "title" ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of documents.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_Document" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createDocument", "summary": "Create a document", "description": "Creates a new document in the library. The content is passed through the content-safety gate before storage; documents that violate the content policy are rejected with `CONTENT_POLICY_VIOLATION`.", "tags": [ "Files & Documents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_CreateDocumentRequest" } } } }, "responses": { "201": { "description": "Document created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/FilesDocs_Document" } } } } } ] } } } }, "400": { "description": "Validation failed or content safety check failed (`VALIDATION_ERROR`, `CONTENT_POLICY_VIOLATION`).", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/documents/explorer": { "get": { "operationId": "getDocumentExplorer", "summary": "Get unified document explorer", "description": "Returns the full explorer tree for the authenticated user, organised into roots (`artifacts`, `personal`, `department`, `organization`, `projects`, `shared`, `sharing`), with nested folders and document items under each root.", "tags": [ "Files & Documents" ], "responses": { "200": { "description": "Explorer tree returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "roots": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_ExplorerRoot" } }, "folders": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_ExplorerFolder" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_Document" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/documents/folders": { "post": { "operationId": "createDocumentFolder", "summary": "Create a document folder", "description": "Creates a virtual folder marker in the document library. Folders are identified by their root and path segments rather than a flat name hierarchy.", "tags": [ "Files & Documents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_CreateFolderRequest" } } } }, "responses": { "201": { "description": "Folder created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "folder": { "$ref": "#/components/schemas/FilesDocs_ExplorerFolder" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/documents/folders/{id}": { "put": { "operationId": "renameDocumentFolder", "summary": "Rename a document folder", "description": "Renames the last segment of an existing document folder.", "tags": [ "Files & Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the folder to rename.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "New folder name (the final path segment)." } } } } } }, "responses": { "200": { "description": "Folder renamed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "folder": { "$ref": "#/components/schemas/FilesDocs_ExplorerFolder" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteDocumentFolder", "summary": "Delete a document folder", "description": "Deletes a document folder and all its contents. This operation is permanent.", "tags": [ "Files & Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the folder to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Folder deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/documents/{id}": { "get": { "operationId": "getDocument", "summary": "Get a document", "description": "Returns a single document by ID. Row Level Security ensures users can only retrieve documents they have access to.", "tags": [ "Files & Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the document.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/FilesDocs_Document" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "updateDocument", "summary": "Update a document", "description": "Updates one or more fields of an existing document. All fields are optional; only supplied fields are changed. Content updates pass through the content-safety gate.", "tags": [ "Files & Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the document to update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_UpdateDocumentRequest" } } } }, "responses": { "200": { "description": "Document updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/FilesDocs_Document" } } } } } ] } } } }, "400": { "description": "Validation failed or content policy violated (`VALIDATION_ERROR`, `CONTENT_POLICY_VIOLATION`).", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteDocument", "summary": "Delete a document", "description": "Permanently deletes a document and its associated storage objects. This operation cannot be undone.", "tags": [ "Files & Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the document to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/documents/publish": { "post": { "operationId": "publishDocument", "summary": "Publish a document to the library", "description": "Upserts a document into a named library bucket with a category and folder path. Accepts either Markdown or a Base64-encoded PDF. PDFs are validated for JavaScript actions (`PDF_CONTAINS_JS_ACTION`) and checked against upload suppression lists (`UPLOAD_SUPPRESSED`). Requires the `documents.publish` API key scope when authenticating with an API key. Returns `operation: 'created'` (HTTP 201) or `operation: 'updated'` (HTTP 200).", "tags": [ "Files & Documents" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_PublishDocumentRequest" } } } }, "responses": { "200": { "description": "Document updated (already existed at the resolved path).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FilesDocs_PublishDocumentResult" } } } ] } } } }, "201": { "description": "Document created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FilesDocs_PublishDocumentResult" } } } ] } } } }, "400": { "description": "Validation failed, PDF contains JavaScript actions, or upload is suppressed (`VALIDATION_ERROR`, `PDF_CONTAINS_JS_ACTION`, `UPLOAD_SUPPRESSED`).", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "description": "Payload exceeds the size limit (`PAYLOAD_TOO_LARGE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/documents/{id}/file-link": { "post": { "operationId": "createDocumentFileLink", "summary": "Mint a short-lived signed URL for a document file", "description": "Issues a 300-second HMAC-signed URL that can be used to retrieve the raw document file (typically a PDF) without an `Authorization` header. Requires the `documents.read` API key scope when authenticating with an API key.", "tags": [ "Files & Documents" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the document whose file URL is being minted.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signed URL minted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Signed download URL valid for `ttl_seconds`." }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the URL expires." }, "ttl_seconds": { "type": "integer", "description": "Validity window in seconds (300).", "example": 300 } }, "required": [ "url", "expires_at", "ttl_seconds" ] } } } ] } } } }, "400": { "description": "Document ID is not a valid UUID (`INVALID_ID_FORMAT`).", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/documents/{id}/file": { "get": { "operationId": "downloadDocumentFile", "summary": "Download a document file (PDF)", "description": "Streams the raw document file (typically a PDF). Accepts either an `Authorization: Bearer` header for JWT/session authentication **or** the HMAC-signed query parameters `org`, `exp`, and `sig` minted by `/v1/documents/{id}/file-link`. When signed URL parameters are present, the Bearer header is ignored. Expired or tampered signatures return `UNAUTHORIZED`.", "tags": [ "Files & Documents" ], "security": [ {}, { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "org", "in": "query", "required": false, "description": "Organisation UUID embedded in the signed URL (required when using signed-URL auth).", "schema": { "type": "string", "format": "uuid" } }, { "name": "exp", "in": "query", "required": false, "description": "Unix timestamp at which the signed URL expires (required when using signed-URL auth).", "schema": { "type": "integer" } }, { "name": "sig", "in": "query", "required": false, "description": "HMAC-SHA256 signature over `{org}:{id}:{exp}` (required when using signed-URL auth).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF binary stream.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Document ID is not a valid UUID (`INVALID_ID_FORMAT`).", "$ref": "#/components/responses/ValidationError" }, "401": { "description": "No valid authentication provided, or signed URL is expired or invalid (`AUTH_REQUIRED`, `UNAUTHORIZED`).", "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Authenticated user does not have access to this document, or API key lacks the required scope (`FORBIDDEN`, `API_KEY_SCOPE_DENIED`).", "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/documents:resolve": { "post": { "operationId": "resolveProjectDocument", "summary": "Resolve a document by project-relative path", "description": "Resolves a project-relative path to a document record. Returns a uniform `403 Forbidden` for both unauthorised access and non-existent paths to prevent existence oracle attacks.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "rel_path" ], "properties": { "rel_path": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Project-relative path of the document to resolve." } } } } } }, "responses": { "200": { "description": "Document resolved.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid" }, "doc_type": { "type": "string" }, "capability": { "type": "string" }, "classification": { "type": "string" } }, "required": [ "document_id", "doc_type", "capability", "classification" ] } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Access denied or path does not exist — uniform 403 to prevent existence oracle (`FORBIDDEN`).", "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/recents": { "get": { "operationId": "getBBDocRecents", "summary": "Get recently accessed BB Docs in a project", "description": "Returns the most recently accessed BB Docs for the authenticated user in the specified project.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of recents to return. Between 1 and 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Recent BB Docs returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_BBDoc" } } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs": { "get": { "operationId": "listBBDocs", "summary": "List BB Docs in a project", "description": "Returns a paginated list of BB Docs belonging to the project. Supports pagination, full-text search, and filtering by content type.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "description": "Items per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "search", "in": "query", "required": false, "description": "Full-text search query. Maximum 500 characters.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "content_type", "in": "query", "required": false, "description": "Filter by BB Doc content type.", "schema": { "type": "string", "enum": [ "pf2", "amsthm", "latex" ] } } ], "responses": { "200": { "description": "Paginated list of BB Docs.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_BBDoc" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createBBDoc", "summary": "Create a BB Doc", "description": "Creates a new BB Doc in the specified project. Optionally initialises the document from a template, with pre-populated content in a supported format, or copies the content from an existing source document.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_CreateBBDocRequest" } } } }, "responses": { "201": { "description": "BB Doc created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/FilesDocs_BBDoc" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}": { "get": { "operationId": "getBBDoc", "summary": "Get a BB Doc", "description": "Returns the metadata and current state of a single BB Doc.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "BB Doc returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/FilesDocs_BBDoc" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "renameBBDoc", "summary": "Rename a BB Doc", "description": "Updates the title of a BB Doc. The title is trimmed and must be between 1 and 255 characters after trimming.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc to rename.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New title for the BB Doc (whitespace-trimmed before storage)." } } } } } }, "responses": { "200": { "description": "BB Doc renamed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/FilesDocs_BBDoc" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/versions": { "get": { "operationId": "listBBDocVersions", "summary": "List versions of a BB Doc", "description": "Returns the append-only version chain for a BB Doc, newest first. Each version represents a snapshot checkpoint.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Version list returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_BBDocVersion" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/versions/{versionId}": { "get": { "operationId": "getBBDocVersion", "summary": "Get a specific BB Doc version", "description": "Returns a single version snapshot for a BB Doc by version ID.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "versionId", "in": "path", "required": true, "description": "UUID of the version snapshot.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Version snapshot returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "version": { "$ref": "#/components/schemas/FilesDocs_BBDocVersion" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/versions/{versionId}/restore": { "post": { "operationId": "restoreBBDocVersion", "summary": "Restore a BB Doc to a previous version", "description": "Creates a new HEAD version that copies the content of the specified version snapshot. The restore operation is non-destructive — the existing version chain is preserved.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "versionId", "in": "path", "required": true, "description": "UUID of the version to restore from.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "New HEAD version created from the specified snapshot.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "version": { "$ref": "#/components/schemas/FilesDocs_BBDocVersion" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/thumbnail": { "get": { "operationId": "getBBDocThumbnail", "summary": "Get BB Doc thumbnail metadata", "description": "Returns the thumbnail for a BB Doc. If the document's first page has a page-icon, returns `{icon}` (a string icon name). If a rendered bitmap is available, returns a 302 redirect to a short-lived signed blob URL (`/v1/projects/{projectId}/bbdocs/{documentId}/thumbnail/blob?...`).", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Page-icon thumbnail returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "icon": { "type": "string", "description": "Icon name representing the document thumbnail." } }, "required": [ "icon" ] } } } ] } } } }, "302": { "description": "Redirect to signed blob URL for bitmap thumbnail.", "headers": { "Location": { "description": "Signed URL for the thumbnail blob.", "schema": { "type": "string", "format": "uri" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/thumbnail/blob": { "get": { "operationId": "downloadBBDocThumbnailBlob", "summary": "Download BB Doc thumbnail bitmap", "description": "Streams the WebP thumbnail bitmap for a BB Doc. Authentication is via HMAC-signed query parameters (`org`, `sha`, `exp`, `sig`) minted by the control plane — **no `Authorization` header is accepted**. The signed URL is obtained from the `Location` header of a `302` response on `GET /v1/projects/{projectId}/bbdocs/{documentId}/thumbnail`.", "tags": [ "Files & Documents" ], "security": [ {} ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "org", "in": "query", "required": true, "description": "Organisation UUID embedded in the signed URL.", "schema": { "type": "string", "format": "uuid" } }, { "name": "sha", "in": "query", "required": true, "description": "Content hash of the blob, embedded in the signed URL.", "schema": { "type": "string" } }, { "name": "exp", "in": "query", "required": true, "description": "Unix timestamp at which the signed URL expires.", "schema": { "type": "integer" } }, { "name": "sig", "in": "query", "required": true, "description": "HMAC-SHA256 signature.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "WebP thumbnail bitmap.", "content": { "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Signed URL is absent, expired, or tampered (`UNAUTHORIZED`).", "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/comments": { "get": { "operationId": "listBBDocComments", "summary": "List comments on a BB Doc", "description": "Returns all comments (and their replies) on the specified BB Doc.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_BBDocComment" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createBBDocComment", "summary": "Create a comment on a BB Doc", "description": "Adds a new comment anchored to a character range in the BB Doc. The anchor positions refer to Yjs document offsets. An optional `commentId` can be supplied by the client for idempotency.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc to comment on.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_CreateCommentRequest" } } } }, "responses": { "201": { "description": "Comment created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/FilesDocs_BBDocComment" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}": { "patch": { "operationId": "updateBBDocComment", "summary": "Update a BB Doc comment", "description": "Toggles the resolved state of a comment. Currently the only mutable field.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "UUID of the comment to update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "resolved" ], "properties": { "resolved": { "type": "boolean", "description": "Whether the comment thread is resolved." } } } } } }, "responses": { "200": { "description": "Comment updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/FilesDocs_BBDocComment" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteBBDocComment", "summary": "Delete a BB Doc comment", "description": "Permanently deletes a comment thread and all its replies.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "UUID of the comment to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}/replies": { "post": { "operationId": "createBBDocCommentReply", "summary": "Add a reply to a BB Doc comment", "description": "Appends a reply to an existing comment thread. An optional `replyId` can be supplied by the client for idempotency.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "UUID of the parent comment thread.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_CreateReplyRequest" } } } }, "responses": { "201": { "description": "Reply created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "reply": { "$ref": "#/components/schemas/FilesDocs_BBDocCommentReply" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}/replies/{replyId}": { "delete": { "operationId": "deleteBBDocCommentReply", "summary": "Delete a reply from a BB Doc comment", "description": "Permanently deletes a single reply from a comment thread.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "UUID of the parent comment thread.", "schema": { "type": "string", "format": "uuid" } }, { "name": "replyId", "in": "path", "required": true, "description": "UUID of the reply to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reply deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}/assign": { "post": { "operationId": "assignBBDocComment", "summary": "Assign a BB Doc comment to a user", "description": "Assigns responsibility for resolving a comment to a specific user. Triggers an in-app notification to the assignee.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "UUID of the comment to assign.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "assigneeUserId" ], "properties": { "assigneeUserId": { "type": "string", "format": "uuid", "description": "UUID of the user to assign the comment to." }, "assigneeName": { "type": "string", "maxLength": 200, "description": "Display name of the assignee (used in notifications)." } } } } } }, "responses": { "200": { "description": "Comment assigned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/FilesDocs_BBDocComment" }, "notified": { "type": "boolean", "description": "Whether the assignee was successfully notified." } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/comments/{commentId}/assignment-done": { "post": { "operationId": "completeBBDocCommentAssignment", "summary": "Mark a BB Doc comment assignment as done", "description": "Marks the comment assignment as completed. Typically called by the assignee when the requested change has been made.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "UUID of the comment whose assignment is being completed.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Assignment marked as done.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/FilesDocs_BBDocComment" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/shares": { "get": { "operationId": "listBBDocShares", "summary": "List shares on a BB Doc", "description": "Returns the active share grants on a BB Doc. Revoked shares are excluded by default.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_revoked", "in": "query", "required": false, "description": "Pass `true` to include revoked share grants in the response.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Share list returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "shares": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_BBDocShare" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createBBDocShare", "summary": "Create a share grant on a BB Doc", "description": "Grants access to a BB Doc for an org, user, or named scope. The caller's existing sharing level acts as a ceiling — attempting to grant a level that exceeds the caller's own access returns `403 Forbidden`.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc to share.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_CreateShareRequest" } } } }, "responses": { "201": { "description": "Share grant created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "share": { "$ref": "#/components/schemas/FilesDocs_BBDocShare" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Access denied, or requested share level exceeds the caller's own share ceiling (`FORBIDDEN`).", "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbdocs/{documentId}/shares/{shareId}": { "delete": { "operationId": "revokeBBDocShare", "summary": "Revoke a BB Doc share grant", "description": "Revokes a share grant. If the grant was already revoked, returns the existing record with `already_revoked: true` rather than an error.", "tags": [ "Files & Documents" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "UUID of the BB Doc.", "schema": { "type": "string", "format": "uuid" } }, { "name": "shareId", "in": "path", "required": true, "description": "UUID of the share grant to revoke.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Share grant revoked (or was already revoked).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": "string", "format": "date-time" }, "already_revoked": { "type": "boolean" } }, "required": [ "id", "revoked_at", "already_revoked" ] } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/versioning/{resourceType}/{resourceId}": { "get": { "operationId": "listResourceVersions", "summary": "List versions of a versioned resource", "description": "Returns the version history of a supported resource type. Supported types are `skill`, `entity_type`, `screen_definition`, `workflow`, `pricing_plan`, and `tool`. Returns `INVALID_PARAMETER` for unsupported types.", "tags": [ "Files & Documents" ], "parameters": [ { "name": "resourceType", "in": "path", "required": true, "description": "The type of the versioned resource.", "schema": { "type": "string", "enum": [ "skill", "entity_type", "screen_definition", "workflow", "pricing_plan", "tool" ] } }, { "name": "resourceId", "in": "path", "required": true, "description": "UUID of the resource.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Version list returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_ResourceVersion" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } ] } } } }, "400": { "description": "Resource type is not supported (`INVALID_PARAMETER`).", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/versioning/{resourceType}/{resourceId}/{version}": { "get": { "operationId": "getResourceVersion", "summary": "Get a specific version of a resource", "description": "Returns a single version snapshot of a resource by its sequential version number.", "tags": [ "Files & Documents" ], "parameters": [ { "name": "resourceType", "in": "path", "required": true, "description": "The type of the versioned resource.", "schema": { "type": "string", "enum": [ "skill", "entity_type", "screen_definition", "workflow", "pricing_plan", "tool" ] } }, { "name": "resourceId", "in": "path", "required": true, "description": "UUID of the resource.", "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "path", "required": true, "description": "Sequential positive-integer version number.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Version snapshot returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "version": { "$ref": "#/components/schemas/FilesDocs_ResourceVersion" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/versioning/{resourceType}/{resourceId}/revert": { "post": { "operationId": "revertResourceVersion", "summary": "Revert a resource to a previous version", "description": "Creates a new HEAD version of the resource that copies the content of the specified version. Returns `CONFLICT` if the requested version is already the current HEAD.", "tags": [ "Files & Documents" ], "parameters": [ { "name": "resourceType", "in": "path", "required": true, "description": "The type of the versioned resource.", "schema": { "type": "string", "enum": [ "skill", "entity_type", "screen_definition", "workflow", "pricing_plan", "tool" ] } }, { "name": "resourceId", "in": "path", "required": true, "description": "UUID of the resource to revert.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "integer", "minimum": 1, "description": "Sequential version number to revert to." }, "changelog": { "type": "string", "maxLength": 500, "description": "Optional human-readable note explaining why this revert was made." } } } } } }, "responses": { "200": { "description": "Resource reverted — new HEAD version created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "version": { "$ref": "#/components/schemas/FilesDocs_ResourceVersion" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The requested version is already the current HEAD (`CONFLICT`).", "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/science/documents/promote-artifact": { "post": { "operationId": "promoteArtifact", "summary": "Promote a Science artifact to the document library", "description": "Copies a Science artifact from the RAG source bucket into the user's document library as a new document record (copy-on-write). The artifact must belong to an accessible catalog and be confined to the caller's organisation. If the artifact file exceeds 16 MB the promotion is rejected with `PAYLOAD_TOO_LARGE`.", "tags": [ "Files & Documents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesDocs_PromoteArtifactRequest" } } } }, "responses": { "201": { "description": "Artifact promoted and document created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/FilesDocs_Document" }, "copy": { "type": "object", "description": "Details of the R2 copy operation.", "properties": { "source_key": { "type": "string" }, "dest_key": { "type": "string" }, "size_bytes": { "type": "integer" } } } } } } } ] } } } }, "400": { "description": "Validation failed or confinement violation — artifact does not belong to the caller's organisation (`VALIDATION_ERROR`).", "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Artifact or its catalog was not found (`NOT_FOUND`).", "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "description": "Artifact file exceeds the 16 MB promotion limit (`PAYLOAD_TOO_LARGE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "Required R2 storage binding is unavailable (`SERVICE_UNAVAILABLE`).", "$ref": "#/components/responses/ServerError" } } } }, "/v1/org/settings/{key}": { "get": { "operationId": "orgAdminGetSetting", "summary": "Get an org setting", "description": "Returns the current value for a single org-level configuration key. Readable by any active member of the organization. The key is a short slug (≤200 chars) identifying the setting; unknown keys return `404 NOT_FOUND`.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Setting key slug (e.g. `conversation_public_sharing_allowed`). Maximum 200 characters.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "The current setting value.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_OrgSetting" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the key exceeds 200 characters or is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — no setting with that key exists for this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "orgAdminSetSetting", "summary": "Upsert an org setting", "description": "Creates or replaces a single org-level configuration key. Requires admin or owner role (enforced by the stored procedure). The value is stored verbatim as text; the stored procedure normalises boolean-shaped strings. Only allowlisted keys can be written — unknown keys are rejected with `NOT_FOUND`.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Setting key slug (e.g. `conversation_public_sharing_allowed`). Maximum 200 characters.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgAdmin_OrgSettingSetRequest" }, "example": { "value": "true" } } } }, "responses": { "200": { "description": "The setting was saved. Returns the updated setting record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_OrgSetting" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the key is invalid, the value exceeds 4096 characters, or the body is not valid JSON (`INVALID_JSON`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller is not an admin or owner of the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the key is not in the allowlisted set of configurable settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/org/domains": { "get": { "operationId": "orgAdminListDomains", "summary": "List org custom domains", "description": "Returns all custom domains registered for the caller's organization, with optional status filter and offset pagination. Requires the `custom_domain.view` permission (held by owner/admin by default).", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by domain status.", "schema": { "type": "string", "enum": [ "pending_verification", "active", "suspended", "deleted" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of domains to return (1–200, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of custom domains.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgAdmin_CustomDomain" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` — a query parameter has an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `custom_domain.view` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "orgAdminCreateDomain", "summary": "Register an org custom domain", "description": "Registers a new custom domain for the organization. The domain enters `pending_verification` state; call `POST /v1/org/domains/{domainId}/verify` to run DNS TXT verification. Requires `custom_domain.create` permission. The `api_base_url` must be an HTTPS URL (max 2048 chars); defaults to the environment's Backbuild API endpoint when omitted.", "tags": [ "Organizations & Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgAdmin_CreateDomainRequest" }, "example": { "domain": "app.acme.com", "domain_type": "primary", "environment": "production" } } } }, "responses": { "201": { "description": "Domain registered. Returns the full domain record including the `dns_verification_token` to publish as a TXT record at `_backbuild-verify.`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_CustomDomain" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the domain name is invalid, a field fails validation, or the body is not valid JSON (`INVALID_JSON`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `custom_domain.create` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`DOMAIN_ALREADY_EXISTS` — a domain with that hostname is already registered (globally unique).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/org/domains/{domainId}": { "get": { "operationId": "orgAdminGetDomain", "summary": "Get an org custom domain", "description": "Returns a single custom domain record by id. A domain not visible to the caller (wrong org or not found) is reported as `404 NOT_FOUND`. Requires `custom_domain.view` permission.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "description": "Custom domain identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The custom domain record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_CustomDomain" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `domainId` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `custom_domain.view` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — domain does not exist or belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "orgAdminDeleteDomain", "summary": "Delete an org custom domain", "description": "Soft-deletes a custom domain. The domain is set to `deleted` status and removed from active routing. Requires `custom_domain.delete` permission.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "description": "Custom domain identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The domain was deleted. Returns the deleted domain record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_CustomDomain" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `domainId` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `custom_domain.delete` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — domain does not exist or belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/organizations/{orgId}/policies": { "get": { "operationId": "orgAdminGetPolicies", "summary": "Get org control policies", "description": "Returns the current control policies for the specified organization: session idle timeout, container concurrency cap, container daily-hours cap, AI daily spend cap, and any extra policy fields. Readable by any active member of the organization. The `orgId` path parameter must match the caller's active organization (super-admins may access any org).", "tags": [ "Organizations & Users" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" } ], "responses": { "200": { "description": "The organization's current control policies.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_OrgPolicies" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `orgId` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`TENANT_ACCESS_DENIED` — the caller's active organization does not match `orgId`. `FORBIDDEN` — the stored procedure rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`ORG_NOT_FOUND` — the organization does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "orgAdminUpdatePolicies", "summary": "Update org control policies", "description": "Partially updates control policies for the specified organization. At least one field must be present. Passing `null` for a numeric field clears the organization-specific override and reverts to the platform default. Requires the `org.manage_settings` permission. The update stored procedure also mirrors the effective idle timeout into the session layer. The `orgId` must match the caller's active organization (super-admins may update any org).", "tags": [ "Organizations & Users" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgAdmin_UpdatePoliciesRequest" }, "example": { "session_inactivity_timeout_minutes": 60, "max_concurrent_containers": 10 } } } }, "responses": { "200": { "description": "Policies updated. Returns the full updated policies record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_OrgPolicies" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `orgId` is not a valid UUID. `VALIDATION_ERROR` — a field failed validation, an unrecognised field was supplied, or no fields were provided (`INVALID_JSON` if the body is not parseable JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`TENANT_ACCESS_DENIED` — `orgId` does not match the caller's active organization. `FORBIDDEN` — caller lacks `org.manage_settings` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`ORG_NOT_FOUND` — the organization does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/slugs/availability": { "get": { "operationId": "orgAdminCheckSlugAvailability", "summary": "Check slug availability", "description": "Advisory check for whether a proposed slug is available for a given resource kind (`org`, `project`, or `package`). Returns `{ available, reason }` — the response NEVER identifies the current owner (anti-enumeration). This endpoint is rate-limited per authenticated user (60 requests/minute per user) and should be called from a debounced editor field. The result is advisory; DB uniqueness enforcement remains authoritative on the write path.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "kind", "in": "query", "required": true, "description": "The resource kind to check.", "schema": { "type": "string", "enum": [ "org", "project", "package" ] } }, { "name": "slug", "in": "query", "required": true, "description": "Candidate slug to check (1–256 characters). Any non-empty bounded string is accepted so the stored procedure can return a precise reason (`invalid_format`, `reserved`, `uuid_shaped`, `taken`) for editor feedback.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "responses": { "200": { "description": "Advisory availability result. The `Cache-Control: private, max-age=0, must-revalidate` header is always set; do not share or cache this response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_SlugAvailability" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` — `kind` or `slug` is missing or invalid. `VALIDATION_ERROR` — the stored procedure rejected the input (e.g. malformed slug).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller lacks the create/update permission required for the requested `kind`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/visibility/check": { "post": { "operationId": "orgAdminVisibilityCheck", "summary": "Check resource visibility", "description": "Evaluates whether the target principal (user or group) can see a given resource, based on the caller's organization's visibility rules. Returns a structured verdict from the stored procedure. Requires an authenticated session; the caller's organization and user id scope the rule evaluation.", "tags": [ "Organizations & Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgAdmin_VisibilityCheckRequest" }, "example": { "resource_type": "project", "resource_id": "019d0000-0000-7000-8000-000000000000" } } } }, "responses": { "200": { "description": "Visibility verdict from the stored procedure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_VisibilityVerdict" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a required field is missing or has an invalid format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/visibility/rules": { "get": { "operationId": "orgAdminListVisibilityRules", "summary": "List visibility rules", "description": "Returns visibility rules for the caller's organization, with optional filtering by resource type, resource id, rule type, or scope. Results are offset-paginated.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "resource_type", "in": "query", "required": false, "description": "Filter by resource type (e.g. `project`, `document`).", "schema": { "type": "string", "maxLength": 100 } }, { "name": "resource_id", "in": "query", "required": false, "description": "Filter by resource identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "rule_type", "in": "query", "required": false, "description": "Filter by rule type.", "schema": { "type": "string", "enum": [ "allow", "deny" ] } }, { "name": "scope", "in": "query", "required": false, "description": "Filter by visibility scope.", "schema": { "type": "string", "enum": [ "global", "org", "user", "role", "group", "department", "project", "org_hierarchy" ] } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Paginated list of visibility rules.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgAdmin_VisibilityRule" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a query parameter has an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "orgAdminCreateVisibilityRule", "summary": "Create a visibility rule", "description": "Creates a new visibility rule for a resource within the caller's organization. For scopes other than `global`, a `scope_id` (the target user, role, group, or project id) is required. The stored procedure enforces authorization; the caller must have sufficient permissions to manage visibility for the target resource.", "tags": [ "Organizations & Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgAdmin_CreateVisibilityRuleRequest" }, "example": { "resource_type": "project", "resource_id": "019d0000-0000-7000-8000-000000000000", "scope": "org", "rule_type": "allow" } } } }, "responses": { "201": { "description": "The visibility rule was created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_VisibilityRule" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a field failed validation (e.g. `scope_id` missing for non-`global` scope, invalid scope value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/visibility/rules/{id}": { "delete": { "operationId": "orgAdminDeleteVisibilityRule", "summary": "Delete a visibility rule", "description": "Deletes a visibility rule by id. The caller must have permission to manage visibility for the resource covered by the rule.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visibility rule identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The rule was deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `id` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — rule does not exist or is not visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bootstrap": { "get": { "operationId": "orgAdminGetBootstrap", "summary": "Bootstrap session context", "description": "Returns, in a single response, the first-paint data slices needed to render the authenticated user's application shell: profile, organizations, projects, settings, and any other areas gated for the caller's entitlements. The payload is assembled by a single stored procedure in one database round-trip. Each slice is gated independently — a missing feature or permission never fails the overall response.\n\nThe response carries `ETag` (weak hash) and `Cache-Control: private, max-age=15, stale-while-revalidate=60` headers. Clients should send `If-None-Match` with the stored ETag on subsequent calls; an unchanged payload returns `304 Not Modified` with no body.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "description": "Previously received weak ETag (e.g. `W/\"a3f9b2c1\"`). If the payload has not changed the server returns `304 Not Modified` with no body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bootstrap context. Includes ETag and Cache-Control headers for conditional GET support.", "headers": { "ETag": { "description": "Weak ETag over the serialised response body.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Always `private, max-age=15, stale-while-revalidate=60`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_BootstrapContext" } } } ] } } } }, "304": { "description": "Not Modified — the payload has not changed since the provided `If-None-Match` ETag. No body is returned." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ccpa/do-not-sell": { "post": { "operationId": "orgAdminCcpaDoNotSell", "summary": "CCPA opt-out: do not sell or share", "description": "Records that the authenticated consumer has exercised their CCPA/CPRA §1798.120 right to opt out of the sale or sharing of their personal information. The operation is idempotent — re-invocation by an already-opted-out consumer succeeds without advancing the original opt-out timestamp (the original instant anchors the §1798.135(c) 12-month wait-before-re-soliciting clock).\n\nThis endpoint is intentionally frictionless per CCPA §1798.135(a)(3): no MFA step-up is required. A valid authenticated session is required so the opt-out is bound to a verified consumer identity per §1798.130(a)(2) record-keeping obligations.\n\nThe request body may be omitted or sent as an empty JSON object `{}`. Any unknown keys are rejected with `400 VALIDATION_ERROR`.", "tags": [ "Organizations & Users" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Empty request body (strict object — no fields accepted)." }, "example": {} } } }, "responses": { "201": { "description": "Opt-out recorded (or confirmed as already active). Returns confirmation details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_CcpaOptOutResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the request body contains unexpected fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the authenticated principal is not the consumer subject (callers may only opt themselves out).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the authenticated user account does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/ccpa/data-categories-collected": { "get": { "operationId": "orgAdminCcpaDataCategories", "summary": "CCPA: data categories collected", "description": "Returns the categories of personal information Backbuild has collected about the authenticated consumer in the preceding 12 months, including the categories of sources, the business or commercial purposes for collection, and the categories of third parties with whom the information has been shared. Satisfies CCPA §1798.110 (right to know categories collected) and §1798.115 (right to know categories sold or shared) in the read-only, machine-readable form contemplated by §1798.130(a)(5).\n\nThe `since` parameter is informational — the enumerated categories are not window-dependent — but is recorded in the response for audit purposes.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Optional explicit start of the 12-month look-back window (RFC 3339 / ISO 8601). Defaults to 12 months before the request time when omitted.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "CCPA data categories disclosure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_CcpaDataCategoriesResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the `since` parameter is not a valid ISO 8601 datetime.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/legal-agreements/templates": { "get": { "operationId": "orgAdminListLegalTemplates", "summary": "List active legal agreement templates", "description": "Returns the set of active legal agreement templates available for signing by the caller's organization (e.g. DPA, BAA, CCPA Addendum). Gated by the `iam` system feature flag.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of active templates.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/OrgAdmin_LegalAgreementTemplate" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — insufficient permissions to view agreement templates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/legal-agreements/templates/{slug}": { "get": { "operationId": "orgAdminGetLegalTemplate", "summary": "Get a legal agreement template", "description": "Returns a single legal agreement template by slug, including its full markdown content. The slug is a short lowercase alphanumeric-with-hyphens identifier (e.g. `dpa`, `baa`). Gated by the `iam` system feature flag.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Template slug (lowercase alphanumeric with hyphens, max 50 chars).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 50 } } ], "responses": { "200": { "description": "The template record with full markdown content.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_LegalAgreementTemplate" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the slug is empty, too long, or contains invalid characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — insufficient permissions to view agreement templates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — no active template with that slug exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/legal-agreements/sign": { "post": { "operationId": "orgAdminSignLegalAgreement", "summary": "Sign a legal agreement", "description": "Signs a legal agreement template on behalf of the caller's organization. The signing flow:\n1. Fetches the template and verifies its content hash for integrity.\n2. Computes an HMAC-SHA256 signature over a canonical signing payload.\n3. Records the acceptance in the database.\n4. Generates a signed PDF and stores it durably.\n5. Sends the signed PDF to the signer's email and any verified CC recipients.\n\nPDF generation and durable storage are required for legal validity — if either step fails the acceptance record is rolled back and `500 INTERNAL_ERROR` is returned.\n\nCC recipients must be active members of the signing organization; non-member addresses are rejected with `403 FORBIDDEN`. Maximum 5 CC recipients. Gated by the `iam` system feature flag.", "tags": [ "Organizations & Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgAdmin_AgreementSignRequest" }, "example": { "template_id": "019d0000-0000-7000-8000-000000000001", "signer_name": "Jane Smith", "signer_title": "Chief Legal Officer", "signer_email": "jane@acme.com", "signer_company": "Acme Corp" } } } }, "responses": { "201": { "description": "Agreement signed and PDF stored. Returns the acceptance record plus `pdf_generated: true`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_AgreementAcceptance" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a required field is missing, a field fails format validation, or the document integrity check failed. `UPLOAD_SUPPRESSED` — the generated PDF matched the platform deny list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — insufficient permissions to sign agreements, or a CC recipient is not an active org member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the specified template does not exist or is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`INTERNAL_ERROR` — PDF generation or durable storage failed; the acceptance record was rolled back. `DATABASE_ERROR` — the signing stored procedure failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`DATABASE_ERROR` — the upload suppression service was unavailable during the signing flow. The acceptance record was NOT committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/legal-agreements/acceptances": { "get": { "operationId": "orgAdminListLegalAcceptances", "summary": "List signed legal agreements", "description": "Returns all signed legal agreement acceptance records for the caller's organization, with optional filtering by template slug or status, and offset pagination. Gated by the `iam` system feature flag.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "template_slug", "in": "query", "required": false, "description": "Filter by template slug (e.g. `dpa`).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by acceptance status.", "schema": { "type": "string", "enum": [ "active", "superseded", "revoked" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of acceptance records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "acceptances": { "type": "array", "items": { "$ref": "#/components/schemas/OrgAdmin_AgreementAcceptance" } }, "total_count": { "type": "integer", "description": "Total matching records before pagination." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a query parameter has an invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — insufficient permissions to view agreements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/legal-agreements/acceptances/{id}": { "get": { "operationId": "orgAdminGetLegalAcceptance", "summary": "Get a signed legal agreement", "description": "Returns a single legal agreement acceptance record by id. The acceptance must belong to the caller's organization. Gated by the `iam` system feature flag.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Acceptance record identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The acceptance record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_AgreementAcceptance" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — the `id` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — insufficient permissions to view agreements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the acceptance does not exist or belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/legal-agreements/acceptances/{id}/pdf": { "get": { "operationId": "orgAdminDownloadLegalAcceptancePdf", "summary": "Download signed agreement PDF", "description": "Downloads the signed PDF for a legal agreement acceptance. The PDF is served directly from durable object storage with `Content-Type: application/pdf` and `Content-Disposition: attachment`. The response carries `Cache-Control: private, no-store` to prevent caching of sensitive contract documents in shared or transparent caches. Gated by the `iam` system feature flag.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Acceptance record identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The signed PDF binary.", "headers": { "Content-Type": { "schema": { "type": "string", "enum": [ "application/pdf" ] } }, "Content-Disposition": { "description": "Always `attachment; filename=\"-signed-.pdf\"`.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "`INVALID_ID_FORMAT` — the `id` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — insufficient permissions to download agreements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the acceptance does not exist, belongs to another organization, or the signed PDF has not yet been stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/org/domains/{domainId}/verify": { "post": { "operationId": "orgAdminVerifyDomain", "summary": "Verify an org custom domain", "description": "Triggers a real-time DNS-over-HTTPS TXT lookup for `_backbuild-verify.` and hands the observed token to the platform. If the TXT record matches the stored `dns_verification_token`, the domain transitions to `active`. DNS propagation delays are the caller's responsibility — if the record has not propagated yet, re-invoke after propagation. Requires `custom_domain.update` permission.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "description": "Custom domain identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Verification attempted. Check `status` in the returned domain record — `active` means the TXT record was found; `pending_verification` means the record was not observed yet.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgAdmin_CustomDomain" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `domainId` is not a valid UUID. `VALIDATION_ERROR` — domain is already verified or is in an invalid state for verification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `custom_domain.update` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — domain does not exist or belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/organizations": { "get": { "operationId": "orgCoreListOrganizations", "summary": "List organizations for the authenticated user", "description": "Returns all organizations the authenticated user is a member of, along with their active-organization context and roles. The list is RLS-scoped to the caller's account — the caller cannot enumerate organizations they do not belong to.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of the caller's organizations with membership context.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organizations" ], "properties": { "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/OrgCore_OrgSummary" }, "description": "Organizations the caller belongs to." } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "orgCoreCreateOrganization", "summary": "Create an organization", "description": "Creates a new organization. The authenticated user becomes the owner. Requires the `org.update` permission on the current session. A URL-safe `slug` is auto-generated from the name when omitted; if a slug is supplied it must conform to the canonical grammar (lowercase alphanumeric groups separated by single hyphens, 3–63 chars, not UUID-shaped, not a reserved word). Returns the platform-assigned organization `id`.", "tags": [ "Organizations & Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgCore_CreateOrganizationRequest" }, "example": { "name": "Acme Corp", "plan_tier": "starter" } } } }, "responses": { "201": { "description": "Organization created. The platform-assigned `id` is returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The new organization's identifier (UUIDv7)." } } } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `VALIDATION_ERROR` (a field failed validation, including a slug that fails the canonical grammar or is a reserved word).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`PERMISSION_DENIED` — the caller lacks the `org.update` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — an organization with the requested slug already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/organizations/resolve": { "get": { "operationId": "orgCoreResolveOrganizationSlug", "summary": "Resolve an organization slug or UUID to its canonical record", "description": "Resolves a slug (or a UUID passed as `?slug=`) to the canonical organization UUID and metadata. The resolved organization must match the caller's JWT-pinned organization; cross-organization slug lookups return `404` to prevent enumeration. UUID-form input receives `Sunset`, `Deprecation`, and `Link: rel=\"alternate\"` headers pointing to the canonical slug URL. The response is `private, max-age=0` — never cached in intermediaries.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "slug", "in": "query", "required": true, "description": "Organization slug (canonical human-readable form) or raw UUID. Maximum 256 characters.", "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Resolved organization identifier and canonical slug.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgCore_SlugResolveResult" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` — `slug` is missing or exceeds 256 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — the slug does not exist, or it resolves to an organization other than the caller's JWT-pinned organization (anti-enumeration: both cases are indistinguishable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/organizations/by/{idOrSlug}": { "get": { "operationId": "orgCoreGetOrganizationBySlugOrId", "summary": "Get an organization by slug or UUID", "description": "Accepts either a canonical slug or a raw UUID as a path segment, resolves it to the organization, enforces that the resolved organization matches the caller's JWT-pinned organization (super-admins exempt), and returns the full organization record. Cross-organization access and missing resources both return `404` (anti-enumeration).", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "Organization UUID or canonical slug. Maximum 256 characters.", "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "The full organization record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgCore_Organization" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` — `idOrSlug` is empty or exceeds 256 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — the identifier does not exist, or it resolves to an organization other than the caller's JWT-pinned organization (anti-enumeration).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/organizations/{orgId}": { "get": { "operationId": "orgCoreGetOrganization", "summary": "Get an organization by UUID", "description": "Returns the full organization record for the given UUID. The caller must belong to the target organization; cross-tenant access returns `403 TENANT_ACCESS_DENIED`. A non-existent organization returns `404 ORG_NOT_FOUND`.", "tags": [ "Organizations & Users" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" } ], "responses": { "200": { "description": "The organization record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgCore_Organization" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `orgId` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`TENANT_ACCESS_DENIED` — the caller is not a member of this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`ORG_NOT_FOUND` — the organization does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "orgCoreUpdateOrganization", "summary": "Update an organization", "description": "Updates organization fields. Requires the `org.update` permission. At least one field must be present. Top-level shorthand fields (`description`, `website`, `billing_email`, `org_type`) are merged into the `settings.profile` sub-object. Passing `slug: null` clears the optional slug; passing a slug string sets it (must satisfy the canonical grammar). A reserved or syntactically-invalid slug is rejected as `400 VALIDATION_ERROR`. A slug collision returns `409 CONFLICT`.", "tags": [ "Organizations & Users" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgCore_UpdateOrganizationRequest" } } } }, "responses": { "200": { "description": "Organization updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `INVALID_ID_FORMAT` (bad UUID), `VALIDATION_ERROR` (field validation failed, reserved slug, or invalid slug grammar).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`TENANT_ACCESS_DENIED` (cross-org access) or `PERMISSION_DENIED` (missing `org.update` permission).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`ORG_NOT_FOUND` — the organization does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the requested slug is already taken by another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/organizations/{orgId}/members": { "get": { "operationId": "orgCoreListMembers", "summary": "List organization members", "description": "Returns the members of an organization with optional filtering by role or status, and offset pagination. The caller must belong to the target organization.", "tags": [ "Organizations & Users" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" }, { "name": "role", "in": "query", "required": false, "description": "Filter members by role (e.g. `owner`, `admin`, `member`). Omit to return all roles.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter members by status (e.g. `active`, `invited`, `suspended`). Omit to return all statuses.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of members to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of members to skip for pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of organization members.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgCore_OrgMember" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (bad UUID) or `INVALID_PARAMETER` (query params out of range).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`TENANT_ACCESS_DENIED` — the caller is not a member of this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`ORG_NOT_FOUND` — the organization does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "orgCoreUpsertMember", "summary": "Add or update an organization member", "description": "Adds a user to the organization or updates an existing member's role and/or status. Requires the `org.manage_members` permission. Role escalation is subject to a role-hierarchy gate in the stored procedure — a caller cannot grant a role higher than their own. Self-modification and demotion of the sole owner are rejected as `409 CONFLICT`. The `email` field is optional; when the target user is visible to the caller via RLS, the platform resolves it automatically.", "tags": [ "Organizations & Users" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgCore_UpsertMemberRequest" }, "example": { "user_id": "019b0000-0000-7000-8000-000000000000", "role": "member" } } } }, "responses": { "201": { "description": "Member added or updated. Returns the membership record identifier.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The membership record identifier." } } } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `INVALID_ID_FORMAT` (bad UUID), `VALIDATION_ERROR` (field validation failed or payload rejected by the stored procedure).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`TENANT_ACCESS_DENIED` (cross-org), `PERMISSION_DENIED` / `FORBIDDEN` (missing `org.manage_members` or role-hierarchy escalation denied), or `MEMBER_LIMIT_REACHED` (the organization's plan member limit is reached).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`USER_NOT_FOUND` — the target user does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — self-role-change attempt or demotion of the sole organization owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/organizations/{orgId}/members/{userId}": { "delete": { "operationId": "orgCoreRemoveMember", "summary": "Remove an organization member", "description": "Removes a user from the organization. Requires the `org.manage_members` permission. A caller cannot remove themselves — the route rejects this with `400 VALIDATION_ERROR` before reaching the stored procedure. Removing the sole owner is rejected by the stored procedure as `409 CONFLICT`. Cross-organization access returns `403 TENANT_ACCESS_DENIED`.", "tags": [ "Organizations & Users" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" }, { "name": "userId", "in": "path", "required": true, "description": "The user to remove (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Member removed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "removed" ], "properties": { "removed": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (bad UUID for `orgId` or `userId`) or `VALIDATION_ERROR` (caller attempting to remove themselves).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`TENANT_ACCESS_DENIED` (cross-org) or `PERMISSION_DENIED` / `FORBIDDEN` (missing `org.manage_members` or SP authz denial).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`USER_NOT_FOUND` — the user is not a member of this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — cannot remove the sole owner of the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/organizations/{orgId}/settings/auth": { "get": { "operationId": "orgCoreGetAuthSettings", "summary": "Get organization auth policy", "description": "Returns the effective authentication settings for the organization (platform defaults merged with any per-organization overrides). Any authenticated member of the organization may call this endpoint; it does not require elevated permissions. Used by the login flow and UI to render policy-dependent controls.", "tags": [ "Organizations & Users" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" } ], "responses": { "200": { "description": "Effective auth settings for the organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgCore_AuthSettings" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `orgId` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`TENANT_ACCESS_DENIED` — the caller is not a member of this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`ORG_NOT_FOUND` — the organization does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "orgCoreUpdateAuthSettings", "summary": "Update organization auth policy", "description": "Updates the organization's authentication policy. Requires the `org.update_auth_settings` permission (narrower than the general `org.update` — auth-policy changes have their own audit grant). At least one field must be provided. Disabling all authentication methods is rejected as `400 VALIDATION_ERROR`. Cross-tenant writes are rejected both at the route layer and inside the stored procedure.", "tags": [ "Organizations & Users" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgCore_UpdateAuthSettingsRequest" } } } }, "responses": { "200": { "description": "Auth settings updated. Returns the org id and the resulting effective settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "org_id", "effective_settings" ], "properties": { "org_id": { "type": "string", "format": "uuid", "description": "The updated organization's identifier." }, "effective_settings": { "$ref": "#/components/schemas/OrgCore_AuthSettings" } } } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `INVALID_ID_FORMAT` (bad UUID), `VALIDATION_ERROR` (field validation failed, all auth methods disabled, or no fields provided).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`TENANT_ACCESS_DENIED` (cross-org) or `PERMISSION_DENIED` / `FORBIDDEN` (missing `org.update_auth_settings` permission).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`ORG_NOT_FOUND` — the organization does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/users/{userId}/data-export": { "get": { "operationId": "orgCoreUserDataExport", "summary": "Export user data (GDPR Data Subject Access Request)", "description": "Returns a machine-readable JSON bundle of all personal data the platform holds for the given user, fulfilling the data subject access right (GDPR Art. 15) and data portability right (GDPR Art. 20). The caller must be either the data subject themselves or a super-admin. Requires a fresh MFA step-up (within the last 5 minutes) and a valid Cloudflare Turnstile proof-of-human token. Rate limited to one export per target user per hour. The response is served with `Content-Disposition: attachment` and `Cache-Control: no-store`. If the audit log was truncated at the 50 000-row platform cap, the response carries `X-Export-Truncated: true` and a top-level `truncated: true` field.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "The user whose data to export (UUID). Must match the authenticated user's own id, or the caller must be a super-admin.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cf-turnstile-response", "in": "header", "required": true, "description": "Cloudflare Turnstile proof-of-human token. Also accepted as `x-turnstile-token`. Required to prevent automated bulk PII scraping.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Full personal data export. The `data` field contains all PII and records associated with the user. The optional `truncated: true` top-level flag and `X-Export-Truncated: true` response header indicate the audit log was capped at the platform limit.", "headers": { "Content-Disposition": { "description": "Attachment filename in the form `backbuild-data-export-{userId}-{YYYY-MM-DD}.json`.", "schema": { "type": "string" } }, "X-Export-Truncated": { "description": "Present with value `true` when the audit-event log exceeded the 50 000-row platform cap and the export is incomplete.", "schema": { "type": "string", "enum": [ "true" ] } }, "Cache-Control": { "description": "Always `no-store, no-cache, must-revalidate, private`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Complete personal data payload returned by the stored procedure. Schema is subject to change; consumers should treat this as an opaque portable record." }, "truncated": { "type": "boolean", "description": "Present and `true` when the audit log was capped at the 50 000-row platform limit. Indicates the export is incomplete." } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — `userId` is not a valid UUID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_REQUIRED` / `MFA_STEPUP_REQUIRED` — authentication or fresh MFA step-up is missing. Also returned when the Turnstile proof-of-human check fails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — the caller is not the data subject and is not a super-admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`USER_NOT_FOUND` — the target user does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — the one-export-per-hour limit for this target user has been reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/org": { "get": { "operationId": "orgCoreGetOrgSettings", "summary": "Get all organization settings", "description": "Returns the full organization settings object for the authenticated user's active organization. The response is the raw settings blob stored for the organization.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "The organization's settings object.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Organization settings key-value map." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "orgCoreUpdateOrgSettings", "summary": "Update organization settings (batch)", "description": "Replaces or merges the organization settings object. Requires the `org.manage_settings` permission (enforced both in this route and inside the stored procedure as defense-in-depth). Emits a real-time `org_settings` change notification to connected collaborators. Returns the resulting settings object.", "tags": [ "Organizations & Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgCore_OrgSettingsUpdateRequest" } } } }, "responses": { "200": { "description": "Settings updated. Returns the resulting settings object.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Resulting organization settings." } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the `settings` field is missing, not an object, or exceeds the bounded JSONB size/depth limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller lacks the `org.manage_settings` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the organization does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/org/{key}": { "get": { "operationId": "orgCoreGetOrgSettingByKey", "summary": "Get a specific organization setting by key", "description": "Returns a single organization setting value looked up by its string key. Returns `404 NOT_FOUND` when the key does not exist in the organization's settings.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "The setting key (1–200 characters).", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "The setting value.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "description": "The setting value (type depends on the key)." } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the key is empty or exceeds 200 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — the key does not exist in the organization's settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/preferences": { "get": { "operationId": "orgCoreGetUserPreferences", "summary": "Get user preferences", "description": "Returns the raw user preferences object for the authenticated user within their active organization context. See also `GET /v1/settings/personalization` for a normalized view.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "Raw user preferences object.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "User preference key-value map." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "orgCoreUpdateUserPreferences", "summary": "Update user preferences (batch)", "description": "Replaces or merges the user's preference object within the active organization context. Accepts a bounded JSONB preferences object. Returns the resulting preferences.", "tags": [ "Organizations & Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgCore_UserPreferencesUpdateRequest" } } } }, "responses": { "200": { "description": "Preferences updated. Returns the resulting preferences object.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Resulting user preferences." } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the `preferences` field is missing, not an object, or exceeds the bounded JSONB size/depth limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/preferences/{key}": { "get": { "operationId": "orgCoreGetUserPreferenceByKey", "summary": "Get a specific user preference by key", "description": "Returns a single preference value for the authenticated user, looked up by its string key.", "tags": [ "Organizations & Users" ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "The preference key (1–200 characters).", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "The preference value.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "description": "The preference value (type depends on the key)." } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — the key is empty or exceeds 200 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — the preference key does not exist for this user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/personalization": { "get": { "operationId": "orgCoreGetPersonalization", "summary": "Get personalization settings", "description": "Returns the authenticated user's personalization preferences in a normalized shape (`themeMode`, `language`, `stayLoggedInHours`, `notifications`). This is a read-only normalized view over the raw preferences; the raw preferences are available at `GET /v1/settings/preferences`.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "Normalized personalization settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgCore_PersonalizationSettings" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "orgCoreUpdatePersonalization", "summary": "Update personalization settings", "description": "Accepts a flat personalization object and persists it as user preferences. All fields are required. The `stayLoggedInHours` value must be one of the discrete allowed choices (`1`, `8`, `24`, `168`, `720`); arbitrary integers are rejected. Returns the resulting normalized personalization.", "tags": [ "Organizations & Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgCore_PersonalizationSettings" } } } }, "responses": { "200": { "description": "Personalization updated. Returns the resulting normalized settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrgCore_PersonalizationSettings" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a required field is missing, `themeMode`/`language` are invalid, `stayLoggedInHours` is not one of the allowed discrete values, or a notification boolean is not a boolean.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/api-keys": { "get": { "operationId": "orgCoreListApiKeysSettings", "summary": "List API keys (settings panel)", "description": "Returns the organization API keys visible to the authenticated user, for display in the Settings → API Keys panel. This is a convenience wrapper over the API-keys data for use by the settings UI.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of API keys.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "API key records." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/integrations": { "get": { "operationId": "orgCoreListIntegrationsSettings", "summary": "List integrations (settings panel)", "description": "Returns integrations configured for the authenticated user and active organization, for display in the Settings → Integrations panel.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of integrations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Integration records." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/views": { "get": { "operationId": "orgCoreListViewsSettings", "summary": "List views (settings panel)", "description": "Returns saved views for the authenticated user and active organization, for display in the Settings → Views panel. Returns up to 100 records.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of views.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "View records." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/ai-skills": { "get": { "operationId": "orgCoreListAiSkills", "summary": "List AI skills (settings panel)", "description": "Returns the AI skills configured for the active organization, for display in the Settings → AI Skills panel. The `/v1/settings/skills` path is an alias for this endpoint.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of AI skills.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "AI skill records." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/skills": { "get": { "operationId": "orgCoreListSkillsAlias", "summary": "List AI skills — alias", "description": "Alias for `GET /v1/settings/ai-skills`. Provided because the web app SkillsPanel calls this path. Returns the same data.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of AI skills.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "AI skill records." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/alert-rules": { "get": { "operationId": "orgCoreListAlertRules", "summary": "List alert rules (settings panel)", "description": "Returns alert rules configured for the active organization, for display in the Settings → Alert Rules panel.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of alert rules.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Alert rule records." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/automation": { "get": { "operationId": "orgCoreListAutomationRules", "summary": "List automation rules (settings panel)", "description": "Returns automation rules configured for the active organization, for display in the Settings → Automation panel.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of automation rules.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Automation rule records." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/profile": { "get": { "operationId": "orgCoreGetSettingsProfile", "summary": "Get user profile (settings panel)", "description": "Returns the authenticated user's profile data for display in the Settings → Profile panel. Retrieves the full user profile from the stored procedure when available; falls back to the session's auth context (userId, email, orgId) if the stored procedure is not yet available.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "User profile data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "User profile fields." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/notifications": { "get": { "operationId": "orgCoreGetSettingsNotifications", "summary": "Get notifications (settings panel)", "description": "Returns the user's notifications for display in the Settings → Notifications panel. Returns up to 50 records.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "List of notifications.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Notification records." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/security": { "get": { "operationId": "orgCoreGetSettingsSecurity", "summary": "Get security settings (settings panel)", "description": "Returns the security settings for the active organization, for display in the Settings → Security panel.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "Organization security settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Security settings object." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/billing": { "get": { "operationId": "orgCoreGetSettingsBilling", "summary": "Get billing overview (settings panel)", "description": "Returns the billing overview for the active organization, for display in the Settings → Billing panel.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "Billing overview data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Billing overview fields." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings/sync-config": { "get": { "operationId": "orgCoreGetSyncConfig", "summary": "Get sync configuration", "description": "Returns the synchronization configuration for the authenticated user's active organization. Used by clients to initialize their offline/sync layer.", "tags": [ "Organizations & Users" ], "responses": { "200": { "description": "Organization sync configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Sync config fields." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/environments": { "get": { "operationId": "entitiesListEnvironments", "summary": "List environments", "description": "Returns the logical deployment environments (dev, staging, preprod, prod) that the authenticated user can access within their organization. The `multi-environment` feature flag must be enabled; the endpoint is gated server-side.", "tags": [ "Projects, Entities & Data Model" ], "responses": { "200": { "description": "Array of environment objects the caller can access.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_Environment" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks organization membership or the `multi-environment` feature is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateEnvironment", "summary": "Create an environment", "description": "Creates a new non-production logical environment (`dev`, `staging`, or `preprod`) for the caller's organization. Requires organization admin role and the `multi-environment` feature flag. The `prod` key is reserved and cannot be created via this route.", "tags": [ "Projects, Entities & Data Model" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateEnvironmentRequest" }, "example": { "env_key": "staging", "display_name": "Staging" } } } }, "responses": { "201": { "description": "Environment created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_Environment" } } } ] } } } }, "400": { "description": "`INVALID_JSON` (malformed body) or `VALIDATION_ERROR` (unknown `env_key`, extra fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `INSUFFICIENT_PERMISSIONS` — caller is not an org admin or the feature is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — an environment with that key already exists in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/environments/{id}/grants": { "get": { "operationId": "entitiesListEnvironmentGrants", "summary": "List environment grants", "description": "Returns the access grants for a specific environment. Requires organization admin role; the stored procedure enforces the authorization check.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Environment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_revoked", "in": "query", "required": false, "description": "When `true`, include revoked grants in the response. Defaults to `false`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of grants for the environment.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_EnvironmentGrant" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — the `id` path parameter is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `INSUFFICIENT_PERMISSIONS` — caller is not an org admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — environment does not exist or is not visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateEnvironmentGrant", "summary": "Create an environment grant", "description": "Grants a user, group, department, or role access to an environment. Requires organization admin role.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Environment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateEnvironmentGrantRequest" } } } }, "responses": { "201": { "description": "Grant created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_EnvironmentGrant" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (bad path param), `INVALID_JSON` (malformed body), or `VALIDATION_ERROR` (invalid scope/capability).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `INSUFFICIENT_PERMISSIONS` — caller is not an org admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a grant for this principal already exists on this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/environments/{id}/grants/{grantId}": { "delete": { "operationId": "entitiesDeleteEnvironmentGrant", "summary": "Revoke an environment grant", "description": "Revokes an environment access grant. Idempotent — revoking an already-revoked grant is a no-op. The environment `id` is validated for format; authorization and ownership are resolved from the grant id within the caller's organization.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Environment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "grantId", "in": "path", "required": true, "description": "Grant identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Grant revoked (or was already revoked).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Revoked grant summary." } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — one or both path parameters is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller is not an org admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — grant does not exist within the caller's organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/templates": { "get": { "operationId": "entitiesListTemplates", "summary": "List project templates", "description": "Returns project templates visible to the authenticated caller within their organization. Supports filtering by publication status and free-text search.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "is_published", "in": "query", "required": false, "description": "Filter by publication state. Omit to return all visible templates.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1, max 100000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (default 100, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search over template names/descriptions (max 500 chars).", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "List of templates.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_Template" } } } } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` — an invalid query parameter value was supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `TENANT_ACCESS_DENIED` — caller lacks template view access or the `orgId` path param does not match the session org.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateTemplate", "summary": "Create a project template", "description": "Creates a new project template in the caller's organization. The `description` field is screened by the platform content-safety gate; prohibited content returns `CONTENT_POLICY_VIOLATION`.", "tags": [ "Projects, Entities & Data Model" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateTemplateRequest" } } } }, "responses": { "201": { "description": "Template created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/Entities_Template" } } } } } ] } } } }, "400": { "description": "`INVALID_JSON` (malformed body), `VALIDATION_ERROR` (field constraint), or `CONTENT_POLICY_VIOLATION` (description content rejected).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `TENANT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/org/{orgId}/templates": { "get": { "operationId": "entitiesListOrgTemplates", "summary": "List project templates (org-scoped)", "description": "Org-scoped alias for `GET /v1/templates`. The `orgId` path parameter must match the authenticated session's organization; a mismatch returns `TENANT_ACCESS_DENIED`. Identical query parameters and response shape.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" }, { "name": "is_published", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "List of templates.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_Template" } } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (bad orgId) or `INVALID_PARAMETER` (bad query).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN`, `TENANT_ACCESS_DENIED` (orgId mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateOrgTemplate", "summary": "Create a project template (org-scoped)", "description": "Org-scoped alias for `POST /v1/templates`. The `orgId` path parameter must match the authenticated session's organization.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateTemplateRequest" } } } }, "responses": { "201": { "description": "Template created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/Entities_Template" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`, or `CONTENT_POLICY_VIOLATION`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `TENANT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/templates/{id}": { "get": { "operationId": "entitiesGetTemplate", "summary": "Get a project template", "description": "Returns a single project template by identifier. Templates not visible to the caller are reported as `NOT_FOUND`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The template record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/Entities_Template" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — the `id` path parameter is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `TENANT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "entitiesUpdateTemplate", "summary": "Update a project template", "description": "Updates a project template's name, description, config, or changelog. At least one field must be provided. The `description` field is screened by the content-safety gate.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_UpdateTemplateRequest" } } } }, "responses": { "200": { "description": "The updated template record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/Entities_Template" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR` (no fields provided or field constraint), or `CONTENT_POLICY_VIOLATION`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `TENANT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "entitiesDeleteTemplate", "summary": "Delete a project template", "description": "Deletes a project template from the caller's organization. Requires the caller to own or have admin rights over the template (enforced by the stored procedure).", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — the `id` path parameter is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `TENANT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/org/{orgId}/templates/{id}": { "get": { "operationId": "entitiesGetOrgTemplate", "summary": "Get a project template (org-scoped)", "description": "Org-scoped alias for `GET /v1/templates/{id}`. The `orgId` must match the session organization.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" }, { "name": "id", "in": "path", "required": true, "description": "Template identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The template record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/Entities_Template" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `TENANT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "entitiesUpdateOrgTemplate", "summary": "Update a project template (org-scoped)", "description": "Org-scoped alias for `PUT /v1/templates/{id}`. The `orgId` must match the session organization.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" }, { "name": "id", "in": "path", "required": true, "description": "Template identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_UpdateTemplateRequest" } } } }, "responses": { "200": { "description": "The updated template.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/Entities_Template" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR`, or `CONTENT_POLICY_VIOLATION`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "entitiesDeleteOrgTemplate", "summary": "Delete a project template (org-scoped)", "description": "Org-scoped alias for `DELETE /v1/templates/{id}`. The `orgId` must match the session organization.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" }, { "name": "id", "in": "path", "required": true, "description": "Template identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/templates/{templateId}/versions": { "get": { "operationId": "entitiesListTemplateVersions", "summary": "List template versions", "description": "Returns the version history of a project template with page-based pagination. The caller must have visibility on the template.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "Template identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1, max 100000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (default 25, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated version history.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_TemplateVersion" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER` (unknown query param — strict schema).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` or `TENANT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entities/{type}/{id}/pin": { "post": { "operationId": "entitiesPinEntity", "summary": "Pin an entity", "description": "Pins (bookmarks) an entity to the authenticated user's sidebar. The caller must have view access on the entity (`project.view` permission). Per-user cap of 20 pins per entity type; exceeding the cap returns `CONFLICT`. 403 and 404 responses collapse to a uniform `NOT_FOUND` (anti-enumeration).", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Entity type key (e.g. `project`). Unknown types return `400 INVALID_PARAMETER`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "position": { "type": "integer", "description": "Optional display position in the pinned list." } } } } } }, "responses": { "201": { "description": "Entity pinned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Entities_EntityPin" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` (unknown type), `INVALID_ID_FORMAT` (bad entity UUID), `INVALID_JSON` (malformed body), or `VALIDATION_ERROR` (invalid `position`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — entity does not exist, is not visible to the caller, or the caller lacks view access (anti-enumeration: 403 collapses to 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — per-user pin cap (20) for this entity type has been reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "entitiesUnpinEntity", "summary": "Unpin an entity", "description": "Removes an entity pin for the authenticated user. As with pin creation, 403 and 404 responses collapse to `NOT_FOUND` (anti-enumeration). The DELETE body must be empty.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Entity type key.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entity unpinned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` (unknown type), `INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (non-empty body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — pin or entity not found, or caller lacks view access (anti-enumeration).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/entities": { "get": { "operationId": "entitiesListEntities", "summary": "List entities in a project", "description": "Returns entities within a project with offset pagination. Requires `project.view` permission. Supports filtering by entity type, parent, and status.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "entity_type_id", "in": "query", "required": false, "description": "Filter to a specific entity type (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "parent_id", "in": "query", "required": false, "description": "Filter to direct children of a parent entity.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by entity status string.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Paginated entity list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_Entity" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT` (bad projectId) or `INVALID_PARAMETER` (bad query).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateEntity", "summary": "Create an entity", "description": "Creates a new entity of the specified type within a project. Requires `project.update` permission. Returns the platform-assigned entity identifier.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateEntityRequest" } } } }, "responses": { "201": { "description": "Entity created. Returns the entity identifier.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (constraint or SP validation refusal).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — the referenced `entity_type_id` or `parent_id` does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a unique constraint was violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/entities/search": { "get": { "operationId": "entitiesSearchEntities", "summary": "Search entities in a project", "description": "Full-text search over entities within a project. Requires `project.view` permission. The `query` parameter is required.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "query", "in": "query", "required": true, "description": "Search terms (1–256 chars).", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "entity_type_id", "in": "query", "required": false, "description": "Restrict search to a specific entity type.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_Entity" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/entities/tree": { "get": { "operationId": "entitiesGetEntityTree", "summary": "Get entity tree", "description": "Returns the entity hierarchy for a project as a nested tree structure. Requires `project.view` permission. Optionally starts from a specific root entity and limits depth.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "root_entity_id", "in": "query", "required": false, "description": "Start the tree from this entity (UUIDv7). Defaults to the project root.", "schema": { "type": "string", "format": "uuid" } }, { "name": "max_depth", "in": "query", "required": false, "description": "Maximum tree depth to traverse (1–20, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "Nested entity tree.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller is not a member of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — project does not exist or is not visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entities/{entityId}": { "get": { "operationId": "entitiesGetEntity", "summary": "Get an entity", "description": "Returns a single entity by identifier. Requires `project.view` permission. An entity the caller cannot see is reported as `NOT_FOUND`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The entity record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_Entity" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks read access on the entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "entitiesUpdateEntity", "summary": "Update an entity", "description": "Updates one or more fields of an entity. Requires `project.view` (the SP enforces the five-right EDIT gate, including grants). The `metadata` bag uses a top-level key merge: supplied keys set/overwrite; a `null` value removes a key; omitted keys are preserved. Supply `expected_updated_at` for optimistic-concurrency control.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_UpdateEntityRequest" } } } }, "responses": { "200": { "description": "Entity updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "updated": { "type": "boolean" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (no fields supplied, or SP validation refusal).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks EDIT right, or a field-level edit is denied. The message contains the offending field key for field-level denials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — optimistic-concurrency: the entity was modified by another session since `expected_updated_at`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "entitiesDeleteEntity", "summary": "Soft-delete an entity", "description": "Soft-deletes an entity (sets `deleted_at`). Requires `project.view` (SP enforces five-right DELETE gate). The entity is hidden from list/get responses after deletion.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entity deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entities/{entityId}/transition": { "post": { "operationId": "entitiesTransitionEntityState", "summary": "Transition entity workflow state", "description": "Moves an entity to a new workflow state. Requires `project.view` (SP enforces the five-right EDIT gate plus step role/group requirements). An illegal workflow edge returns `CONFLICT`; an unknown state returns `VALIDATION_ERROR`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_TransitionEntityRequest" } } } }, "responses": { "200": { "description": "Entity transitioned to the new workflow state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (unknown `to_state_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks edit access or does not meet the step's role/group requirement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — illegal workflow edge (no transition defined from the current state to `to_state_id`), or optimistic-concurrency mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entities/{entityId}/purge": { "post": { "operationId": "entitiesPurgeEntity", "summary": "Hard-purge an entity", "description": "Permanently deletes an entity and all associated data. Requires the five-right `can_purge` right (SP-enforced). This operation is irreversible.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entity permanently deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entities/{entityId}/comments": { "get": { "operationId": "entitiesListEntityComments", "summary": "List entity comments", "description": "Returns the comments on an entity with offset pagination. Requires `project.view` permission.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of comments to return (1–200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "List of comments.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_EntityComment" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateEntityComment", "summary": "Create an entity comment", "description": "Adds a comment to an entity. Requires `project.update` permission. Supports threaded replies via `parent_comment_id`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateCommentRequest" } } } }, "responses": { "201": { "description": "Comment created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_EntityComment" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — entity or `parent_comment_id` does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entities/{entityId}/media": { "post": { "operationId": "entitiesUploadEntityMedia", "summary": "Upload entity media", "description": "Uploads a binary media asset and attaches it to a named field on the entity. Accepts either `multipart/form-data` (with a `file` part + `field_key` field) or a raw body with `?field_key=&filename=&content_type=` query parameters. The server performs magic-byte validation to determine the authoritative content type; the declared content type must also be on the allowlist (images, audio, video, common documents). Maximum 100 MiB. Returns the media descriptor `id` that the entity field stores.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "field_key", "in": "query", "required": false, "description": "Entity field key to attach the media to (required when using a raw body upload; 1–128 chars matching `^[A-Za-z0-9_.-]+$`).", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_.-]+$" } }, { "name": "filename", "in": "query", "required": false, "description": "Original filename for display purposes (raw body upload only).", "schema": { "type": "string" } }, { "name": "content_type", "in": "query", "required": false, "description": "Declared MIME type (raw body upload only). Must be from the allowlist.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "field_key" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The media binary." }, "field_key": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Entity field key to attach the media to." } } } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw binary body. Use query params for field_key, filename, and content_type." } } } }, "responses": { "201": { "description": "Media uploaded and descriptor created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_EntityMedia" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` (bad field_key, missing content type, invalid UUID), `UNSUPPORTED_FILE_TYPE` (content type not allowlisted or bytes mismatch declared type), or `UPLOAD_SUPPRESSED` (file on deny list).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks EDIT right on the entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "`PAYLOAD_TOO_LARGE` — the uploaded file exceeds the 100 MiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — media storage is not configured or temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/entities/{entityId}/media/{mediaId}": { "get": { "operationId": "entitiesGetEntityMedia", "summary": "Get entity media (authenticated delivery)", "description": "Streams the binary payload of an entity media asset. The caller's `can_read` right on the owning entity is re-validated on every request. Returns the binary with appropriate `Content-Type`, `Cache-Control: private`, `X-Content-Type-Options: nosniff`, and a restrictive `Content-Security-Policy: default-src 'none'; sandbox`. Browser-renderable media (image/audio/video) is served `inline`; all other types force `Content-Disposition: attachment`. Content-addressed binaries support conditional GET with `If-None-Match`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "mediaId", "in": "path", "required": true, "description": "Media descriptor identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Binary payload with appropriate media content-type headers.", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "Not Modified — content unchanged since the ETag supplied in `If-None-Match`." }, "400": { "description": "`VALIDATION_ERROR` — one or both path UUIDs are malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — media or owning entity not found, or caller lacks read access (anti-enumeration: no access collapses to 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — media storage is not configured or unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/entities/{entityId}/effective-permissions": { "get": { "operationId": "entitiesGetEntityEffectivePermissions", "summary": "Get effective permissions on an entity", "description": "Returns the computed five-right effective permissions for the caller (or a specified in-org user) on the entity, with contributing grant sources. Self-view is available to any caller with entity visibility; inspecting another user's rights (`?user_id=`) is SP-gated to org admins and resource creators, and is audit-logged.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "description": "Entity identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "description": "Inspect effective permissions for another in-org user. Restricted to org admins and resource creators.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Effective permission set.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Entities_EffectivePermissions" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entity-types": { "get": { "operationId": "entitiesListEntityTypes", "summary": "List entity types", "description": "Returns the entity types visible to the caller's organization. Optionally filtered by project. Requires `project.view` permission.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Filter to entity types associated with a specific project.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "List of entity types.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateEntityType", "summary": "Create an entity type", "description": "Creates a new entity type schema in the caller's organization. Requires `entity_type.create` permission. Permission-flag configuration is validated by the stored procedure; invalid flag grammar returns `VALIDATION_ERROR`.", "tags": [ "Projects, Entities & Data Model" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateEntityTypeRequest" } } } }, "responses": { "201": { "description": "Entity type created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_EntityType" } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR` (field constraints or SP permission-flag validation).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — an entity type with that name or slug already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entity-types/{entityTypeId}": { "get": { "operationId": "entitiesGetEntityType", "summary": "Get an entity type", "description": "Returns a single entity type by identifier including render templates. Requires `project.view` permission. An invisible or non-existent entity type returns `NOT_FOUND`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityTypeId", "in": "path", "required": true, "description": "Entity type identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The entity type record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_EntityType" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "entitiesUpdateEntityType", "summary": "Update an entity type", "description": "Updates an entity type schema. Requires `entity_type.update` permission. Changing `fields` on an entity type with live entities is validated by the stored procedure; a conflict is returned if the change would break existing data.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityTypeId", "in": "path", "required": true, "description": "Entity type identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_UpdateEntityTypeRequest" } } } }, "responses": { "200": { "description": "Updated entity type.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_EntityType" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (no fields provided or SP validation).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — a field change is blocked because downstream entities are using the affected field; the response `details` contains which field and how many entities are affected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "entitiesDeleteEntityType", "summary": "Soft-delete an entity type", "description": "Soft-deletes an entity type. Requires `entity_type.delete` permission. An entity type that has already been deleted returns `NOT_FOUND`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityTypeId", "in": "path", "required": true, "description": "Entity type identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entity type deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entity-types/{entityTypeId}/adopt-package-update": { "post": { "operationId": "entitiesAdoptEntityTypePackageUpdate", "summary": "Adopt a publisher package update for an entity type", "description": "Pulls the latest publisher package update into a subscriber clone entity type. Useful when auto-propagation was skipped because the subscriber had locally diverged. Check `adopted_source_version` versus `source_current_version` on the entity type to detect whether an update is available. Requires `entity_type.update` permission.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityTypeId", "in": "path", "required": true, "description": "Entity type identifier (UUIDv7) of the subscriber clone.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Package update adopted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_EntityType" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — the packaged entity type clone was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entity-types/{entityTypeId}/purge": { "post": { "operationId": "entitiesPurgeEntityType", "summary": "Hard-purge an entity type", "description": "Permanently deletes an entity type and all entities of that type. Requires `entity_type.delete` permission plus the five-right `can_purge` right (SP-enforced). This operation is irreversible.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityTypeId", "in": "path", "required": true, "description": "Entity type identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entity type permanently deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entity-types/{entityTypeId}/effective-permissions": { "get": { "operationId": "entitiesGetEntityTypeEffectivePermissions", "summary": "Get effective permissions on an entity type", "description": "Returns computed five-right effective permissions for the caller (or a specified in-org user) on an entity type. Self-view for any caller with visibility; `?user_id=` is SP-gated to org admins and resource creators.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entityTypeId", "in": "path", "required": true, "description": "Entity type identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "description": "Inspect effective permissions for another in-org user (org admin / resource creator only).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Effective permission set.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Entities_EffectivePermissions" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entity-permissions": { "get": { "operationId": "entitiesListEntityPermissions", "summary": "List entity permission grants", "description": "Returns entity permission grants for the caller's organization. Supports filtering by resource type and resource id. Paginated. Access is SP-gated to resource owners and org admins.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "resource_type", "in": "query", "required": false, "description": "Filter by resource type.", "schema": { "type": "string", "enum": [ "entity", "entity_type" ] } }, { "name": "resource_id", "in": "query", "required": false, "description": "Filter to a specific resource (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_revoked", "in": "query", "required": false, "description": "When `true`, include revoked grants.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "List of permission grants.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_EntityPermission" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateEntityPermission", "summary": "Create an entity permission grant", "description": "Creates a five-right permission grant on an entity or entity type. Exactly one of `resource_id` or `criteria` must be provided. Criteria-based grants are restricted to org admins. Requires `project.view` (the SP gates to resource owner or org admin).", "tags": [ "Projects, Entities & Data Model" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateEntityPermissionRequest" } } } }, "responses": { "201": { "description": "Grant created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_EntityPermission" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR` (missing `resource_id`/`criteria`, both supplied, invalid permission flag name).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/entity-permissions/{permissionId}": { "delete": { "operationId": "entitiesDeleteEntityPermission", "summary": "Revoke an entity permission grant", "description": "Revokes an entity or entity-type permission grant. Authorization and ownership are resolved SP-side from the grant within the caller's organization. Requires `project.view` (the SP gates to resource owner or org admin).", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "permissionId", "in": "path", "required": true, "description": "Permission grant identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Grant revoked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/relationships": { "get": { "operationId": "entitiesListRelationships", "summary": "List entity relationships", "description": "Returns relationships for a specific entity. The `entity_id` query parameter is required. Optionally filtered by relationship type UUID and direction. Requires `project.view` on the entity.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "entity_id", "in": "query", "required": true, "description": "The entity whose relationships to list (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": false, "description": "Filter to a specific relationship type (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "direction", "in": "query", "required": false, "description": "Filter by direction from the reference entity. `outgoing` returns edges where the entity is the source; `incoming` returns edges where it is the target.", "schema": { "type": "string", "enum": [ "outgoing", "incoming" ] } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "List of relationships.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_Relationship" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (entity_id not a UUID) or `INVALID_PARAMETER` (unknown direction).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateRelationship", "summary": "Create a relationship between entities", "description": "Creates a directional relationship between two entities. Source and target must differ (`VALIDATION_ERROR` if equal). Requires `project.update` permission. Duplicate (source, target, type) returns `CONFLICT`.", "tags": [ "Projects, Entities & Data Model" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateRelationshipRequest" } } } }, "responses": { "201": { "description": "Relationship created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_Relationship" } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR` (same source/target, missing fields), or `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — source entity, target entity, or relationship type not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a relationship of this type between these two entities already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/relationships/{relationshipId}": { "delete": { "operationId": "entitiesDeleteRelationship", "summary": "Delete a relationship", "description": "Removes a relationship edge. Requires `project.delete` permission on the source entity.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "description": "Relationship identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Relationship deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/relationship-types": { "get": { "operationId": "entitiesListRelationshipTypes", "summary": "List relationship types", "description": "Returns all relationship types visible to the caller's organization. Requires `project.view` permission.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "List of relationship types.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_RelationshipType" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateRelationshipType", "summary": "Create a relationship type", "description": "Defines a new directed relationship type with forward and reverse labels. Requires `relationship_type.create` permission. Duplicate `name` within the organization returns `CONFLICT`.", "tags": [ "Projects, Entities & Data Model" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateRelationshipTypeRequest" } } } }, "responses": { "201": { "description": "Relationship type created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_RelationshipType" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR` (field constraints).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — a relationship type with that name already exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/views": { "get": { "operationId": "entitiesListViews", "summary": "List views", "description": "Returns saved views accessible to the caller within an organization. Filterable by `project_id`, `view_type`, and `is_shared`. Paginated.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Filter to views belonging to a specific project.", "schema": { "type": "string", "format": "uuid" } }, { "name": "view_type", "in": "query", "required": false, "description": "Filter by view rendering type.", "schema": { "type": "string", "enum": [ "board", "list", "table", "calendar", "timeline", "gantt" ] } }, { "name": "is_shared", "in": "query", "required": false, "description": "When `true`, return only shared views; `false` returns private views.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Paginated view list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_View" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "entitiesCreateView", "summary": "Create a view", "description": "Creates a new saved view. Only `name` is required; `view_type` defaults to `list`. If `project_id` is supplied the caller must have `project.update` permission on that project. SP validates the unified `config` object; invalid config returns `VALIDATION_ERROR`.", "tags": [ "Projects, Entities & Data Model" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_CreateViewRequest" } } } }, "responses": { "201": { "description": "View created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_View" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR` (name length, unknown view_type, missing project_id).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/views/templates": { "get": { "operationId": "entitiesListViewTemplates", "summary": "List view templates", "description": "Returns system-provided and organization view templates, optionally filtered by `view_type`. This is a static path registered before `GET /v1/views/{viewId}` in the router to ensure correct routing.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "view_type", "in": "query", "required": false, "description": "Filter templates to a specific view type.", "schema": { "type": "string", "enum": [ "board", "list", "table", "calendar", "timeline", "gantt" ] } } ], "responses": { "200": { "description": "List of view templates.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_View" } } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/views/{viewId}": { "get": { "operationId": "entitiesGetView", "summary": "Get a view", "description": "Returns a saved view by identifier. Requires `project.view` on the owning project.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "viewId", "in": "path", "required": true, "description": "View identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The view record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_View" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "entitiesUpdateView", "summary": "Update a view", "description": "Updates a saved view's configuration. Requires `project.update` on the owning project. At least one field must be provided.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "viewId", "in": "path", "required": true, "description": "View identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_UpdateViewRequest" } } } }, "responses": { "200": { "description": "Updated view record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_View" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (no fields provided).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "entitiesDeleteView", "summary": "Delete a view", "description": "Soft-deletes a saved view. Requires `project.update` on the owning project.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "viewId", "in": "path", "required": true, "description": "View identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "View deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/views/{viewId}/execute": { "post": { "operationId": "entitiesExecuteView", "summary": "Execute a view query", "description": "Runs the view's saved filter/sort/group configuration and returns the matching entity rows. Requires `project.view` on the owning project. This is the canonical Wave-4 execution endpoint.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "viewId", "in": "path", "required": true, "description": "View identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Page size for this execution (1–500)." }, "offset": { "type": "integer", "minimum": 0, "description": "Zero-based row offset." } } } } } }, "responses": { "200": { "description": "View execution results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_Entity" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (limit/offset out of range).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "entitiesExecuteViewLegacy", "summary": "Execute a view query (legacy GET alias)", "description": "Legacy GET alias for view execution. Prefer `POST /v1/views/{viewId}/execute`. Returns a combined view-config-plus-results object rather than a bare row array. The `limit` and `offset` query params are not forwarded; the response always uses default pagination (limit 50, offset 0). Clients should migrate to the POST form.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "name": "viewId", "in": "path", "required": true, "description": "View identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Combined view config and execution results.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "config": { "type": "object" }, "view_type": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object" } }, "rows": { "type": "array", "items": { "type": "object" } }, "total_count": { "type": "integer" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/org/{orgId}/templates/{templateId}/versions": { "get": { "operationId": "entitiesListOrgTemplateVersions", "summary": "List template versions (org-scoped)", "description": "Org-scoped alias for `GET /v1/templates/{templateId}/versions`. The `orgId` must match the session organization.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/OrgIdPath" }, { "name": "templateId", "in": "path", "required": true, "description": "Template identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated version history.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_TemplateVersion" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline": { "get": { "operationId": "entitiesGetPipelineConfig", "summary": "Get project pipeline configuration", "description": "Returns the CI/CD pipeline configuration for a project. Requires `project.view`. The `project_deployments` and `containers` system feature flags must be enabled; if not, all pipeline endpoints return `FORBIDDEN`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "Pipeline configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_PipelineConfig" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks project view access, or required feature flags are disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "entitiesUpsertPipelineConfig", "summary": "Create or update project pipeline configuration", "description": "Creates or updates the CI/CD pipeline root configuration for a project. Requires `project.update`. The `org_repo_id` linking the project to a connected repository is required. Idempotent: repeated calls update in place.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_UpsertPipelineConfigRequest" } } } }, "responses": { "200": { "description": "Pipeline configuration upserted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_PipelineConfig" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (missing `org_repo_id`, field bounds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/runs": { "get": { "operationId": "entitiesListPipelineRuns", "summary": "List pipeline runs", "description": "Returns pipeline deploy runs for a project with cursor-based pagination. Optionally filtered by `env_id`. Requires `project.view`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "env_id", "in": "query", "required": false, "description": "Filter to runs for a specific pipeline environment.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's response for pagination.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum runs to return per page.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of pipeline runs.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_PipelineRun" } }, "next_cursor": { "type": "string", "nullable": true } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/environments": { "put": { "operationId": "entitiesUpsertPipelineEnvironments", "summary": "Create or update a pipeline environment", "description": "Creates or updates a single pipeline environment definition for a project. Requires `project.update`. If `id` is present in the body the matching environment row is updated; otherwise a new row is created. Call once per environment to build the full set.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entities_UpsertPipelineEnvironmentItem" } } } }, "responses": { "200": { "description": "Pipeline environments upserted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (field bounds, duplicate rank, invalid commit SHA pattern).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/environments/{envId}/vault": { "post": { "operationId": "entitiesBindPipelineEnvironmentVault", "summary": "Bind a vault to a pipeline environment", "description": "Attaches a vault to a pipeline environment, making its secrets available during deploys. Requires `project.update`. The `members_fp` is a content fingerprint of the vault members list at bind time, used to detect drift.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "envId", "in": "path", "required": true, "description": "Pipeline environment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "vault_id", "members_fp" ], "properties": { "vault_id": { "type": "string", "format": "uuid", "description": "The vault to bind." }, "members_fp": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Content fingerprint of the vault members list at bind time." } } } } } }, "responses": { "200": { "description": "Vault bound to pipeline environment.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "entitiesUnbindPipelineEnvironmentVault", "summary": "Unbind a vault from a pipeline environment", "description": "Removes the vault binding from a pipeline environment. Requires `project.update`. The request body must be empty.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "envId", "in": "path", "required": true, "description": "Pipeline environment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Vault binding removed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR` (non-empty body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/environments/{envId}/secrets/{itemId}": { "put": { "operationId": "entitiesSetPipelineEnvironmentSecret", "summary": "Set a pipeline environment secret", "description": "Creates or updates a secret override for a pipeline environment. Requires `project.update`. The `content_fp` is a content fingerprint of the secret value, not the value itself.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "envId", "in": "path", "required": true, "description": "Pipeline environment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "description": "Secret item identifier (UUIDv7). Must match `item_id` in the body when provided.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "content_fp" ], "properties": { "item_id": { "type": "string", "format": "uuid", "description": "Optional — if supplied, must match the path `itemId`." }, "content_fp": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Content fingerprint of the secret value." } } } } } }, "responses": { "200": { "description": "Secret set.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (content_fp missing or too long).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/environments/{envId}/deploy": { "post": { "operationId": "entitiesDeployPipelineEnvironment", "summary": "Trigger a deploy for a pipeline environment", "description": "Enqueues a deploy run for a specific pipeline environment. Requires `project.update`. An optional `commit_sha` (40 hex chars case-insensitive) pins the deploy to a specific commit; omitting it deploys the branch HEAD.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "envId", "in": "path", "required": true, "description": "Pipeline environment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commit_sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$", "description": "Optional full 40-hex-char commit SHA to deploy. Omit to deploy branch HEAD." } } } } } }, "responses": { "200": { "description": "Deploy run enqueued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_PipelineRun" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (malformed commit SHA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/promote/prepare": { "post": { "operationId": "entitiesPreparePipelinePromotion", "summary": "Prepare a pipeline promotion", "description": "Validates a promotion between pipeline environments and returns a run id. Requires `project.update`. Optional source and target commit SHAs and a `content_fp` content fingerprint allow specifying the exact artifact to promote.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "source_environment_id", "target_environment_id" ], "properties": { "source_environment_id": { "type": "string", "format": "uuid", "description": "Source pipeline environment." }, "target_environment_id": { "type": "string", "format": "uuid", "description": "Target pipeline environment." }, "source_commit_sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$", "description": "Optional source commit SHA." }, "target_base_commit_sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$", "description": "Optional target base commit SHA for diff calculation." }, "content_fp": { "type": "string", "maxLength": 256, "description": "Optional artifact content fingerprint." } } } } } }, "responses": { "200": { "description": "Promotion validated. Returns a `run_id` to pass to `POST /promote/start`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, `VALIDATION_ERROR` (malformed SHA, missing required fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — a promotion is already in flight for the target environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/promote/start": { "post": { "operationId": "entitiesStartPipelinePromotion", "summary": "Start a prepared pipeline promotion", "description": "Starts a previously prepared promotion run. Requires `project.update`. The `run_id` must refer to a run in `prepared` state from a prior `/promote/prepare` call.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "run_id" ], "properties": { "run_id": { "type": "string", "format": "uuid", "description": "The run_id returned by `/promote/prepare`." } } } } } }, "responses": { "200": { "description": "Promotion started.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_PipelineRun" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (run not in prepared state).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/runs/{runId}/events": { "get": { "operationId": "entitiesGetPipelineRunEvents", "summary": "Get pipeline run events", "description": "Returns the event stream for a pipeline run (log lines, status changes, step boundaries). Supports tail-following via `after_seq`. Requires `project.view`.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "runId", "in": "path", "required": true, "description": "Pipeline run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "after_seq", "in": "query", "required": false, "description": "Sequence number of the last event seen; returns only events after this sequence.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum events to return.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "List of pipeline run events.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `INVALID_PARAMETER`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/runs/{runId}/retry": { "post": { "operationId": "entitiesRetryPipelineRun", "summary": "Retry a failed pipeline run", "description": "Retries a failed or cancelled pipeline run, creating a new run from the same configuration. Requires `project.update`. The run must be in a terminal state. Request body must be empty.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "runId", "in": "path", "required": true, "description": "Pipeline run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "New retry run enqueued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Entities_PipelineRun" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR` (run is not in a terminal state).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/runs/{runId}/cancel": { "post": { "operationId": "entitiesCancelPipelineRun", "summary": "Cancel an active pipeline run", "description": "Requests cancellation of an in-progress pipeline run. Requires `project.update`. The run must be in a non-terminal state.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "runId", "in": "path", "required": true, "description": "Pipeline run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancellation requested.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` or `VALIDATION_ERROR` (run is already in a terminal state).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — the run has already transitioned to a terminal state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/environments/{envId}/approval-policy": { "put": { "operationId": "entitiesUpsertPipelineApprovalPolicy", "summary": "Set pipeline environment approval policy", "description": "Creates or replaces the approval gate policy for a protected pipeline environment. Requires `project.update`. Protected environments require N-of-M approval before a promotion can start.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "envId", "in": "path", "required": true, "description": "Pipeline environment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "rules": { "description": "Approval rule set. Shape is opaque to the API — validated SP-side.", "nullable": true }, "allow_self_approval": { "type": "boolean", "description": "When false, the user who triggered the run cannot approve it. Defaults to false." } } } } } }, "responses": { "200": { "description": "Approval policy set.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (invalid rule grammar).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/pipeline/runs/{runId}/approve": { "post": { "operationId": "entitiesRespondToPipelineApproval", "summary": "Approve or reject a pipeline run", "description": "Submits an approval or rejection decision on a pipeline run waiting at a protected environment gate. Requires `project.update`. Self-approval is blocked if `allow_self_approval=false` on the environment's approval policy.", "tags": [ "Projects, Entities & Data Model" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "runId", "in": "path", "required": true, "description": "Pipeline run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "approve", "reject" ], "description": "Approval decision." } } } } } }, "responses": { "200": { "description": "Approval decision recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_JSON`, or `VALIDATION_ERROR` (unknown action, run not awaiting approval).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks permission, or `allow_self_approval=false` and the caller is the run initiator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — the run has already been approved/rejected by this user or has moved to a terminal state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "description": "Returns the projects in the caller's organization that the caller can see, with offset pagination. Requires a valid session; the organization and RLS scope are derived from the access token.", "tags": [ "Projects" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by lifecycle status (e.g. `active`, `archived`). Omit for the default active set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of projects to return (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of projects to skip for pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of projects.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Projects_Project" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createProject", "summary": "Create a project", "description": "Creates a new project in the caller's organization. The only required field is `name`. A URL-safe `slug` is generated from the name when omitted. The organization is taken from the session — `org_id` is never accepted in the body. Returns the full created record, including the platform-assigned `id`, `slug`, `is_active`, and timestamps.", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Projects_CreateProjectRequest" }, "example": { "name": "Q2 Client Onboarding" } } } }, "responses": { "201": { "description": "Project created. The full project record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Projects_Project" } } } ] }, "example": { "success": true, "data": { "id": "019d0000-0000-7000-8000-000000000000", "org_id": "019c0000-0000-7000-8000-000000000000", "name": "Q2 Client Onboarding", "slug": "q2-client-onboarding-3f9a2c", "description": null, "prefix": null, "visibility": "private", "category_id": null, "owner_scope": "organization", "is_active": true, "created_by_user_id": "019b0000-0000-7000-8000-000000000000", "created_at": "2026-04-13T12:00:00Z", "updated_at": "2026-04-13T12:00:00Z", "settings": {} } } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `VALIDATION_ERROR` (a field failed validation, including a non-canonical or reserved `slug` → message names `RESERVED_SLUG`/`INVALID_FORMAT`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`PERMISSION_DENIED` (missing the `project.create` permission) or `PROJECT_LIMIT_REACHED` (the organization's plan project limit is reached).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`PROJECT_SLUG_EXISTS` — a project with that slug already exists in this organization and environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}": { "get": { "operationId": "getProject", "summary": "Get a project", "description": "Returns a single project by id. A project the caller cannot see is reported as `404 NOT_FOUND` (indistinguishable from a missing one, per the anti-enumeration contract).", "tags": [ "Projects" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "The project record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Projects_Project" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "updateProject", "summary": "Update a project", "description": "Updates a project's name, slug, description, visibility, archive state, or settings. At least one field must be provided. `description: null` clears the description; `is_active` toggles archive/active.", "tags": [ "Projects" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Projects_UpdateProjectRequest" } } } }, "responses": { "200": { "description": "The updated project record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Projects_Project" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`PROJECT_SLUG_EXISTS` — the requested slug is already taken in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteProject", "summary": "Delete (archive) a project", "description": "Soft-deletes a project by setting `is_active = false`. The underlying data is preserved for recovery and the audit trail; the project is hidden from listings.", "tags": [ "Projects" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "The project was soft-deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean", "enum": [ false ] } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/members": { "get": { "operationId": "listProjectMembers", "summary": "List project members", "description": "Returns the members of a project with offset pagination.", "tags": [ "Projects" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Paginated list of project members.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Projects_ProjectMember" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "addProjectMember", "summary": "Add a project member", "description": "Adds a user to the project with a role. The acting user must have permission to manage project membership.", "tags": [ "Projects" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Projects_AddMemberRequest" }, "example": { "user_id": "019b0000-0000-7000-8000-000000000000", "role": "editor" } } } }, "responses": { "201": { "description": "The member was added.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Projects_ProjectMember" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/members/{userId}": { "delete": { "operationId": "removeProjectMember", "summary": "Remove a project member", "description": "Removes a user from the project. A non-existent or cross-tenant project is reported as `404 NOT_FOUND`.", "tags": [ "Projects" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "userId", "in": "path", "required": true, "description": "The user to remove (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The member was removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/settings": { "put": { "operationId": "upsertProjectSettings", "summary": "Upsert project settings", "description": "Replaces the project's settings JSON object. The body is a bounded JSON object validated for size and depth.", "tags": [ "Projects" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Arbitrary bounded settings object (size/depth limited).", "additionalProperties": true } } } }, "responses": { "200": { "description": "The settings were saved.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases": { "post": { "operationId": "releasesCreateRelease", "summary": "Create a release", "description": "Creates a new draft release for the given SaaS package. The release name must be unique within the package. Returns the full release record.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_CreateReleaseRequest" } } } }, "responses": { "201": { "description": "Release created. The full release record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Releases_Release" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR` (name missing, exceeds 200 chars, or invalid package ID) or `INVALID_ID_FORMAT` (malformed packageId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.create` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "releasesListReleases", "summary": "List releases", "description": "Returns paginated releases for a SaaS package, optionally filtered by status.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by release status.", "schema": { "type": "string", "enum": [ "draft", "testing", "approved", "rejected", "archived" ] } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated list of releases.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_Release" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/diff": { "get": { "operationId": "releasesDiffReleases", "summary": "Diff two releases", "description": "Returns a semantic diff of the version-pinned manifest between two releases of the same package. Both `from` and `to` must be UUIDs of releases that belong to this package.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Release ID to diff from (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "to", "in": "query", "required": true, "description": "Release ID to diff to (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Diff result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Platform-generated diff object showing added, removed, and changed manifest items.", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}": { "get": { "operationId": "releasesGetRelease", "summary": "Get a release", "description": "Returns a single release record by ID.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Release record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Releases_Release" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — malformed packageId or releaseId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/status": { "patch": { "operationId": "releasesUpdateReleaseStatus", "summary": "Update release status", "description": "Transitions the release to the specified status. Valid transitions are enforced server-side; an invalid transition returns `422 VALIDATION_ERROR`.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_UpdateReleaseStatusRequest" } } } }, "responses": { "200": { "description": "Release status updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Releases_Release" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — the requested status transition is invalid for the release's current state (e.g. transition preconditions not met).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/deploy": { "post": { "operationId": "releasesDeployRelease", "summary": "Deploy a release", "description": "Deploys the release to the specified environment. Supports four rollout strategies: `immediate` (all tenants at once), `targeted` (explicit list of org IDs), `percentage` (a random sample), and `progressive` (staged percentage ramp-up with configurable wait periods). A progressive deploy with `rollout_stages` starts the rollout scheduler automatically. Invalidates the application-config KV cache on success.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_DeployReleaseRequest" } } } }, "responses": { "200": { "description": "Deployment initiated. Returns the deployment record. If a `progressive` strategy was requested, `rollout_plan_id` is included.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_DeploymentResult" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.deploy` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — an active deployment already exists for this environment, or the release is in an invalid state for deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`VALIDATION_ERROR` — the release cannot be deployed (e.g. approval required, compliance check required, or rejection in place).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/rollback": { "post": { "operationId": "releasesRollbackRelease", "summary": "Rollback a release", "description": "Rolls back the active deployment in the specified environment to the previously deployed release. Only `staging`, `preprod`, and `production` environments support rollback.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_RollbackRequest" } } } }, "responses": { "200": { "description": "Rollback initiated. Returns the new deployment record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_DeploymentResult" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.rollback` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — no prior deployment exists to roll back to, or the transition is otherwise invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/undeploy": { "post": { "operationId": "releasesUndeployRelease", "summary": "Undeploy a release", "description": "Removes the current deployment from the specified environment, leaving the environment with no active release. Only `staging`, `preprod`, and `production` environments are supported.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_UndeployRequest" } } } }, "responses": { "200": { "description": "Release undeployed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.deploy` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — no active deployment in the requested environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/environments": { "get": { "operationId": "releasesGetEnvironmentStatus", "summary": "Get environment deployment status", "description": "Returns the currently deployed release for each environment (development, staging, preprod, production) for the given SaaS package.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Per-environment deployment status.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_EnvironmentStatus" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/environments/history": { "get": { "operationId": "releasesGetDeploymentHistory", "summary": "Get deployment history", "description": "Returns the paginated deployment history for a SaaS package, optionally filtered by environment.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "environment", "in": "query", "required": false, "description": "Filter by environment.", "schema": { "type": "string", "enum": [ "staging", "preprod", "production" ] } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated deployment history.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_DeploymentHistoryEntry" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/approval-policies": { "post": { "operationId": "releasesCreateApprovalPolicy", "summary": "Create an approval policy", "description": "Creates an approval policy for the SaaS package. The `rules` field must be a top-level branch node (`{operator, conditions}`) — bare leaf conditions at the top level are rejected. The conditions tree is limited to 5 levels of nesting. The request body is limited to 8 KiB to guard against deeply-nested rule trees.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_CreateApprovalPolicyRequest" } } } }, "responses": { "201": { "description": "Approval policy created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Releases_ApprovalPolicy" } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR` (field validation or rules tree exceeds depth limit), or `PAYLOAD_TOO_LARGE` (body > 8 KiB).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `approval_policy.create` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — a policy with this category is already active for the package.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "releasesGetApprovalPolicies", "summary": "Get approval policies", "description": "Returns all approval policies for the SaaS package.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of approval policies.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_ApprovalPolicy" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/approval-policies/{policyId}": { "delete": { "operationId": "releasesDeactivateApprovalPolicy", "summary": "Deactivate an approval policy", "description": "Soft-deactivates an approval policy. A deactivated policy is no longer enforced for new approval requests.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "policyId", "in": "path", "required": true, "description": "Approval policy identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Policy deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `approval_policy.delete` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — policy is currently in use by a pending approval and cannot be deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/request-approval": { "post": { "operationId": "releasesRequestApproval", "summary": "Request approval for a release", "description": "Submits an approval request for the release targeting the specified environment. Requires an active approval policy to exist for the target environment category; if none exists, returns `409 CONFLICT`.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_RequestApprovalRequest" } } } }, "responses": { "200": { "description": "Approval request submitted. Returns the approval request record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.update` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — no active approval policy exists for the target environment category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`VALIDATION_ERROR` — the release is not in a state from which approval can be requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/approve": { "post": { "operationId": "releasesApproveRelease", "summary": "Approve a release", "description": "Records an approval decision for the release targeting the specified environment. Separation-of-duties is enforced: the approver must not be the requester (when the package policy requires it).", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_ApproveRequest" } } } }, "responses": { "200": { "description": "Approval recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.approve` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — separation-of-duties violation, wrong release state, or no active approval request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/reject": { "post": { "operationId": "releasesRejectRelease", "summary": "Reject a release", "description": "Records a rejection decision for a pending approval. The `reason` field is required for audit purposes.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_RejectRequest" } } } }, "responses": { "200": { "description": "Rejection recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.approve` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — no active approval request to reject, or wrong release state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/approval-status": { "get": { "operationId": "releasesGetApprovalStatus", "summary": "Evaluate approval policy status", "description": "Evaluates the current approval policy for the release and environment, returning whether approval requirements are satisfied, the individual approver decisions, and which approvers are still outstanding.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "environment", "in": "query", "required": true, "description": "Environment to evaluate approval for.", "schema": { "type": "string", "enum": [ "staging", "preprod", "production" ] } } ], "responses": { "200": { "description": "Approval policy evaluation result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_ApprovalStatusResult" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/comments": { "post": { "operationId": "releasesCreateComment", "summary": "Create a release comment", "description": "Adds a comment to a release. Comments can be threaded via `parent_comment_id` and scoped to a specific environment.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_CreateCommentRequest" } } } }, "responses": { "201": { "description": "Comment created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Comment" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.comment` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "releasesListComments", "summary": "List release comments", "description": "Returns paginated comments for a release, optionally filtered by environment or comment type.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "environment", "in": "query", "required": false, "description": "Filter by environment.", "schema": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] } }, { "name": "comment_type", "in": "query", "required": false, "description": "Filter by comment type.", "schema": { "type": "string", "enum": [ "general", "bug", "test_pass", "test_fail", "approval", "rejection", "task" ] } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Records per page (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated comment list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_Comment" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/compliance-check": { "post": { "operationId": "releasesRunComplianceCheck", "summary": "Run a compliance check", "description": "Evaluates the release against compliance requirements for the target environment (approval status, mandatory tests, change-window restrictions, etc.). Returns a structured compliance result indicating pass/fail per check.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_ComplianceCheckRequest" } } } }, "responses": { "200": { "description": "Compliance check result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Structured compliance result with per-check pass/fail details.", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.compliance` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/import-to-draft": { "post": { "operationId": "releasesImportToDraft", "summary": "Import a release to draft", "description": "Imports the specified release's configuration into a new draft for the package. Used to create a new release pre-populated from an existing one (e.g. to re-apply a deployed config as a baseline for new changes).", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier to import (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_ImportToDraftRequest" } } } }, "responses": { "200": { "description": "Import completed. Returns the new draft release.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Release" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.import` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/releases/{releaseId}/items": { "get": { "operationId": "releasesListReleaseItems", "summary": "List release manifest items", "description": "Returns the version-pinned manifest items for the release. Each item represents a configuration artifact (screen, seed, connector, etc.) pinned at a specific version in this release snapshot.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "releaseId", "in": "path", "required": true, "description": "Release identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Release manifest items.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "A single version-pinned manifest item." } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/rollouts": { "post": { "operationId": "releasesCreateRollout", "summary": "Create a rollout plan", "description": "Creates a rollout plan for an existing active deployment. The plan defines how the release is progressively distributed across tenants. Requires `saas_release.deploy` permission.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_CreateRolloutRequest" } } } }, "responses": { "201": { "description": "Rollout plan created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_RolloutPlan" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.deploy` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — a rollout plan already exists for this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/rollouts/{rolloutId}": { "get": { "operationId": "releasesGetRolloutStatus", "summary": "Get rollout status", "description": "Returns the current rollout plan status including per-stage progress.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "rolloutId", "in": "path", "required": true, "description": "Rollout plan identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rollout plan with per-stage progress.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_RolloutPlan" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/rollouts/{rolloutId}/advance": { "post": { "operationId": "releasesAdvanceRollout", "summary": "Advance rollout to next stage", "description": "Manually advances a progressive rollout to the next stage without waiting for the scheduled wait period to expire.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "rolloutId", "in": "path", "required": true, "description": "Rollout plan identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rollout advanced to the next stage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.deploy` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — rollout is not in a state that can be advanced (e.g. already complete or cancelled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/rollouts/{rolloutId}/pause": { "post": { "operationId": "releasesPauseRollout", "summary": "Pause a rollout", "description": "Pauses a progressive rollout at the current stage. An optional `reason` can be provided. The rollout can be resumed by advancing to the next stage.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "rolloutId", "in": "path", "required": true, "description": "Rollout plan identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_RolloutActionRequest" } } } }, "responses": { "200": { "description": "Rollout paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.deploy` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/rollouts/{rolloutId}/cancel": { "post": { "operationId": "releasesCancelRollout", "summary": "Cancel a rollout", "description": "Cancels a progressive rollout. The rollout is terminated and no further stages will be executed. An optional `reason` can be provided.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "rolloutId", "in": "path", "required": true, "description": "Rollout plan identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_RolloutActionRequest" } } } }, "responses": { "200": { "description": "Rollout cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `saas_release.deploy` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/products/{slug}": { "put": { "operationId": "releasesUpsertProduct", "summary": "Upsert a release product", "description": "Creates or updates a desktop release product definition for the authenticated organization. A product groups versions across channels for a single distributable tool.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Product slug (lowercase alphanumeric with dots, hyphens, or underscores; 1–100 chars).", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_ProductUpsertRequest" } } } }, "responses": { "200": { "description": "Product created or updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Product" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.manage` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the custom domain is already taken by another product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/products/{slug}/versions": { "post": { "operationId": "releasesPublishStart", "summary": "Start a release version publish", "description": "Opens a new version staging record for the product. Call this before uploading artefacts. Returns the staging version ID used for subsequent `/artefacts`, `/complete`, and `/finalize` calls.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Product slug.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_PublishStartRequest" } } } }, "responses": { "201": { "description": "Staging version created. Returns the staging release record including the version ID.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_StagingVersion" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.publish` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — product slug not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a version with this version string already exists for the product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/versions/{id}/artefacts": { "post": { "operationId": "releasesAddArtefact", "summary": "Add an artefact to a staged version", "description": "Registers a platform-specific binary artefact (OS + arch combination) against a staged release version. The artefact must have already been uploaded to R2; this call records its `r2_key`, `sha256_hex`, and optional platform-signed digest.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Staged release version identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_AddArtefactRequest" } } } }, "responses": { "200": { "description": "Artefact registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.publish` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — the staging version is in an invalid state (e.g. already finalized or yanked).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/versions/{id}/complete": { "post": { "operationId": "releasesPublishComplete", "summary": "Complete a staged version", "description": "Marks the artefact upload phase as complete, records optional release notes URL, minimum OS requirements, and whether this is a forced upgrade.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Staged release version identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_PublishCompleteRequest" } } } }, "responses": { "200": { "description": "Version marked complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.publish` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — no artefacts have been registered or the version state is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/versions/{id}/finalize": { "post": { "operationId": "releasesPublishFinalize", "summary": "Finalize a staged version", "description": "Finalizes the staged version by recording the manifest SHA-256 hash and an Ed25519 signature over the manifest. The version is published and becomes visible to update checks after this call.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Staged release version identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_PublishFinalizeRequest" } } } }, "responses": { "200": { "description": "Version finalized and published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.publish` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — the version is not in the `complete` state, or the active signing key is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/versions/{id}": { "delete": { "operationId": "releasesCancelStagedVersion", "summary": "Cancel a staged release version", "description": "Cancels and removes a staged (not-yet-finalized) release version. Returns `VALIDATION_ERROR` if the version has already been finalized.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Staged release version identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Staged version cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.publish` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — the version is already finalized and cannot be cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/products/{slug}/channels/{channel}/promote": { "post": { "operationId": "releasesPromoteVersion", "summary": "Promote a version to a channel", "description": "Promotes the specified version to the target channel (e.g. promoting from `beta` to `stable`). The specified version string must already be finalized.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Product slug.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "channel", "in": "path", "required": true, "description": "Source channel to promote from (e.g. `beta`, `nightly`). Alphanumeric with dots/hyphens/underscores.", "schema": { "type": "string", "minLength": 1, "maxLength": 50 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_PromoteRequest" } } } }, "responses": { "200": { "description": "Version promoted to the target channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.publish` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — the target channel already has this version or a newer one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/versions/{id}/yank": { "post": { "operationId": "releasesYankVersion", "summary": "Yank a release version", "description": "Yanks a published version so that update checks no longer offer it to clients. Requires both `product_slug` and `version` in the body alongside the path `id`. A reason is mandatory for audit purposes.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Release version surrogate identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_YankRequest" } } } }, "responses": { "200": { "description": "Version yanked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.yank` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — the version is already yanked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/versions/{id}/rollout": { "patch": { "operationId": "releasesSetRolloutPercentage", "summary": "Set rollout percentage for a version", "description": "Sets the rollout percentage for a published version. A percentage of `0` pauses rollout; `100` completes it. Requires both `product_slug` and `version` in the body.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Release version surrogate identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_SetRolloutRequest" } } } }, "responses": { "200": { "description": "Rollout percentage updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.publish` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`VALIDATION_ERROR` — the version has been yanked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/signing-keys": { "post": { "operationId": "releasesCreateSigningKey", "summary": "Register a signing key", "description": "Registers an Ed25519 public signing key for the organization's release pipeline. The key is identified by `key_id` (human-readable); `public_key_hex` is the 32-byte raw Ed25519 public key as 64 hex chars. Optionally chains from a prior key via `signed_by_key_id` and `successor_signature_hex`.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_SigningKeyCreateRequest" } } } }, "responses": { "201": { "description": "Signing key registered.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_SigningKey" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.manage_keys` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a key with this `key_id` already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/signing-keys/{id}/revoke": { "post": { "operationId": "releasesRevokeSigningKey", "summary": "Revoke a signing key", "description": "Revokes the signing key identified by `id` (the textual `key_id`, not a UUID). Revoked keys are retained for historical verification but are excluded from the active key chain.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The signing key's textual `key_id` (1–200 chars, not a UUID).", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_SigningKeyRevokeRequest" } } } }, "responses": { "200": { "description": "Signing key revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `releases.manage_keys` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — the key is already revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/{slug}/current": { "get": { "operationId": "releasesGetCurrentVersion", "summary": "Get the current release version (public)", "description": "Returns the latest published version for the product and channel visible to the given organization. This is the update-check endpoint called by installed desktop clients. No authentication is required; `org_id` must be supplied as a query parameter to scope the lookup.", "tags": [ "Releases & Automation" ], "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Product slug.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "org_id", "in": "query", "required": true, "description": "Organization identifier (UUIDv7) — required because no session is present.", "schema": { "type": "string", "format": "uuid" } }, { "name": "channel", "in": "query", "required": false, "description": "Distribution channel (1–50 chars). Defaults to the product's primary channel when omitted.", "schema": { "type": "string", "minLength": 1, "maxLength": 50 } }, { "name": "current_version", "in": "query", "required": false, "description": "The client's installed version string. Included in telemetry; does not change the response.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "install_id_hash", "in": "query", "required": false, "description": "Pseudonymous install ID hash (≤256 chars) for analytics. Never linked to a user.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "responses": { "200": { "description": "Current release version record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_CurrentVersion" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/releases/signing-keys/chain": { "get": { "operationId": "releasesGetSigningKeyChain", "summary": "Get the signing key chain (public)", "description": "Returns the full chain of active and revoked public signing keys for the organization. Clients use this to verify the integrity and authenticity of release manifests. No authentication is required; `org_id` must be supplied as a query parameter.", "tags": [ "Releases & Automation" ], "security": [], "parameters": [ { "name": "org_id", "in": "query", "required": true, "description": "Organization identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signing key chain.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_SigningKey" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/setup": { "get": { "operationId": "deploymentsGetSetup", "summary": "Get deployment setup", "description": "Returns the deployment configuration for the authenticated organization (configs, environments, approval policies, and run summary). Pass `config_id` to scope the response to a single configuration.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "config_id", "in": "query", "required": false, "description": "Deployment config identifier (UUIDv7) to filter the response.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployment setup record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Deployment setup object." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/configs": { "post": { "operationId": "deploymentsUpsertConfig", "summary": "Upsert a deployment config", "description": "Creates or updates a deployment configuration record. The config links a repository to the deployment system via vault and encryption key references.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_DeploymentConfigUpsertRequest" } } } }, "responses": { "200": { "description": "Config created or updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/environments": { "post": { "operationId": "deploymentsUpsertEnvironment", "summary": "Upsert a deployment environment", "description": "Creates or updates a deployment environment within a config. Environments define the branch, deploy commands, container size, and secret exposure.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_DeploymentEnvironmentUpsertRequest" } } } }, "responses": { "200": { "description": "Environment created or updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/approval-policy": { "post": { "operationId": "deploymentsSetApprovalPolicy", "summary": "Set a deployment approval policy", "description": "Creates or replaces the approval policy for a deployment environment. The policy specifies which roles must approve a run to `production` or `preprod` and minimum approval quorums.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_DeploymentApprovalPolicyRequest" } } } }, "responses": { "200": { "description": "Approval policy set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/approvals": { "post": { "operationId": "deploymentsRecordApproval", "summary": "Approve or reject a deployment run", "description": "Records an approval or rejection decision for a pending deployment run. The `action` field determines the decision. Dual-approval rules (BB-03) are enforced by the stored procedure; a second approver in the same role is required for production deployments when the policy requires it.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_DeploymentApproveRequest" } } } }, "responses": { "200": { "description": "Approval or rejection recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — dual-approval requirement not yet satisfied; or another approval gate conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/solo-mode": { "post": { "operationId": "deploymentsSetSoloMode", "summary": "Set solo-operator mode", "description": "Enables or disables solo-operator mode for a deployment config. In solo mode a single-person organization can deploy without a second approver.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_DeploymentSoloModeRequest" } } } }, "responses": { "200": { "description": "Solo-operator mode updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/runs": { "post": { "operationId": "deploymentsStartRun", "summary": "Start a deployment run", "description": "Creates a queued deployment run for the given environment and commit SHA, then best-effort provisions a deploy container. The run record is created regardless of container provisioning success. If provisioning fails, `orchestrated: false` is returned and the run can be retried. Requires the `deployment.trigger` permission.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_DeploymentRunStartRequest" } } } }, "responses": { "200": { "description": "Run queued. `orchestrated: true` if the container was successfully started. If `orchestrated: false`, `orchestration_error` contains a non-fatal reason.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_DeployRunResult" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — dual-approval gate not met; submit approvals first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/runs/{runId}/retry": { "post": { "operationId": "deploymentsRetryRun", "summary": "Retry a deployment run", "description": "Retries a failed or cancelled deployment run.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Deployment run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run retry queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/runs/{runId}/cancel": { "post": { "operationId": "deploymentsCancelRun", "summary": "Cancel a deployment run", "description": "Cancels a queued or running deployment run.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Deployment run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 2000, "description": "Optional cancellation reason." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Run cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/runs/{runId}/events": { "post": { "operationId": "deploymentsRecordRunEvent", "summary": "Record a deployment run event (container only)", "description": "Records a structured progress/status event for a deployment run. This endpoint is called **only** by the deploy container using its per-run instance token (`apiKeyAuth`). A human session JWT is rejected. When the container reports a terminal status (`succeeded`, `failed`, or `cancelled`), the instance token is revoked automatically.", "tags": [ "Releases & Automation" ], "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Deployment run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_DeploymentRunEventRequest" } } } }, "responses": { "200": { "description": "Event recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the token is not a valid deployment instance token or is not bound to this run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "deploymentsListRunEvents", "summary": "List deployment run events", "description": "Returns the progress/error log for a deployment run. Supports incremental polling via `?after_seq=` to fetch only events since the last poll.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Deployment run identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "after_seq", "in": "query", "required": false, "description": "Return only events with a sequence number greater than this value.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run event log.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/secret-keys": { "get": { "operationId": "deploymentsListSecretKeys", "summary": "List secret keys available to this run (container only)", "description": "Returns the list of escrow secret item IDs that the running deploy container is authorized to fetch. This endpoint requires a deployment instance token (`apiKeyAuth`); a user JWT is rejected. Use the returned IDs with `POST /v1/deployments/secret-value` to retrieve decrypted values.", "tags": [ "Releases & Automation" ], "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "List of authorized secret item IDs.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller is not a deployment instance token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/deployments/secret-value": { "post": { "operationId": "deploymentsGetSecretValue", "summary": "Get a decrypted secret value (container only)", "description": "Authorizes and returns the decrypted plaintext value of the specified secret item. This endpoint requires a deployment instance token (`apiKeyAuth`); a user JWT is rejected. The value is decrypted in the API worker — never in the database — and returned over TLS. The container is expected to hold values in memory only.", "tags": [ "Releases & Automation" ], "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "item_id" ], "additionalProperties": false, "properties": { "item_id": { "type": "string", "format": "uuid", "description": "Escrow secret item identifier (UUIDv7)." } } } } } }, "responses": { "200": { "description": "Decrypted secret value.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Secret name." }, "value": { "type": "string", "description": "Decrypted plaintext value." } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller is not a deployment instance token, or is not authorized to access this secret for this run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/feature-flags/effective": { "get": { "operationId": "featureFlagsGetEffective", "summary": "Get effective feature flags for caller", "description": "Returns the effective (resolved) feature flag state for the authenticated user and their organization. Available to any authenticated user; does not require super-admin.", "tags": [ "Releases & Automation" ], "responses": { "200": { "description": "Resolved feature flag states for the caller's organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "feature_flags": { "type": "object", "additionalProperties": true, "description": "Resolved feature flag state map." } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/campaigns": { "get": { "operationId": "campaignsList", "summary": "List campaigns", "description": "Returns all campaigns for the authenticated organization. Supports optional `status` and `type` query filters.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by campaign status: `active` or `paused`.", "schema": { "type": "string", "enum": [ "active", "paused" ] } }, { "name": "type", "in": "query", "required": false, "description": "Filter by campaign type.", "schema": { "type": "string", "enum": [ "drip", "sequence", "one_shot" ] } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Campaign list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_Campaign" } }, "total_count": { "type": "integer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "campaignsCreate", "summary": "Create a campaign", "description": "Creates a new campaign for the authenticated organization.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_CampaignCreateRequest" } } } }, "responses": { "201": { "description": "Campaign created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Campaign" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/campaigns/{id}": { "get": { "operationId": "campaignsGet", "summary": "Get a campaign", "description": "Returns a campaign by ID.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Campaign record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Campaign" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "campaignsUpdate", "summary": "Update a campaign", "description": "Updates campaign metadata. All fields are optional.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_CampaignUpdateRequest" } } } }, "responses": { "200": { "description": "Campaign updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Campaign" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "campaignsDelete", "summary": "Delete a campaign", "description": "Permanently deletes a campaign.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Campaign deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/campaigns/{id}/steps": { "get": { "operationId": "campaignsListSteps", "summary": "List steps for a campaign", "description": "Returns all steps for the specified campaign, ordered by `step_number`.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Campaign step list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_CampaignStep" } }, "total_count": { "type": "integer" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `id` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "campaignsAddStep", "summary": "Add a step to a campaign", "description": "Adds a step (email, notification, delay, condition, or action) to an existing campaign at the specified position (0-based, converted to 1-based `step_number` internally).", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_CampaignStepCreateRequest" } } } }, "responses": { "201": { "description": "Campaign step created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_CampaignStep" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/campaigns/{id}/steps/{stepId}": { "put": { "operationId": "campaignsUpdateStep", "summary": "Update a campaign step", "description": "Updates one or more fields of an existing campaign step. At least one field must be provided.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "stepId", "in": "path", "required": true, "description": "Step identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_CampaignStepUpdateRequest" } } } }, "responses": { "200": { "description": "Campaign step updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_CampaignStep" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `id` or `stepId` is not a valid UUID; or `VALIDATION_ERROR` — body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "campaignsDeleteStep", "summary": "Delete a campaign step", "description": "Permanently removes a step from the campaign.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "stepId", "in": "path", "required": true, "description": "Step identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Campaign step deleted. Returns `{ deleted: true }`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `id` or `stepId` is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/campaigns/{id}/enrollments": { "get": { "operationId": "campaignsListEnrollments", "summary": "List enrollments for a campaign", "description": "Returns enrollments for the specified campaign, optionally filtered by `status`. Supports pagination via `limit`/`offset`.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by enrollment status.", "schema": { "type": "string", "enum": [ "active", "completed", "paused", "cancelled", "failed" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Max records to return (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset for pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Enrollment list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "enrollments": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_CampaignEnrollment" } }, "total_count": { "type": "integer" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `id` is not a valid UUID; or `VALIDATION_ERROR` — query params are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "campaignsEnrollUser", "summary": "Enroll a user in a campaign", "description": "Enrolls a target user in the campaign. Requires the `campaign.enroll` permission.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_CampaignEnrollmentRequest" } } } }, "responses": { "201": { "description": "User enrolled in campaign.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Enrollment record." } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `campaign.enroll` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/automation-rules": { "get": { "operationId": "automationRulesList", "summary": "List automation rules", "description": "Returns automation rules for the authenticated organization. Supports optional filters: `is_enabled` (`true`/`false`), `trigger_type`, `action_type`, `page`, `page_size` (max 200).", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "is_enabled", "in": "query", "required": false, "description": "Filter by enabled state.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "trigger_type", "in": "query", "required": false, "description": "Filter by trigger type string.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "action_type", "in": "query", "required": false, "description": "Filter by action type string.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Results per page (max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Automation rule list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_AutomationRule" } }, "total_count": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "automationRulesCreate", "summary": "Create an automation rule", "description": "Creates an automation rule. For `webhook` action types `action_config.url` must use HTTPS and `action_config.method` must be present. For `run_ai_session` action types `action_config.prompt` must be a non-empty string. For `cron` trigger types `trigger_config.expression` must be a valid 5-field cron expression.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_AutomationRuleCreateRequest" } } } }, "responses": { "201": { "description": "Automation rule created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_AutomationRule" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — a rule with the same name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/automation-rules/{ruleId}": { "get": { "operationId": "automationRulesGet", "summary": "Get an automation rule", "description": "Returns a single automation rule by ID.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "description": "Automation rule identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Automation rule record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_AutomationRule" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "automationRulesUpdate", "summary": "Update an automation rule", "description": "Updates an automation rule. All fields are optional; same validation rules as create apply to `action_config` and `trigger_config`.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "description": "Automation rule identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_AutomationRuleUpdateRequest" } } } }, "responses": { "200": { "description": "Automation rule updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_AutomationRule" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`CONFLICT` — another rule with the same name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "automationRulesDelete", "summary": "Delete an automation rule", "description": "Permanently deletes an automation rule.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "description": "Automation rule identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Automation rule deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/automation-rules/{ruleId}/executions": { "get": { "operationId": "automationRulesListExecutions", "summary": "List executions for an automation rule", "description": "Returns execution history for the specified automation rule. Supports optional `status` filter and `page`/`page_size` pagination.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "description": "Automation rule identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by execution status (up to 50 characters).", "schema": { "type": "string", "maxLength": 50 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based, max 100,000).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "page_size", "in": "query", "required": false, "description": "Results per page (1–200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Rule execution history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT` — `ruleId` is not a valid UUID; or `VALIDATION_ERROR` — query params are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/automation-rules/{ruleId}/execute": { "post": { "operationId": "automationRulesExecute", "summary": "Manually execute an automation rule", "description": "Enqueues an immediate execution of the rule. The rule must belong to the caller's organization (cross-tenant IDOR prevention is enforced). Requires the `automation.manage` permission.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "description": "Automation rule identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rule execution enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `automation.manage` permission, or the rule does not belong to the caller's organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/time-triggers": { "get": { "operationId": "timeTriggersList", "summary": "List time triggers", "description": "Returns time-based automation triggers for the authenticated organization.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Results per page (max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Time trigger list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_TimeTrigger" } }, "total_count": { "type": "integer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "timeTriggersCreate", "summary": "Create a time trigger", "description": "Creates a cron-based time trigger. The `cron_expression` must be a valid 5-field cron expression (minute hour day-of-month month day-of-week).", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_TimeTriggerCreateRequest" } } } }, "responses": { "201": { "description": "Time trigger created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_TimeTrigger" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/time-triggers/{id}": { "put": { "operationId": "timeTriggersUpdate", "summary": "Update a time trigger", "description": "Updates a time trigger. All fields are optional.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Time trigger identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_TimeTriggerUpdateRequest" } } } }, "responses": { "200": { "description": "Time trigger updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_TimeTrigger" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "timeTriggersDelete", "summary": "Delete a time trigger", "description": "Permanently deletes a time trigger.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Time trigger identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Time trigger deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/time-triggers/{id}/logs": { "get": { "operationId": "timeTriggersGetLogs", "summary": "Get time trigger execution log", "description": "Returns execution logs for the specified time trigger with optional `status` filter and pagination.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Time trigger identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by execution status (max 50 chars).", "schema": { "type": "string", "maxLength": 50 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Results per page (max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Trigger execution log.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total_count": { "type": "integer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/workflows": { "get": { "operationId": "workflowsList", "summary": "List approval workflows", "description": "Returns approval workflows for the authenticated organization. When called via the `/v1/org/{orgId}/workflows` or `/v1/organizations/{orgId}/workflows` alias paths, `data` is a plain array rather than the paginated `{workflows, total_count}` object.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by workflow status.", "schema": { "type": "string", "enum": [ "active", "draft", "archived" ] } }, { "name": "trigger_type", "in": "query", "required": false, "description": "Filter by trigger type.", "schema": { "type": "string", "enum": [ "manual", "event", "schedule", "webhook", "condition" ] } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search (max 200 chars).", "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Workflow list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_ApprovalWorkflow" } }, "total_count": { "type": "integer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "workflowsCreate", "summary": "Create an approval workflow", "description": "Creates a new approval workflow with up to 100 steps (each step defines a state transition and the role required to execute it).", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_WorkflowCreateRequest" } } } }, "responses": { "201": { "description": "Workflow created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_ApprovalWorkflow" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/workflows/states": { "get": { "operationId": "workflowsListStates", "summary": "List workflow states", "description": "Returns all workflow states for the authenticated organization.", "tags": [ "Releases & Automation" ], "responses": { "200": { "description": "Workflow state list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_WorkflowState" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "workflowsCreateState", "summary": "Create a workflow state", "description": "Creates a new workflow state. `color` must be a valid 7-char hex color (e.g. `#4CAF50`). `position` is 0-based display order.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_WorkflowStateCreateRequest" } } } }, "responses": { "201": { "description": "Workflow state created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_WorkflowState" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/workflows/{workflowId}": { "get": { "operationId": "workflowsGet", "summary": "Get an approval workflow", "description": "Returns a single approval workflow including its steps.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "Workflow identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workflow record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_ApprovalWorkflow" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "workflowsUpdate", "summary": "Update an approval workflow", "description": "Updates workflow metadata. At least one non-`changelog` field must be provided. `changelog` alone is insufficient and returns 400.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "Workflow identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_WorkflowUpdateRequest" } } } }, "responses": { "200": { "description": "Workflow updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_ApprovalWorkflow" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "workflowsDelete", "summary": "Delete an approval workflow", "description": "Permanently deletes an approval workflow.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "Workflow identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workflow deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/workflows/{workflowId}/steps": { "post": { "operationId": "workflowsAddStep", "summary": "Add a step to a workflow", "description": "Adds a state-transition step to the workflow. Each step defines `from_state_id`, `to_state_id`, and the `required_role` that can execute the transition.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "Workflow identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_WorkflowStepCreateRequest" } } } }, "responses": { "201": { "description": "Workflow step added.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_WorkflowStep" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/workflows/{workflowId}/steps/{stepId}": { "put": { "operationId": "workflowsUpdateStep", "summary": "Update a workflow step", "description": "Updates a workflow step. At least one non-`changelog` field must be provided.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "Workflow identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "stepId", "in": "path", "required": true, "description": "Step identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_WorkflowStepUpdateRequest" } } } }, "responses": { "200": { "description": "Workflow step updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_WorkflowStep" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "workflowsDeleteStep", "summary": "Delete a workflow step", "description": "Removes a state-transition step from the workflow.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "Workflow identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "stepId", "in": "path", "required": true, "description": "Step identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workflow step deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/change-mgmt/changesets": { "get": { "operationId": "changeMgmtListChangesets", "summary": "List changesets", "description": "Returns changesets for the authenticated organization. Supports optional filters: `project_id`, `status`, `changeset_type`, `search`.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Filter by project identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by changeset status.", "schema": { "type": "string", "enum": [ "draft", "submitted", "in_review", "approved", "rejected" ] } }, { "name": "changeset_type", "in": "query", "required": false, "description": "Filter by changeset type.", "schema": { "type": "string", "enum": [ "feature", "bugfix", "hotfix", "refactor", "config" ] } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search across title/description (max 200 chars).", "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Changeset list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "changesets": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_Changeset" } }, "total_count": { "type": "integer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "changeMgmtCreateChangeset", "summary": "Create a changeset", "description": "Creates a new changeset to group related changes before review and deployment.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_ChangesetCreateRequest" } } } }, "responses": { "201": { "description": "Changeset created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Changeset" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/change-mgmt/changesets/{id}": { "get": { "operationId": "changeMgmtGetChangeset", "summary": "Get a changeset", "description": "Returns a changeset including its individual changes.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Changeset identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Changeset record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Changeset" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "changeMgmtUpdateChangeset", "summary": "Update a changeset", "description": "Updates changeset fields. The `status` field is **not accepted here** — use the dedicated lifecycle endpoints (`/submit`, `/approve`, `/reject`, `/apply`, `/revert`). Sending `status` returns `400 VALIDATION_ERROR` with a redirect hint.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Changeset identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_ChangesetUpdateRequest" } } } }, "responses": { "200": { "description": "Changeset updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Changeset" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — field validation failed, or the request included `status` (use lifecycle endpoints instead).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/change-mgmt/changesets/{id}/changes": { "get": { "operationId": "changeMgmtListChanges", "summary": "List changes in a changeset", "description": "Returns all individual resource changes within the specified changeset.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Changeset identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Change list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_Change" } }, "total_count": { "type": "integer" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "changeMgmtAddChange", "summary": "Add a change to a changeset", "description": "Adds an individual resource change to the specified changeset. `change_type` determines the recorded operation: `create` → INSERT, `update`/`move`/`rename` → UPDATE, `delete` → DELETE.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Changeset identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_ChangeCreateRequest" } } } }, "responses": { "201": { "description": "Change added to changeset.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Releases_Change" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/change-mgmt/approvals": { "get": { "operationId": "changeMgmtListApprovals", "summary": "List change approvals", "description": "Returns approval decisions, optionally filtered by `changeset_id` and/or `decision`.", "tags": [ "Releases & Automation" ], "parameters": [ { "name": "changeset_id", "in": "query", "required": false, "description": "Filter by changeset identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "decision", "in": "query", "required": false, "description": "Filter by approval decision.", "schema": { "type": "string", "enum": [ "approve", "reject", "request_changes" ] } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Approval list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "approvals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total_count": { "type": "integer" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "changeMgmtRecordApproval", "summary": "Record a change approval decision", "description": "Records an approval, rejection, or change-request decision against a changeset.", "tags": [ "Releases & Automation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Releases_ChangeApprovalRequest" } } } }, "responses": { "201": { "description": "Approval decision recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/resolve": { "get": { "operationId": "saasPkgResolve", "summary": "Resolve a package slug or UUID", "description": "Resolve a slug (or UUID) to its canonical package identity. Authenticated callers who are members of the owning org see all packages scoped to their membership; non-members only see published packages (anti-enumeration: all not-found/non-published/cross-scope conditions collapse to 404). When the input is a UUID, RFC 8594 `Sunset`/`Deprecation` headers and a `Link: rel=alternate` pointing to the canonical slug URL are added to hint migration — the response is still HTTP 200. Rate-limited per IP (public slug lookup budget) and per authenticated session.", "tags": [ "SaaS Builder" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "query", "required": true, "description": "Package slug or UUID (max 256 characters).", "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Resolved package identity. `redirect` is a client-shell hint only — no HTTP redirect is emitted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_SlugResolveResult" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` — slug query param missing or longer than 256 chars.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — package not found, not published (for non-members), or cross-scope. All conditions return identical shape for anti-enumeration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/by/{idOrSlug}": { "get": { "operationId": "saasPkgResolveByIdOrSlug", "summary": "Resolve a package by slug or UUID (path form)", "description": "Identical resolution logic to `GET /v1/saas-packages/resolve` but accepts the identifier as a path segment rather than a query parameter. Useful for deep-link patterns. Same anti-enumeration, rate-limiting, and RFC 8594 deprecation-hint behaviour as the query-param form.", "tags": [ "SaaS Builder" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "Package slug or UUID (max 256 characters).", "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Resolved package identity.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_SlugResolveResult" } } } ] } } } }, "400": { "description": "`INVALID_PARAMETER` — identifier empty or longer than 256 chars.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`NOT_FOUND` — same anti-enumeration contract as `/resolve`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/plans/refs": { "get": { "operationId": "saasPkgPlanRefsListCrossPackage", "summary": "List cross-package pricing plan refs", "description": "Returns a picker-safe projection of every pricing plan across all packages in the caller's org (up to 500). Intended for the `requires_any_plan_ids` prerequisite multi-select in the curation UI — only `plan_id`, `plan_slug`, `plan_name`, `package_id`, `package_slug`, `package_name`, and `is_active` are returned; pricing amounts and features are never included. Requires `saas_package.curate` permission. Registered before `/:packageId` routes so the literal `plans` segment wins the Hono path match.", "tags": [ "SaaS Builder" ], "responses": { "200": { "description": "List of pricing plan refs across all packages in the org.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_PlanRef" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/pricing-plans/{planId}/rename-slug": { "post": { "operationId": "saasPkgPlanRenameSlug", "summary": "Atomically rename a pricing plan slug", "description": "Atomically rename the URL slug for a pricing plan. Direct slug edits via `PUT /:packageId/pricing-plans/:planId` are rejected by the stored procedure; this is the only supported rename path. Requires `saas_package.curate` permission. The `planId` is resolved cross-package within the caller's org. Returns `400 VALIDATION_ERROR` if the new slug is reserved or fails canonical-grammar validation server-side.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "planId", "in": "path", "required": true, "description": "Pricing plan UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_RenamePlanSlugRequest" } } } }, "responses": { "200": { "description": "Slug renamed successfully. Returns the updated pricing plan.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_PricingPlan" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — slug fails canonical-grammar or is a reserved word. `INVALID_ID_FORMAT` — planId is not a UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — pricing plan not found in caller's org.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` or `PACKAGE_SLUG_EXISTS` — slug already in use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages": { "get": { "operationId": "saasPkgList", "summary": "List SaaS packages", "description": "List all SaaS packages for the authenticated caller's organization. Supports optional full-text search and page/page_size pagination. Requires `package.view` permission. Gated behind the `saas-builder` system feature flag.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "search", "in": "query", "description": "Optional full-text search term (max 255 chars).", "schema": { "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "description": "Page number (1-based, default 1).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "description": "Page size (1–100, default varies by SP).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated list of packages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_Package" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_OffsetPagination" } } } } } }, "400": { "description": "`INVALID_PARAMETER` — invalid query parameter values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgCreate", "summary": "Create a SaaS package", "description": "Create a new SaaS package in draft status for the caller's organization. The `slug` must match the canonical package slug grammar (lowercase alphanumeric, single internal hyphens, 3–63 characters, not UUID-shaped) and is globally unique across all organizations via a reference-table registry. Returns `409 PACKAGE_SLUG_EXISTS` if the slug is already registered. Requires `package.create` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreatePackageRequest" } } } }, "responses": { "201": { "description": "Package created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Package" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — field validation failed. `INVALID_JSON` — malformed request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`PACKAGE_SLUG_EXISTS` — the requested slug is already registered globally.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}": { "get": { "operationId": "saasPkgGet", "summary": "Get a SaaS package", "description": "Retrieve a single SaaS package by UUID. Requires `package.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Package UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Package record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Package" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SAAS_PACKAGE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgUpdate", "summary": "Update a SaaS package", "description": "Update package properties. At least one field (other than `id`) must be provided. Setting `slug` to `null` clears the slug and releases the globally-registered slug registry entry. Setting `logo_url` or `favicon_url` to `null` clears those fields. Changes to `app_name`, `logo_url`, `favicon_url`, `theme_config`, `org_config`, `login_screen_config`, `plan_group_config`, `billing_interval_config`, or `subdomain` invalidate the per-package app-config KV cache. Requires `package.update` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Package UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_UpdatePackageRequest" } } } }, "responses": { "200": { "description": "Updated package record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Package" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`PACKAGE_SLUG_EXISTS` — the new slug is already globally registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "saasPkgCurationUpdate", "summary": "Curation-only update for a SaaS package", "description": "Update signup roll-up curation fields only. Intentionally distinct from `PUT /:packageId` so operators with `saas_package.curate` can manage the signup roll-up card without holding the broader `package.update` permission. The strict schema rejects all non-curation keys so a leaked curate token cannot piggyback a price or theme edit. `signup_card_config.icon_url` must be HTTPS and hosted on the Backbuild CDN allowlist.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Package UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_PackageCurationPatchRequest" } } } }, "responses": { "200": { "description": "Curation fields updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Package" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgDelete", "summary": "Delete a SaaS package", "description": "Soft-delete (archive) a SaaS package. Requires `package.delete` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Package UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`deleted: true`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`SAAS_PACKAGE_HAS_SUBSCRIBERS` — cannot delete while active subscriber tenants exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/publish": { "post": { "operationId": "saasPkgPublish", "summary": "Publish a SaaS package", "description": "Transition a package from `draft` to `published`. The package must meet all SP-enforced preconditions (e.g. at least one active pricing plan); unmet conditions return `409 CONFLICT`. Requires `package.publish` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Package UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Package published.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Package" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — publish precondition unmet (e.g. no active pricing plan). `SAAS_PACKAGE_NOT_PUBLISHABLE` — package state does not allow publishing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/unpublish": { "post": { "operationId": "saasPkgUnpublish", "summary": "Unpublish / suspend a SaaS package", "description": "Transition a published package to `suspended`, preventing new subscriber sign-ups while retaining existing subscribers. Requires `package.publish` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Package UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Package suspended.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Package" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/clone": { "post": { "operationId": "saasPkgClone", "summary": "Deep-clone a SaaS package", "description": "Create a deep copy of an existing package into a new draft. The clone inherits all pricing plans, screen definitions, marketing pages, seed data, connectors, and app configs from the source. The source package must belong to the caller's org. Requires `package.create` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Source package UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_ClonePackageRequest" } } } }, "responses": { "201": { "description": "Cloned package (new draft).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Package" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SAAS_PACKAGE_NOT_FOUND` — source package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/archive": { "post": { "operationId": "saasPkgArchive", "summary": "Archive a suspended package", "description": "Permanently archive a suspended (unpublished) package. The package must first be suspended via `POST /unpublish`. Requires `package.publish` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Package UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Package archived.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Package" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — precondition unmet (package must be suspended first).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/signup-card-events": { "get": { "operationId": "saasPkgSignupCardEventsList", "summary": "List signup card dropped events", "description": "Returns the most recent signup-card-dropped audit events for a package (default limit 10, max 50). Powers the curation UI warning banner. Requires `saas_package.curate` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Package UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Maximum events to return (1–50, default 10).", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Signup card events.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/pricing-plans": { "get": { "operationId": "saasPkgPricingPlanList", "summary": "List pricing plans for a package", "description": "List pricing plans belonging to a package with optional active/inactive filter and limit/offset pagination. Requires `saas_pricing.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by status: `active` or `inactive`. Omit for all.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Paginated pricing plans.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_PricingPlan" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_OffsetPagination" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgPricingPlanCreate", "summary": "Create a pricing plan", "description": "Create a new pricing plan for the package. `plan_type` defaults to `recurring`; recurring plans require a `billing_interval`; free plans must have `price_cents: 0`. `plan_tier` is required and must be one of the platform canonical tiers. `category` is a builder-defined group key validated by the SP against the package's `plan_group_config`. Per-timeframe `prices` rows may be provided in addition to the legacy `price_cents`/`price_cents_yearly` fields. Requires `saas_pricing.create`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreatePricingPlanRequest" } } } }, "responses": { "201": { "description": "Pricing plan created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_PricingPlan" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/pricing-plans/sync": { "post": { "operationId": "saasPkgPricingPlanSync", "summary": "Mark pricing plans as pending Stripe sync", "description": "Mark one or all active pricing plans in the package as pending Stripe sync for the given deployment environment. An optional `plan_id` restricts the marking to a single plan. The actual Stripe synchronization is performed by a background worker; this endpoint only updates the sync-pending state. Requires `saas_pricing.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_SyncPricingPlansRequest" } } } }, "responses": { "200": { "description": "Plans marked as pending sync.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/pricing-plans/{planId}": { "get": { "operationId": "saasPkgPricingPlanGet", "summary": "Get a pricing plan", "description": "Retrieve a single pricing plan. Returns `404` if the plan does not belong to the specified package. Requires `saas_pricing.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pricing plan.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_PricingPlan" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgPricingPlanUpdate", "summary": "Update a pricing plan", "description": "Update pricing plan fields. At least one field (other than `id`) must be provided. Returns `404` if the plan does not belong to the specified package. Requires `saas_pricing.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_UpdatePricingPlanRequest" } } } }, "responses": { "200": { "description": "Updated pricing plan.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_PricingPlan" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgPricingPlanDelete", "summary": "Delete a pricing plan", "description": "Delete a pricing plan. Returns `409` if the plan has active subscribers. Returns `404` if the plan does not belong to the specified package. Requires `saas_pricing.delete`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`deleted: true`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`PRICING_PLAN_HAS_SUBSCRIBERS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/pricing-plans/{planId}/curation": { "patch": { "operationId": "saasPkgPricingPlanCurationUpdate", "summary": "Curation-only update for a pricing plan", "description": "Update signup-eligibility curation fields on a pricing plan. Distinct from `PUT` so operators with `saas_package.curate` can manage sign-up visibility without holding the broader `saas_pricing.update` permission. The strict schema rejects non-curation keys. Returns `404` if the plan does not belong to the specified package. Requires `saas_package.curate`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_PricingPlanCurationPatchRequest" } } } }, "responses": { "200": { "description": "Updated pricing plan.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_PricingPlan" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/promotions": { "get": { "operationId": "saasPkgPromotionList", "summary": "List promotions for a package", "description": "List promotions with optional active filter and page/page_size pagination. Requires `saas_pricing.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "is_active", "in": "query", "description": "Filter by active status.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Paginated promotions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_Promotion" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `VALIDATION_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgPromotionCreate", "summary": "Create a promotion", "description": "Create a discount promotion for the package. `discount_type` is `percentage` or `fixed_amount`; `currency` is a 3-letter lowercase ISO 4217 code (default `usd`). `stripe_duration` controls Stripe coupon duration. Requires `saas_pricing.create`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreatePromotionRequest" } } } }, "responses": { "201": { "description": "Promotion created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Promotion" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/promotions/sync": { "post": { "operationId": "saasPkgPromotionSync", "summary": "Trigger Stripe sync for promotions", "description": "Mark all active promotions in the package as pending Stripe sync for the given environment, then run the sync. Returns `503 SERVICE_UNAVAILABLE` if Stripe is not configured for this deployment. Requires `saas_pricing.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_SyncPromotionsRequest" } } } }, "responses": { "200": { "description": "Promotions sync result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "environment": { "type": "string" }, "marked": { "type": "integer", "description": "Number of promotions marked as pending sync." }, "total": { "type": "integer", "description": "Total promotions processed by the sync worker." }, "synced": { "type": "integer", "description": "Number successfully synced to Stripe." }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "environment", "marked", "total", "synced" ], "additionalProperties": false } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — Stripe is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/saas-packages/{packageId}/promotions/{promotionId}": { "get": { "operationId": "saasPkgPromotionGet", "summary": "Get a promotion", "description": "Retrieve a single promotion by ID. Requires `saas_pricing.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Promotion.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Promotion" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgPromotionUpdate", "summary": "Update a promotion", "description": "Update promotion fields. At least one field (other than `id`) must be provided. Requires `saas_pricing.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_UpdatePromotionRequest" } } } }, "responses": { "200": { "description": "Updated promotion.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_Promotion" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgPromotionDelete", "summary": "Soft-delete a promotion", "description": "Soft-delete (deactivate) a promotion. Requires `saas_pricing.delete`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`deleted: true`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/domains": { "get": { "operationId": "saasPkgDomainList", "summary": "List custom domains", "description": "List custom domains for the package. Supports optional `status` filter and limit/offset pagination. Requires `custom_domain.view`. The path `/v1/saas-packages/{packageId}/custom-domains` is a deprecated alias with identical behaviour.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by domain status.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Custom domains.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_CustomDomain" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_OffsetPagination" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgDomainCreate", "summary": "Create a custom domain", "description": "Add a custom domain to the package. `domain_type` defaults to `alias`. `environment` defaults to `production`. `api_base_url` must be HTTPS; defaults to the standard Backbuild API URL for the chosen environment. Returns `409 DOMAIN_ALREADY_EXISTS` on duplicate. Requires `custom_domain.create`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreateDomainRequest" } } } }, "responses": { "201": { "description": "Domain created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_CustomDomain" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`DOMAIN_ALREADY_EXISTS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/domains/{domainId}": { "get": { "operationId": "saasPkgDomainGet", "summary": "Get a custom domain", "description": "Retrieve a custom domain by ID. Returns `404` if the domain does not belong to the specified package. Requires `custom_domain.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Custom domain.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_CustomDomain" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgDomainDelete", "summary": "Delete a custom domain", "description": "Remove a custom domain. Returns `404` if the domain does not belong to the specified package. Requires `custom_domain.delete`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted domain record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_CustomDomain" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/domains/{domainId}/verify": { "post": { "operationId": "saasPkgDomainVerify", "summary": "Verify custom domain DNS", "description": "Trigger a DNS verification check for the domain. The SP validates the expected TXT or CNAME record in DNS and updates `verification_status`. Returns `409 DOMAIN_VERIFICATION_FAILED` if DNS has not propagated. Requires `custom_domain.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain with updated verification status.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_CustomDomain" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`DOMAIN_VERIFICATION_FAILED` — DNS not yet propagated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/marketing-pages": { "get": { "operationId": "saasPkgMarketingPageList", "summary": "List marketing pages", "description": "List marketing pages for the package with optional status filter and limit/offset pagination. Requires `marketing_page.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by page status.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Marketing pages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_MarketingPage" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_OffsetPagination" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgMarketingPageCreate", "summary": "Create a marketing page", "description": "Create a marketing page for the package. `og_image_url` must be HTTPS. Requires `marketing_page.create`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreateMarketingPageRequest" } } } }, "responses": { "201": { "description": "Marketing page created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_MarketingPage" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/marketing-pages/{pageId}": { "get": { "operationId": "saasPkgMarketingPageGet", "summary": "Get a marketing page", "description": "Retrieve a marketing page by ID. Requires `marketing_page.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Marketing page.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_MarketingPage" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgMarketingPageUpdate", "summary": "Update a marketing page", "description": "Update marketing page fields. At least one field (other than `id`) must be provided. Requires `marketing_page.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_UpdateMarketingPageRequest" } } } }, "responses": { "200": { "description": "Updated marketing page.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_MarketingPage" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`MARKETING_PAGE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgMarketingPageDelete", "summary": "Delete a marketing page", "description": "Delete a marketing page. Requires `marketing_page.delete`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`deleted: true`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`MARKETING_PAGE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/marketing-pages/{pageId}/publish": { "post": { "operationId": "saasPkgMarketingPagePublish", "summary": "Publish a marketing page", "description": "Transition a marketing page to `published` status. Requires `marketing_page.publish`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Marketing page published.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_MarketingPage" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`MARKETING_PAGE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/seed-data": { "get": { "operationId": "saasPkgSeedDataList", "summary": "List seed data entries", "description": "List seed data for the package with optional limit/offset pagination. Requires `seed_data.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Seed data entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_SeedData" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_OffsetPagination" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgSeedDataCreate", "summary": "Create a seed data entry", "description": "Create a seed data record. `entity_type` is a free-form type discriminator (max 128 chars). `data` is the JSON payload. Requires `seed_data.create`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreateSeedDataRequest" } } } }, "responses": { "201": { "description": "Seed data created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_SeedData" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/seed-data/{seedId}": { "get": { "operationId": "saasPkgSeedDataGet", "summary": "Get a seed data entry", "description": "Retrieve a seed data entry by ID. Requires `seed_data.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "seedId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Seed data entry.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_SeedData" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SEED_DATA_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgSeedDataUpdate", "summary": "Update a seed data entry", "description": "Update seed data fields. At least one field (other than `id`) must be provided. Requires `seed_data.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "seedId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_UpdateSeedDataRequest" } } } }, "responses": { "200": { "description": "Updated seed data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_SeedData" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SEED_DATA_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgSeedDataDelete", "summary": "Delete a seed data entry", "description": "Delete a seed data entry. Requires `seed_data.delete`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "seedId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`deleted: true`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SEED_DATA_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/connectors": { "get": { "operationId": "saasPkgConnectorList", "summary": "List connector configs", "description": "List connector configs for the package with optional limit/offset pagination. Requires `connector_config.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Connector configs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_ConnectorConfig" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_OffsetPagination" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgConnectorCreate", "summary": "Create a connector config", "description": "Create a connector configuration for the package. Requires `connector_config.create`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreateConnectorRequest" } } } }, "responses": { "201": { "description": "Connector created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_ConnectorConfig" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/connectors/{connectorId}": { "get": { "operationId": "saasPkgConnectorGet", "summary": "Get a connector config", "description": "Retrieve a connector config by ID. Requires `connector_config.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Connector config.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_ConnectorConfig" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`CONNECTOR_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgConnectorUpdate", "summary": "Update a connector config", "description": "Update connector config fields. At least one field (other than `id`) must be provided. Requires `connector_config.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_UpdateConnectorRequest" } } } }, "responses": { "200": { "description": "Updated connector config.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_ConnectorConfig" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`CONNECTOR_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgConnectorDelete", "summary": "Delete a connector config", "description": "Delete a connector config. Requires `connector_config.delete`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`deleted: true`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`CONNECTOR_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/screen-definitions": { "get": { "operationId": "saasPkgScreenDefList", "summary": "List screen definitions", "description": "List screen definitions for the package with optional `screen_type` / `is_active` filter and limit/offset pagination. Requires `screen_definition.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "screen_type", "in": "query", "description": "Filter by screen type.", "schema": { "type": "string", "enum": [ "core", "custom", "view_based" ] } }, { "name": "is_active", "in": "query", "description": "Filter by active status.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Screen definitions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_ScreenDefinition" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_OffsetPagination" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgScreenDefCreate", "summary": "Create a screen definition", "description": "Create a screen definition. `screen_key` must be alphanumeric with dots, underscores, or hyphens (max 200 chars). Returns `409 SCREEN_KEY_EXISTS` if the key is already used in the package. Requires `screen_definition.create`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreateScreenDefinitionRequest" } } } }, "responses": { "201": { "description": "Screen definition created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_ScreenDefinition" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`SCREEN_KEY_EXISTS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/screen-definitions/{screenDefId}": { "get": { "operationId": "saasPkgScreenDefGet", "summary": "Get a screen definition", "description": "Retrieve a screen definition by ID. Requires `screen_definition.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "screenDefId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Screen definition.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_ScreenDefinition" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SCREEN_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgScreenDefUpdate", "summary": "Update a screen definition", "description": "Update screen definition fields. At least one field (other than `id`) must be provided. `changelog` records a freeform description of what changed (max 4096 chars). Requires `screen_definition.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "screenDefId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_UpdateScreenDefinitionRequest" } } } }, "responses": { "200": { "description": "Updated screen definition.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_ScreenDefinition" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SCREEN_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`SCREEN_KEY_EXISTS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgScreenDefDelete", "summary": "Delete a screen definition", "description": "Delete a screen definition. Requires `screen_definition.delete`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "screenDefId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`deleted: true`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SCREEN_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/app-configs": { "get": { "operationId": "saasPkgAppConfigList", "summary": "List app configs", "description": "List app configs for the package with optional `platform` filter and page/page_size pagination. Requires `app_config.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "description": "Filter by platform.", "schema": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux", "web" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "App configs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_AppConfig" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_PagePagination" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgAppConfigCreate", "summary": "Create an app config", "description": "Create a platform-specific app config. Only one config per `platform` per package is allowed (`APP_CONFIG_DUPLICATE_PLATFORM`). `splash_background_color` must be a hex color like `#FFFFFF`. Requires `app_config.create`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreateAppConfigRequest" } } } }, "responses": { "201": { "description": "App config created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_AppConfig" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`APP_CONFIG_DUPLICATE_PLATFORM`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/app-configs/{configId}": { "get": { "operationId": "saasPkgAppConfigGet", "summary": "Get an app config", "description": "Retrieve an app config by ID. Requires `app_config.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "configId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "App config.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_AppConfig" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`APP_CONFIG_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgAppConfigUpdate", "summary": "Update an app config", "description": "Update app config fields. `platform` is immutable after creation. At least one field (other than `id`) must be provided. `null` values clear optional URL/ref fields. Requires `app_config.update`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "configId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_UpdateAppConfigRequest" } } } }, "responses": { "200": { "description": "Updated app config.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_AppConfig" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`APP_CONFIG_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgAppConfigDelete", "summary": "Delete an app config", "description": "Delete an app config. Requires `app_config.delete`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "configId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`deleted: true`", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`APP_CONFIG_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/data-bundles": { "get": { "operationId": "saasPkgDataBundleList", "summary": "List data bundles", "description": "List data bundles for the package with limit/offset pagination (max 200 per page). Requires `data_bundle.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "$ref": "#/components/parameters/OffsetQuery" } ], "responses": { "200": { "description": "Data bundles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_DataBundle" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_OffsetPagination" } } } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgDataBundleCreate", "summary": "Create a data bundle", "description": "Create a data bundle (snapshot of package config/seed data for distribution). `bundle_hash` is a content-addressed hash. Requires `data_bundle.create`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreateDataBundleRequest" } } } }, "responses": { "201": { "description": "Data bundle created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_DataBundle" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/data-bundles/current": { "get": { "operationId": "saasPkgDataBundleGetCurrent", "summary": "Get the current (published) data bundle", "description": "Retrieve the currently published data bundle. Returns `404 NO_CURRENT_BUNDLE` if no bundle has been published. Registered before `/:bundleId` so the literal `current` segment wins. Requires `data_bundle.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current data bundle.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_DataBundle" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NO_CURRENT_BUNDLE` — no bundle has been published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/data-bundles/{bundleId}": { "get": { "operationId": "saasPkgDataBundleGet", "summary": "Get a data bundle", "description": "Retrieve a data bundle by UUID. Requires `data_bundle.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bundleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Data bundle.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_DataBundle" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`DATA_BUNDLE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/data-bundles/{bundleId}/publish": { "post": { "operationId": "saasPkgDataBundlePublish", "summary": "Publish a data bundle", "description": "Mark a data bundle as the current live bundle. Requires `data_bundle.publish`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bundleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Published data bundle.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_DataBundle" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`DATA_BUNDLE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/data-bundles/{bundleId}/rollback": { "post": { "operationId": "saasPkgDataBundleRollback", "summary": "Rollback to a data bundle", "description": "Re-publish a previous data bundle, making it the current live bundle. Requires `data_bundle.publish`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bundleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rolled-back data bundle.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_DataBundle" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`DATA_BUNDLE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/revenue/summary": { "get": { "operationId": "saasPkgRevenueSummary", "summary": "Revenue summary (MRR, ARR, churn)", "description": "Retrieve revenue analytics summary including MRR, ARR, and churn metrics for the package. Requires `billing.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revenue summary.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_RevenueSummary" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/revenue/timeseries": { "get": { "operationId": "saasPkgRevenueTimeseries", "summary": "Revenue timeseries", "description": "Retrieve revenue timeseries data by `interval` (`day`, `week`, or `month`) over `periods` data points (1–365). Requires `billing.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "interval", "in": "query", "description": "Aggregation interval.", "schema": { "type": "string", "enum": [ "day", "week", "month" ] } }, { "name": "periods", "in": "query", "description": "Number of periods (1–365).", "schema": { "type": "integer", "minimum": 1, "maximum": 365 } } ], "responses": { "200": { "description": "Timeseries data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_RevenueTimeseries" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`, `INVALID_PARAMETER`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/revenue/by-plan": { "get": { "operationId": "saasPkgRevenueByPlan", "summary": "Revenue breakdown by pricing plan", "description": "Retrieve revenue breakdown segmented by pricing plan. Requires `billing.view`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revenue by plan.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_RevenueByPlan" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/feature-flags": { "get": { "operationId": "saasPkgFeatureFlagList", "summary": "List custom feature flags for a package", "description": "List all custom feature flags defined for the package. Authorization is enforced entirely by the stored procedure. All routes in the feature-flags module require `bearerAuth` via the inherited `authMiddleware`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Feature flags.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_FeatureFlag" } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPkgFeatureFlagCreate", "summary": "Create a custom feature flag", "description": "Create a custom feature flag for the package. `slug` must be lowercase alphanumeric with hyphens. Returns `409 CONFLICT` if the slug is already used. Authorization is SP-enforced.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_CreateFeatureFlagRequest" } } } }, "responses": { "201": { "description": "Feature flag created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_FeatureFlag" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — slug already in use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/feature-flags/{flagId}": { "get": { "operationId": "saasPkgFeatureFlagGet", "summary": "Get a custom feature flag", "description": "Retrieve a custom feature flag by ID.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "flagId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Feature flag.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_FeatureFlag" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgFeatureFlagUpdate", "summary": "Update a custom feature flag", "description": "Update a custom feature flag. At least one field must be provided.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "flagId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_UpdateFeatureFlagRequest" } } } }, "responses": { "200": { "description": "Updated feature flag.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_FeatureFlag" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPkgFeatureFlagDelete", "summary": "Delete a custom feature flag", "description": "Delete a custom feature flag from the package.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "flagId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/system-feature-flags": { "get": { "operationId": "saasPkgSystemFeatureFlagsGet", "summary": "Get system feature flag assignments for a package", "description": "Retrieve the system-level feature flag assignments for the package.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "System feature flag assignments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgSystemFeatureFlagsUpdate", "summary": "Update system feature flag assignments for a package", "description": "Batch-update the system-level feature flag assignments for the package. Each entry targets a system flag by `feature_flag_id` UUID.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_SystemAssignmentsRequest" } } } }, "responses": { "200": { "description": "Updated system assignments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/pricing-plans/{planId}/feature-flags": { "get": { "operationId": "saasPkgPlanFeatureFlagsGet", "summary": "Get feature flag assignments for a pricing plan", "description": "Retrieve the feature flag assignments (both system and custom) for a specific pricing plan.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Plan feature flag assignments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgPlanFeatureFlagsUpdate", "summary": "Update feature flag assignments for a pricing plan", "description": "Batch-update feature flag assignments for a pricing plan. Each entry specifies `flag_source` (`system` or `custom`) and `feature_flag_id`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_ScopedAssignmentsRequest" } } } }, "responses": { "200": { "description": "Updated plan feature flag assignments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/tenants/{tenantOrgId}/feature-flags": { "get": { "operationId": "saasPkgTenantFeatureFlagsGet", "summary": "Get tenant feature flag overrides", "description": "Retrieve the feature flag overrides set for a specific subscriber tenant organization.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenantOrgId", "in": "path", "required": true, "description": "Tenant organization UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tenant feature flag overrides.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgTenantFeatureFlagsUpdate", "summary": "Update tenant feature flag overrides", "description": "Batch-update feature flag overrides for a specific subscriber tenant. Each entry specifies `flag_source` and `feature_flag_id`.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenantOrgId", "in": "path", "required": true, "description": "Tenant organization UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_ScopedAssignmentsRequest" } } } }, "responses": { "200": { "description": "Updated tenant feature flag overrides.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/tenants/{tenantOrgId}/feature-flags/effective": { "get": { "operationId": "saasPkgTenantFeatureFlagsEffective", "summary": "Get effective feature flags for a tenant", "description": "Retrieve the computed (merged) effective feature flag state for a subscriber tenant, combining package defaults, plan-level overrides, and tenant-specific overrides. Registered before `/:tenantOrgId/feature-flags` so `effective` wins the path match.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenantOrgId", "in": "path", "required": true, "description": "Tenant organization UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Effective feature flag state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/ai-models": { "get": { "operationId": "saasPkgAiModelList", "summary": "List AI models available to a package", "description": "Returns a model-centric list of AI models with their package-level enable/disable override state. Each entry includes the model's display name, model string, whether it is a system model or an org-owned model, and whether it is enabled for this package. Supports `page`/`page_size` pagination (default 50, max 200). Authorization is SP-enforced.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "AI model list for the package.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_AiModelOverride" } }, "pagination": { "$ref": "#/components/schemas/SaasPkg_PagePagination" } }, "required": [ "models", "pagination" ], "additionalProperties": false } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgAiModelBatchOverride", "summary": "Batch-update AI model overrides for a package", "description": "Batch-upsert package-level enable/disable overrides for AI models. Each entry must specify exactly one of `system_model_id` or `org_model_id` and a boolean `is_enabled`. Array must contain 1–200 items.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_AiModelBatchOverrideRequest" } } } }, "responses": { "200": { "description": "Overrides applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-packages/{packageId}/ai-models/override": { "post": { "operationId": "saasPkgAiModelOverrideUpsert", "summary": "Upsert a single AI model override for a package", "description": "Create or update the package-level enable/disable override for a single AI model. Exactly one of `system_model_id` or `org_model_id` must be provided. `PUT /ai-models/override` on the same path is a verb alias for this operation.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_AiModelUpsertRequest" } } } }, "responses": { "200": { "description": "Override upserted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPkgAiModelOverrideUpsertPut", "summary": "Upsert a single AI model override for a package (PUT alias)", "description": "Identical to `POST /ai-models/override`. Both HTTP verbs map to the same upsert handler.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_AiModelUpsertRequest" } } } }, "responses": { "200": { "description": "Override upserted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_ID_FORMAT`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas/integrations": { "get": { "operationId": "saasPkgIntegrationList", "summary": "List configured SaaS integrations for an org", "description": "List the integrations configured for the calling user's organization. Requires an authenticated session (`bearerAuth`). Authorization is verified inline: unauthenticated requests receive `401 AUTH_REQUIRED`. Secret values are never returned — config objects strip `_secret_ref` fields. Supports `limit`/`offset` pagination (default `limit` 20, max 100; default `offset` 0).", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Integration list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_Integration" } }, "total": { "type": "integer", "description": "Total number of integrations for this org." } }, "required": [ "integrations", "total" ], "additionalProperties": false } } } ] } } } }, "401": { "description": "`AUTH_REQUIRED` — session not present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas/integrations/configure": { "post": { "operationId": "saasPkgIntegrationConfigure", "summary": "Configure a SaaS integration provider", "description": "Create or replace the configuration for a third-party integration provider. Requires `integration.create` permission. Secret values are encrypted at rest; they are never returned in subsequent reads. Returns `503 SERVICE_UNAVAILABLE` if the encryption service is not available.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPkg_ConfigureIntegrationRequest" } } } }, "responses": { "201": { "description": "Integration configured.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "integration": { "$ref": "#/components/schemas/SaasPkg_Integration" } }, "required": [ "integration" ], "additionalProperties": false } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR`, `INVALID_JSON`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — encryption service is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/saas/integrations/{integrationId}": { "delete": { "operationId": "saasPkgIntegrationDelete", "summary": "Delete a SaaS integration", "description": "Delete an integration and clean up its encrypted secrets. Requires `integration.delete` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Integration deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "deleted", "id" ], "additionalProperties": false } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas/integrations/{integrationId}/test": { "post": { "operationId": "saasPkgIntegrationTest", "summary": "Test a SaaS integration connection", "description": "Test the live connectivity of a configured integration by exercising a provider-specific connectivity probe. Requires `integration.view` permission. Returns `503 SERVICE_UNAVAILABLE` if the encryption service is not available.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Test result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPkg_IntegrationTestResult" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — encryption service is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/saas/customer/paused-subscriptions": { "get": { "operationId": "saasPlatformListPausedSubscriptions", "summary": "List paused customer subscriptions", "description": "Returns the calling organization's SaaS subscriptions that are currently paused because the seller's payment account has been disabled. Used to render a 'Payments temporarily unavailable' banner in the subscriber UI. Returns an empty list when no subscriptions are paused. The organization is derived from the authenticated session — no org_id parameter is accepted. NOTE: this route is declared in saas-customer.ts and documented at its declared path /v1/saas/customer/paused-subscriptions; verify against the active router mount when consuming.", "tags": [ "SaaS Builder" ], "responses": { "200": { "description": "List of paused subscriptions for the caller's organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "subscriptions", "total" ], "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_PausedSubscription" } }, "total": { "type": "integer", "description": "Total count of paused subscriptions." } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller is not a member of the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-tenants": { "post": { "operationId": "saasPlatformProvisionTenant", "summary": "Provision a new tenant", "description": "Creates a new tenant (end-customer environment) for a published SaaS package owned by the caller's organization. Requires the `saas_tenant.provision` permission. The package must be published and owned by the caller's org.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_TenantProvisionRequest" } } } }, "responses": { "201": { "description": "Tenant provisioned. The provision record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_TenantProvision" } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `VALIDATION_ERROR` (field validation failure or the referenced package is not valid for this operation).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `saas_tenant.provision` permission or does not own the package.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the referenced SaaS package or admin user does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a tenant with this slug already exists (`TENANT_SLUG_EXISTS`) or the tenant is already provisioned (`TENANT_ALREADY_PROVISIONED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListTenantProvisions", "summary": "List tenant provisions", "description": "Returns a paginated list of tenant provisions for packages owned by the caller's organization. Requires the `saas_tenant.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": false, "description": "Filter by SaaS package (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by provision status (e.g. `active`, `deprovisioned`).", "schema": { "type": "string", "maxLength": 64 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of tenant provisions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_TenantProvision" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-tenants/{provisionId}": { "get": { "operationId": "saasPlatformGetTenantProvision", "summary": "Get tenant provision", "description": "Returns a single tenant provision record by id. Requires `saas_tenant.view` permission. A provision outside the caller's org scope is reported as 404.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "provisionId", "in": "path", "required": true, "description": "Tenant provision identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The tenant provision record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_TenantProvision" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — provisionId is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-tenants/{provisionId}/deprovision": { "post": { "operationId": "saasPlatformDeprovisionTenant", "summary": "Deprovision a tenant", "description": "Deprovisions an active tenant, removing access and cleaning up resources. Requires the `saas_tenant.deprovision` permission. An optional `reason` string is recorded in the audit log.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "provisionId", "in": "path", "required": true, "description": "Tenant provision identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_DeprovisionRequest" } } } }, "responses": { "200": { "description": "Tenant deprovisioned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "`INVALID_ID_FORMAT` — provisionId is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `saas_tenant.deprovision` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — the tenant provision does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the tenant is already deprovisioned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-tenants/{packageId}/subscriptions": { "post": { "operationId": "saasPlatformCreateCustomerSubscription", "summary": "Create customer subscription", "description": "Creates a subscription record for a subscriber organization purchasing a pricing plan from the specified SaaS package. The caller must be the package owner and have the `subscription.create` permission. A subscriber cannot subscribe to their own package.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_CustomerSubscriptionCreateRequest" } } } }, "responses": { "201": { "description": "Subscription created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_CustomerSubscription" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — the package or pricing plan was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` or `DUPLICATE_SUBSCRIPTION` — an active subscription already exists for this subscriber and package.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListCustomerSubscriptions", "summary": "List customer subscriptions", "description": "Returns a paginated list of subscriptions for the specified SaaS package, scoped to the caller's organization. Requires `subscription.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by subscription status.", "schema": { "type": "string", "maxLength": 64 } }, { "name": "subscriber_org_id", "in": "query", "required": false, "description": "Filter by subscriber organization (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of subscriptions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_CustomerSubscription" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-tenants/{packageId}/subscriptions/{subscriptionId}": { "get": { "operationId": "saasPlatformGetCustomerSubscription", "summary": "Get customer subscription", "description": "Returns a single customer subscription by id. Requires `subscription.view` permission. A subscription outside the caller's org scope is reported as 404.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "subscriptionId", "in": "path", "required": true, "description": "Subscription identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The subscription record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_CustomerSubscription" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPlatformUpdateCustomerSubscription", "summary": "Update customer subscription", "description": "Updates a customer subscription (pricing plan, quantity, or metadata). At least one field must be provided. Requires `subscription.update` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "subscriptionId", "in": "path", "required": true, "description": "Subscription identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_CustomerSubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Subscription updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_CustomerSubscription" } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `INVALID_ID_FORMAT`, or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/saas-tenants/{packageId}/subscriptions/{subscriptionId}/cancel": { "post": { "operationId": "saasPlatformCancelCustomerSubscription", "summary": "Cancel customer subscription", "description": "Cancels an active customer subscription. Requires `subscription.cancel` permission. Returns `409 CONFLICT` if the subscription is already cancelled.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "subscriptionId", "in": "path", "required": true, "description": "Subscription identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Subscription cancelled.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "cancelled": { "type": "boolean" } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — the subscription does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — the subscription is already cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/configs": { "post": { "operationId": "saasPlatformCreateAppConfig", "summary": "Create app config", "description": "Creates a platform-specific app configuration record for a SaaS package. One config per package per platform is enforced. Requires `app_config.create` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_AppConfigCreateRequest" } } } }, "responses": { "201": { "description": "App config created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_AppConfig" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — referenced SaaS package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`APP_CONFIG_DUPLICATE_PLATFORM` — a config for this platform already exists for the package.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListAppConfigs", "summary": "List app configs", "description": "Returns a paginated list of app configs for the caller's organization. Requires `app_config.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": false, "description": "Filter by SaaS package (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "description": "Filter by platform.", "schema": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux", "web" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of app configs.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_AppConfig" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/configs/{configId}": { "get": { "operationId": "saasPlatformGetAppConfig", "summary": "Get app config", "description": "Returns a single app config by id. Requires `app_config.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "configId", "in": "path", "required": true, "description": "App config identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The app config.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_AppConfig" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPlatformUpdateAppConfig", "summary": "Update app config", "description": "Updates an existing app config. At least one field must be supplied. Requires `app_config.update` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "configId", "in": "path", "required": true, "description": "App config identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_AppConfigUpdateRequest" } } } }, "responses": { "200": { "description": "App config updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_AppConfig" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPlatformDeleteAppConfig", "summary": "Delete app config", "description": "Deletes an app config. Requires `app_config.delete` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "configId", "in": "path", "required": true, "description": "App config identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "App config deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/bundles": { "post": { "operationId": "saasPlatformCreateDataBundle", "summary": "Create data bundle", "description": "Creates a new versioned data bundle (seed data, configuration, or content payload) for a SaaS package. Requires `data_bundle.create` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_DataBundleCreateRequest" } } } }, "responses": { "201": { "description": "Data bundle created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_DataBundle" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — referenced SaaS package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListDataBundles", "summary": "List data bundles", "description": "Returns a paginated list of data bundles for the caller's organization. Requires `data_bundle.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": false, "description": "Filter by SaaS package (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of data bundles.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_DataBundle" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/bundles/current": { "get": { "operationId": "saasPlatformGetCurrentDataBundle", "summary": "Get current data bundle", "description": "Returns the currently published (active) data bundle for the specified SaaS package. Returns `404 NO_CURRENT_BUNDLE` when no bundle has been published yet. Requires `data_bundle.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The current published data bundle.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_DataBundle" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` (`NO_CURRENT_BUNDLE`) — no published bundle exists for this package.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/bundles/{bundleId}": { "get": { "operationId": "saasPlatformGetDataBundle", "summary": "Get data bundle", "description": "Returns a single data bundle by id. Requires `data_bundle.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "bundleId", "in": "path", "required": true, "description": "Data bundle identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The data bundle.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_DataBundle" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/bundles/{bundleId}/publish": { "post": { "operationId": "saasPlatformPublishDataBundle", "summary": "Publish data bundle", "description": "Marks a data bundle as the current published version for the package. The previously published bundle is demoted. Requires `data_bundle.publish` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "bundleId", "in": "path", "required": true, "description": "Data bundle identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bundle published.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "published" ], "properties": { "published": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/bundles/{bundleId}/rollback": { "post": { "operationId": "saasPlatformRollbackDataBundle", "summary": "Rollback to data bundle", "description": "Rolls back the current published bundle to the specified previous bundle. Requires `data_bundle.publish` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "bundleId", "in": "path", "required": true, "description": "Data bundle identifier to roll back to (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rollback performed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "rolled_back" ], "properties": { "rolled_back": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/builds": { "post": { "operationId": "saasPlatformCreateBuildJob", "summary": "Create build job", "description": "Creates a new build job for a native app platform (iOS, Android, Windows, macOS, or Linux — web is not a valid build target). The referenced app config must exist and belong to the same package. Requires `build_job.create` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_BuildJobCreateRequest" } } } }, "responses": { "201": { "description": "Build job queued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_BuildJob" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR` (e.g. web platform, invalid build-system/platform combination).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — referenced app config or SaaS package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListBuildJobs", "summary": "List build jobs", "description": "Returns a paginated list of build jobs for the caller's organization. Requires `build_job.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": false, "description": "Filter by SaaS package.", "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "description": "Filter by platform.", "schema": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by build status.", "schema": { "type": "string", "enum": [ "pending", "queued", "in_progress", "success", "failed", "cancelled" ] } }, { "name": "build_system", "in": "query", "required": false, "description": "Filter by build system.", "schema": { "type": "string", "enum": [ "cloudflare_container", "codemagic", "eas_build", "self_hosted_mac" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of build jobs.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_BuildJob" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/builds/{buildId}": { "get": { "operationId": "saasPlatformGetBuildJob", "summary": "Get build job", "description": "Returns a single build job by id. Requires `build_job.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "Build job identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The build job.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_BuildJob" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/builds/{buildId}/status": { "put": { "operationId": "saasPlatformUpdateBuildStatus", "summary": "Update build status", "description": "Updates the execution status of a build job, called by the build system (Cloudflare Container, Codemagic, EAS Build, or self-hosted Mac builder) as the job progresses. Requires `build_job.update` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "Build job identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_BuildStatusUpdateRequest" } } } }, "responses": { "200": { "description": "Build status updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_BuildJob" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`INVALID_STATUS_TRANSITION` — the requested status change is not permitted from the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/builds/{buildId}/cancel": { "post": { "operationId": "saasPlatformCancelBuildJob", "summary": "Cancel build job", "description": "Cancels a queued or in-progress build job. Returns `409 BUILD_JOB_NOT_CANCELLABLE` if the job is already in a terminal state (success, failed, or cancelled). Requires `build_job.cancel` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "Build job identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Build job cancelled.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "cancelled" ], "properties": { "cancelled": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`BUILD_JOB_NOT_CANCELLABLE` — the job is already in a terminal state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/screens": { "post": { "operationId": "saasPlatformCreateScreenDefinition", "summary": "Create screen definition", "description": "Creates a screen definition describing the layout and component configuration of a screen in the generated app. `screen_key` must be unique per package. Requires `screen_definition.create` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_ScreenDefinitionCreateRequest" } } } }, "responses": { "201": { "description": "Screen definition created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_ScreenDefinition" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — referenced SaaS package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`SCREEN_KEY_EXISTS` — a screen with this key already exists for the package.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListScreenDefinitions", "summary": "List screen definitions", "description": "Returns a paginated list of screen definitions for the caller's organization. Requires `screen_definition.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": false, "description": "Filter by SaaS package.", "schema": { "type": "string", "format": "uuid" } }, { "name": "screen_type", "in": "query", "required": false, "description": "Filter by screen type.", "schema": { "type": "string", "enum": [ "core", "custom", "view_based" ] } }, { "name": "is_active", "in": "query", "required": false, "description": "Filter by active status.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of screen definitions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_ScreenDefinition" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/app/screens/{screenId}": { "get": { "operationId": "saasPlatformGetScreenDefinition", "summary": "Get screen definition", "description": "Returns a single screen definition by id. Requires `screen_definition.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "screenId", "in": "path", "required": true, "description": "Screen definition identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The screen definition.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_ScreenDefinition" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPlatformUpdateScreenDefinition", "summary": "Update screen definition", "description": "Updates a screen definition. At least one field must be supplied. Requires `screen_definition.update` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "screenId", "in": "path", "required": true, "description": "Screen definition identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_ScreenDefinitionUpdateRequest" } } } }, "responses": { "200": { "description": "Screen definition updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_ScreenDefinition" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPlatformDeleteScreenDefinition", "summary": "Delete screen definition", "description": "Deletes a screen definition. Requires `screen_definition.delete` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "screenId", "in": "path", "required": true, "description": "Screen definition identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Screen definition deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/accounts": { "post": { "operationId": "saasPlatformCreateStoreAccount", "summary": "Create store account", "description": "Creates a store account credential for submitting apps to a supported app store. Requires `store_account.create` permission. Credentials are encrypted at rest and never returned in plaintext.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_StoreAccountCreateRequest" } } } }, "responses": { "201": { "description": "Store account created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_StoreAccount" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListStoreAccounts", "summary": "List store accounts", "description": "Returns a paginated list of store accounts for the caller's organization. Requires `store_account.view` permission. Credential fields are masked.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": false, "description": "Filter by SaaS package.", "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "description": "Filter by platform.", "schema": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of store accounts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_StoreAccount" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/accounts/{accountId}": { "get": { "operationId": "saasPlatformGetStoreAccount", "summary": "Get store account", "description": "Returns a single store account by id. Credential fields are masked. Requires `store_account.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "description": "Store account identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The store account.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_StoreAccount" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPlatformUpdateStoreAccount", "summary": "Update store account", "description": "Updates a store account. Requires `store_account.update` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "description": "Store account identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_StoreAccountUpdateRequest" } } } }, "responses": { "200": { "description": "Store account updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_StoreAccount" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPlatformDeleteStoreAccount", "summary": "Delete store account", "description": "Deletes a store account and its encrypted credentials. Requires `store_account.delete` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "description": "Store account identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Store account deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/accounts/{accountId}/validate": { "post": { "operationId": "saasPlatformValidateStoreAccount", "summary": "Validate store account credentials", "description": "Triggers a live connectivity check against the target store API to validate the stored credentials. Returns validation result and any error detail. Requires `store_account.update` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "description": "Store account identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Validation result (may indicate failure via `valid: false` — this is not an HTTP error).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "valid" ], "properties": { "valid": { "type": "boolean" }, "error": { "type": "string", "description": "Human-readable validation error, present when `valid` is false." } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/listings": { "post": { "operationId": "saasPlatformCreateStoreListing", "summary": "Create store listing", "description": "Creates a store listing for a SaaS package. Listing content (title, description, keywords, screenshots) is evaluated against the platform content policy before storage; requests that violate the policy are rejected with `CONTENT_POLICY_VIOLATION`. Requires `store_listing.create` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_StoreListingCreateRequest" } } } }, "responses": { "201": { "description": "Store listing created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_StoreListing" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "`CONTENT_POLICY_VIOLATION` — the listing content failed the platform content-safety evaluation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListStoreListings", "summary": "List store listings", "description": "Returns a paginated list of store listings for the caller's organization. Requires `store_listing.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": false, "description": "Filter by SaaS package.", "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "description": "Filter by target platform.", "schema": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of store listings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_StoreListing" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/listings/{listingId}": { "get": { "operationId": "saasPlatformGetStoreListing", "summary": "Get store listing", "description": "Returns a single store listing by id. Requires `store_listing.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "listingId", "in": "path", "required": true, "description": "Store listing identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The store listing.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_StoreListing" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "saasPlatformUpdateStoreListing", "summary": "Update store listing", "description": "Updates a store listing. Content fields are re-evaluated against the platform content policy; rejected content returns `CONTENT_POLICY_VIOLATION`. Requires `store_listing.update` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "listingId", "in": "path", "required": true, "description": "Store listing identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_StoreListingUpdateRequest" } } } }, "responses": { "200": { "description": "Store listing updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_StoreListing" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`CONTENT_POLICY_VIOLATION` — updated content failed the platform content-safety evaluation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/submissions": { "get": { "operationId": "saasPlatformListStoreSubmissions", "summary": "List store submissions", "description": "Returns a paginated list of store submissions for the caller's organization. Requires `store_submission.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": false, "description": "Filter by SaaS package.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by submission status.", "schema": { "type": "string", "enum": [ "draft", "pending_review", "in_review", "approved", "rejected", "published" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records (1–100, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Records to skip.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated list of submissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_StoreSubmission" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/submissions/{submissionId}": { "get": { "operationId": "saasPlatformGetStoreSubmission", "summary": "Get store submission", "description": "Returns a single store submission by id. Requires `store_submission.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "submissionId", "in": "path", "required": true, "description": "Store submission identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The store submission.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_StoreSubmission" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/submissions/{submissionId}/status": { "get": { "operationId": "saasPlatformGetStoreSubmissionStatus", "summary": "Get store submission status", "description": "Returns the current status details for a store submission including any reviewer notes. Requires `store_submission.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "submissionId", "in": "path", "required": true, "description": "Store submission identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Submission status details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "submission_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "pending_review", "in_review", "approved", "rejected", "published" ] }, "reviewer_notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/submissions/compliance-check": { "post": { "operationId": "saasPlatformRunSubmissionComplianceCheck", "summary": "Run submission compliance check", "description": "Triggers a compliance pre-check for a submission using the local compliance evaluation service (distinct from `POST /v1/store/compliance/check` which is database-backed). Returns a list of compliance issues and a pass/fail result. Requires `store_submission.view` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_ComplianceCheckRequest" } } } }, "responses": { "200": { "description": "Compliance check completed. `passed` indicates whether all checks passed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_ComplianceCheckResult" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "`VALIDATION_ERROR` — submission is missing required prerequisites for compliance evaluation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/compliance/check": { "post": { "operationId": "saasPlatformDbComplianceCheck", "summary": "Database-backed compliance check", "description": "Runs a database-backed compliance evaluation for a SaaS package and returns structured compliance findings. Distinct from `POST /v1/store/submissions/compliance-check` which uses the local service. Requires `store_submission.view` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_DbComplianceCheckRequest" } } } }, "responses": { "200": { "description": "Compliance check result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_ComplianceCheckResult" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "`VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/age-ratings": { "post": { "operationId": "saasPlatformCreateAgeRating", "summary": "Create age rating", "description": "Creates an age rating record for a SaaS package on a specific store platform. Both `saas_package_id` and `platform` are required. Requires `age_rating.create` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_AgeRatingCreateRequest" } } } }, "responses": { "201": { "description": "Age rating created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_AgeRating" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListAgeRatings", "summary": "List age ratings", "description": "Returns age rating records. Both `saas_package_id` and `platform` are required query parameters. Requires `age_rating.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": true, "description": "Target store platform.", "schema": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] } } ], "responses": { "200": { "description": "List of age ratings for the specified package and platform.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_AgeRating" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/age-ratings/{ratingId}": { "put": { "operationId": "saasPlatformUpdateAgeRating", "summary": "Update age rating", "description": "Updates an existing age rating record. Requires `age_rating.update` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "ratingId", "in": "path", "required": true, "description": "Age rating identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_AgeRatingUpdateRequest" } } } }, "responses": { "200": { "description": "Age rating updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_AgeRating" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/kyc/sessions": { "post": { "operationId": "saasPlatformCreateKycSession", "summary": "Create KYC session", "description": "Initiates a KYC (Know Your Customer) verification session for the caller's organization in the context of a SaaS package. Returns a session token and redirect URL to the KYC provider. Requires `kyc.create` permission.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_KycSessionCreateRequest" } } } }, "responses": { "201": { "description": "KYC session created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_KycSession" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/kyc/status": { "get": { "operationId": "saasPlatformGetKycStatus", "summary": "Get KYC verification status", "description": "Returns the current KYC verification status for the caller's organization on a SaaS package. Requires `kyc.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "KYC status for the organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "pending", "in_review", "approved", "rejected" ] }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/store/kyc/requirements": { "get": { "operationId": "saasPlatformGetKycRequirements", "summary": "Get KYC requirements", "description": "Returns the list of KYC requirements for a SaaS package (required documents, fields, supported regions). Requires `kyc.view` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "saas_package_id", "in": "query", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "KYC requirements.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_KycRequirements" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/listings": { "get": { "operationId": "saasPlatformBrowseMarketplaceListings", "summary": "Browse marketplace listings", "description": "Returns a paginated list of published marketplace listings. Public endpoint — no authentication required. Rate limited to 60 requests per minute per IP.", "tags": [ "SaaS Builder" ], "security": [], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Full-text search query (max 100 characters, trimmed).", "schema": { "type": "string", "maxLength": 100 } }, { "name": "category", "in": "query", "required": false, "description": "Filter by category (max 120 characters, trimmed).", "schema": { "type": "string", "maxLength": 120 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order.", "schema": { "type": "string", "enum": [ "rating", "newest", "downloads" ] } } ], "responses": { "200": { "description": "List of public marketplace listings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceListing" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "saasPlatformCreateMarketplaceListing", "summary": "Create marketplace listing", "description": "Creates a new marketplace listing. Requires `marketplace.create` permission. Unknown body keys are rejected with 400 (`additionalProperties: false`).", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceListingCreateRequest" } } } }, "responses": { "201": { "description": "Marketplace listing created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceListingAdmin" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/packages": { "get": { "operationId": "saasPlatformBrowseMarketplacePackages", "summary": "Browse marketplace packages", "description": "Returns available SaaS packages from the marketplace. Supports two modes: signup discovery (pass `visibility=signup` with either `org_id` or `domain`) and general browse. Public endpoint — no authentication required. Rate limited to 60 requests per minute per IP. Unknown query parameters are rejected with 400.", "tags": [ "SaaS Builder" ], "security": [], "parameters": [ { "name": "visibility", "in": "query", "required": false, "description": "Set to `signup` to fetch packages relevant for a specific organization or domain at signup. When `signup`, either `org_id` or `domain` is required.", "schema": { "type": "string", "enum": [ "signup" ] } }, { "name": "org_id", "in": "query", "required": false, "description": "Organization identifier for signup-mode lookup (UUIDv7). One of `org_id` or `domain` required when `visibility=signup`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "domain", "in": "query", "required": false, "description": "Verified domain for signup-mode lookup (max 253 chars, valid domain format). One of `org_id` or `domain` required when `visibility=signup`.", "schema": { "type": "string", "maxLength": 253 } }, { "name": "search", "in": "query", "required": false, "description": "Full-text search query for general browse (max 100 characters).", "schema": { "type": "string", "maxLength": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order for general browse.", "schema": { "type": "string", "enum": [ "newest", "name" ] } } ], "responses": { "200": { "description": "List of marketplace packages.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_MarketplacePackage" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/plans": { "get": { "operationId": "saasPlatformGetMarketplacePlans", "summary": "Get marketplace plans", "description": "Returns pricing plans for a SaaS package. Accepts either a UUID (`saas_package_id`) or a slug. UUID-based lookups are fully anonymous. Slug-based lookups apply a tighter per-IP rate limit and accept an optional bearer token to resolve subscriber-context pricing. Public endpoint — no authentication required by default; authentication is optional for subscriber-context slug resolution. Unknown query parameters are rejected with 400.", "tags": [ "SaaS Builder" ], "security": [], "parameters": [ { "name": "saas_package_id", "in": "query", "required": false, "description": "SaaS package identifier (UUID or URL slug). Exactly one of `saas_package_id` (UUID) or a slug equivalent must be supplied.", "schema": { "type": "string" } }, { "name": "visibility", "in": "query", "required": false, "description": "Plan visibility filter.", "schema": { "type": "string", "enum": [ "all", "signup" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "List of plans for the package.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_PricingPlan" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/addons": { "get": { "operationId": "saasPlatformGetMarketplaceAddons", "summary": "Get marketplace add-ons", "description": "Returns available add-ons for a SaaS package. `saas_package_id` is required. Public endpoint — no authentication required. Unknown query parameters are rejected with 400.", "tags": [ "SaaS Builder" ], "security": [], "parameters": [ { "name": "saas_package_id", "in": "query", "required": true, "description": "SaaS package identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "plan_slug", "in": "query", "required": false, "description": "Filter add-ons to those compatible with the specified plan slug.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "List of add-ons for the package.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_Addon" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "description": "`NOT_FOUND` — referenced SaaS package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/resolve-domain": { "get": { "operationId": "saasPlatformResolveMarketplaceDomain", "summary": "Resolve domain to SaaS package", "description": "Resolves a verified custom domain to its associated SaaS package metadata. Used by app clients at startup to discover the correct package configuration. Public endpoint — no authentication required. Unknown query parameters are rejected with 400.", "tags": [ "SaaS Builder" ], "security": [], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "The domain to resolve (must be a valid domain name).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolved package metadata.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_ResolvedDomain" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/resolve": { "get": { "operationId": "saasPlatformResolveMarketplaceDomainLegacy", "summary": "Resolve domain to SaaS package (legacy alias)", "description": "Legacy alias for `GET /v1/marketplace/resolve-domain`. Identical behavior. Prefer `resolve-domain` for new integrations. Public endpoint — no authentication required.", "tags": [ "SaaS Builder" ], "security": [], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "The domain to resolve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolved package metadata.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_ResolvedDomain" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/app-config": { "get": { "operationId": "saasPlatformGetMarketplaceAppConfig", "summary": "Get app configuration", "description": "Returns the app configuration for a SaaS package, resolved by domain or package ID. Public by default. Passing `subscriber_org_id` or `draft=true` requires a valid bearer token whose session org_id matches `subscriber_org_id`. Unknown query parameters are rejected with 400.", "tags": [ "SaaS Builder" ], "security": [], "parameters": [ { "name": "domain", "in": "query", "required": false, "description": "The verified domain for the SaaS package. One of `domain` or `package_id` is required.", "schema": { "type": "string" } }, { "name": "package_id", "in": "query", "required": false, "description": "SaaS package identifier (UUIDv7). One of `domain` or `package_id` is required.", "schema": { "type": "string", "format": "uuid" } }, { "name": "subscriber_org_id", "in": "query", "required": false, "description": "Subscriber organization identifier for subscriber-context config. Requires bearer authentication with matching org.", "schema": { "type": "string", "format": "uuid" } }, { "name": "draft", "in": "query", "required": false, "description": "Return draft config. Requires bearer authentication.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "App configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_AppConfigPublic" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "description": "`UNAUTHORIZED` — bearer token required when `subscriber_org_id` or `draft=true` is supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/build-config": { "get": { "operationId": "saasPlatformGetMarketplaceBuildConfig", "summary": "Get build configuration", "description": "Returns the build configuration for a SaaS package for the specified platform. Resolved by domain. Public endpoint — no authentication required. Unknown query parameters are rejected with 400.", "tags": [ "SaaS Builder" ], "security": [], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "The verified domain for the SaaS package.", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": true, "description": "Target platform.", "schema": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux", "web" ] } } ], "responses": { "200": { "description": "Build configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Platform-specific build configuration object." } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/build-targets": { "get": { "operationId": "saasPlatformGetMarketplaceBuildTargets", "summary": "Get build targets", "description": "Returns available build targets (platform + environment combinations) for a SaaS package. All parameters are optional. Public endpoint — no authentication required. Unknown query parameters are rejected with 400.", "tags": [ "SaaS Builder" ], "security": [], "parameters": [ { "name": "domain", "in": "query", "required": false, "description": "The verified domain for the SaaS package.", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": false, "description": "Filter by platform.", "schema": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux", "web" ] } }, { "name": "org_id", "in": "query", "required": false, "description": "Filter by organization.", "schema": { "type": "string", "format": "uuid" } }, { "name": "environment", "in": "query", "required": false, "description": "Filter by environment.", "schema": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] } } ], "responses": { "200": { "description": "Available build targets.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_BuildTarget" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/listings/manage": { "get": { "operationId": "saasPlatformManageMarketplaceListings", "summary": "Manage marketplace listings", "description": "Returns a paginated list of marketplace listings for the caller's organization, with management-level fields. Unlike the public browse endpoint, this returns draft and suspended listings. Any authenticated organization member may call this endpoint. Unknown query parameters are rejected with 400. NOTE: this route is registered before `GET /v1/marketplace/listings/{id}` to prevent path shadowing.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "mine_only", "in": "query", "required": false, "description": "When `true`, returns only listings owned by the caller's organization.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "search", "in": "query", "required": false, "description": "Full-text search query.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Filter by category.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by listing status.", "schema": { "type": "string", "enum": [ "draft", "pending_review", "published", "suspended" ] } }, { "name": "pricing_type", "in": "query", "required": false, "description": "Filter by pricing type.", "schema": { "type": "string", "enum": [ "free", "one_time", "subscription" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated list of managed listings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceListingAdmin" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/listings/{id}": { "get": { "operationId": "saasPlatformGetMarketplaceListingAdmin", "summary": "Get marketplace listing (management)", "description": "Returns full management-level detail for a single marketplace listing. `publisher_org_id` is required to scope the lookup. Any authenticated organization member may call this endpoint.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Marketplace listing identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "publisher_org_id", "in": "query", "required": true, "description": "Publisher organization identifier (UUIDv7). Used to scope the lookup.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The marketplace listing.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceListingAdmin" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "saasPlatformUpdateMarketplaceListing", "summary": "Update marketplace listing", "description": "Partially updates a marketplace listing. Requires `marketplace.update` permission. Unknown body keys are rejected with 400 (`additionalProperties: false`).", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Marketplace listing identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceListingUpdateRequest" } } } }, "responses": { "200": { "description": "Listing updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceListingAdmin" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "saasPlatformDeleteMarketplaceListing", "summary": "Delete marketplace listing", "description": "Deletes a marketplace listing. Requires `marketplace.delete` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Marketplace listing identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Listing deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/reviews": { "post": { "operationId": "saasPlatformCreateMarketplaceReview", "summary": "Create marketplace review", "description": "Creates a review for a marketplace listing. Requires `marketplace.review` permission. Rating must be an integer from 1 to 5. Unknown body keys are rejected with 400.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceReviewCreateRequest" } } } }, "responses": { "201": { "description": "Review created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceReview" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR` (e.g. rating out of range 1–5).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "saasPlatformListMarketplaceReviews", "summary": "List marketplace reviews", "description": "Returns a paginated list of reviews. Optionally filter by `listing_id`. Any authenticated organization member may call this endpoint. Unknown query parameters are rejected with 400.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "listing_id", "in": "query", "required": false, "description": "Filter reviews by listing (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated list of reviews.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceReview" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/subscriptions": { "post": { "operationId": "saasPlatformCreateMarketplaceSubscription", "summary": "Create marketplace subscription", "description": "Creates a subscription to a marketplace listing. Requires `marketplace.subscribe` permission. Unknown body keys are rejected with 400.", "tags": [ "SaaS Builder" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceSubscriptionCreateRequest" } } } }, "responses": { "201": { "description": "Subscription created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SaasPlatform_MarketplaceSubscription" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketplace/subscriptions/{id}": { "delete": { "operationId": "saasPlatformDeleteMarketplaceSubscription", "summary": "Delete marketplace subscription", "description": "Cancels and removes a marketplace subscription. Requires `marketplace.subscribe` permission.", "tags": [ "SaaS Builder" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Marketplace subscription identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Subscription removed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/marketing/events": { "post": { "operationId": "saasPlatformIngestMarketingEvents", "summary": "Ingest marketing events", "description": "Accepts a batch of up to 25 marketing analytics events for asynchronous processing. The endpoint returns 202 immediately — all processing is fire-and-forget; delivery is best-effort. This endpoint requires service authorization; calls that fail service authorization return 403. Rate limited to 100 requests per 60 seconds per IP. Content-Length must not exceed 100 KB. Events missing required UUID fields or malformed events within an otherwise valid batch are silently dropped (reflected in `eventsDropped`).", "tags": [ "SaaS Builder" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaasPlatform_MarketingEventBatchRequest" } } } }, "responses": { "202": { "description": "Events accepted for async processing. Returns counts of received and dropped events.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "eventsReceived", "eventsDropped" ], "properties": { "success": { "type": "boolean" }, "eventsReceived": { "type": "integer", "description": "Number of events accepted into the processing queue." }, "eventsDropped": { "type": "integer", "description": "Number of events dropped (e.g. due to schema errors or internal capacity limits)." } } } } } }, "400": { "description": "`INVALID_JSON` — unparseable body; or `MISSING_EVENTS` — the `events` array is absent or not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — the request did not pass service authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "`PAYLOAD_TOO_LARGE` — request body exceeds the 100 KB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "`UNSUPPORTED_MEDIA_TYPE` — Content-Type must be `application/json`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`BATCH_TOO_LARGE` — batch exceeds 25 events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — marketing event ingestion is not configured for this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/science/academic/verifications": { "post": { "operationId": "scienceAcademicInitiateVerification", "summary": "Initiate academic verification", "description": "Starts an academic identity/affiliation verification for the authenticated user and creates the external KYC handoff session. The organization and user are pinned from the session (never accepted in the body). An existing in-flight verification may be reused (`reused: true`).", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceAcademic_VerificationInitiateRequest" } } } }, "responses": { "200": { "description": "Verification initiated (or an existing one reused).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScienceAcademic_VerificationInitiateResult" } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body) or `VALIDATION_ERROR` (bad `requested_plan_slug`, non-https `return_url`, or unknown field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — a conflicting verification or subscription state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`VALIDATION_ERROR` — the requested plan is not verification-eligible or the state transition is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` / `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/science/academic/verifications/{id}": { "get": { "operationId": "scienceAcademicGetVerification", "summary": "Get a verification", "description": "Returns the status and details of an academic verification the caller owns (or may review).", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Verification identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The verification record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScienceAcademic_Verification" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/science/academic/subscriptions/current": { "get": { "operationId": "scienceAcademicGetCurrentSubscription", "summary": "Get the current academic subscription", "description": "Returns the caller's current academic subscription for the Backbuild Science package, if any.", "tags": [ "Prove, Science & Studio" ], "responses": { "200": { "description": "The current subscription (or null when none).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScienceAcademic_Subscription" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/science/academic/subscriptions": { "post": { "operationId": "scienceAcademicCreateSubscription", "summary": "Create an academic subscription", "description": "Activates the academic subscription by consuming a completed verification. The plan is pinned from the verification row (not the body).", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceAcademic_SubscriptionCreateRequest" } } } }, "responses": { "200": { "description": "The activated subscription (or an existing one reused).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScienceAcademic_Subscription" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — the referenced verification does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — an active subscription already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`VALIDATION_ERROR` — the verification is not in a consumable state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/science/academic/subscriptions/{subscription_id}/renew": { "post": { "operationId": "scienceAcademicRenewSubscription", "summary": "Renew an academic subscription", "description": "Renews an academic subscription by consuming a fresh completed verification (academic status must be re-confirmed each term).", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Subscription identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceAcademic_SubscriptionRenewRequest" } } } }, "responses": { "200": { "description": "The renewed subscription.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScienceAcademic_Subscription" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "`VALIDATION_ERROR` — the verification is not consumable or the subscription cannot be renewed in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/science/academic/verifications/bulk-import": { "post": { "operationId": "scienceAcademicBulkImport", "summary": "Bulk-import academic verifications", "description": "Reviewer endpoint to create verification rows on behalf of subject users (1–500 per call), e.g. from an institution roster. Requires the academic-review capability. Also reachable at `/v1/science/verifications/bulk-import`.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceAcademic_BulkImportRequest" } } } }, "responses": { "200": { "description": "Import summary (created / skipped counts).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — the caller lacks the academic-review capability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`VALIDATION_ERROR` — a row failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/science/academic/verifications/erase": { "post": { "operationId": "scienceAcademicEraseVerification", "summary": "Erase academic verification data (GDPR)", "description": "GDPR Article 17 erasure of a subject's academic verification data. The subject erases their own data when `user_id` is omitted; a super-admin or academic-review holder may target another subject. Also reachable at `/v1/science/verifications/erase`.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceAcademic_EraseRequest" } } } }, "responses": { "200": { "description": "Erasure completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — not permitted to erase another subject's data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "`DATABASE_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/secrets": { "post": { "operationId": "scienceStudioLinkSecret", "summary": "Link a vault secret to a production", "description": "Registers a secret link that allows the renderer to inject a vault-stored credential (e.g. API key, URL token) into the production at render time. The secret value is never transmitted through this endpoint — only the vault reference (vault_id, item_key) and injection metadata are stored. The `escrow_verified` attestation required by the renderer is established server-side by the platform's credential-escrow control plane; clients cannot supply it. Until that server-side attestation step is completed the stored procedure fails closed and secret-linked renders are blocked.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_LinkSecretRequest" }, "example": { "vault_id": "019d0000-0000-7000-8000-000000000001", "item_key": "elevenlabs-api-key", "purpose": "TTS synthesis", "allowed_origin": "https://api.elevenlabs.io", "injection_field": "x-api-key" } } } }, "responses": { "200": { "description": "Secret link registered. The link record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_SecretLink" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/secrets/{linkId}": { "delete": { "operationId": "scienceStudioUnlinkSecret", "summary": "Remove a vault secret link from a production", "description": "Removes a previously registered vault secret link from the production. The underlying vault item is not modified; only the link record is deleted. Future renders will no longer have access to the referenced credential via this link.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "linkId", "in": "path", "required": true, "description": "Secret link identifier (UUIDv7) as returned by the link-secret endpoint.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Optional body — ignored by the SP; may be omitted entirely.", "additionalProperties": true } } } }, "responses": { "200": { "description": "Secret link removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/estimate": { "get": { "operationId": "scienceStudioGetEstimate", "summary": "Get a credit-cost estimate for generating a production", "description": "Returns the predicted render credit cost and change-gate analysis for the production in its current state. This is a read-only preflight — it has no side effects, does not reserve credits, and does not enqueue a render job. Use it to show the user the precise cost before they commit to calling the generate endpoint. The estimate mirrors the gate math used by `generate` so the number shown in the editor confirmation dialog exactly matches what will be charged.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Render estimate and predicted change-gate analysis.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_EstimateResult" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/generate": { "post": { "operationId": "scienceStudioGenerate", "summary": "Generate (render) a production", "description": "Enqueues or directly triggers a render job for the production. Credits are spent on a cache miss (scripts/scenes that have changed since the last render). Returns the job_id, the final credit estimate, and the predicted change-gate results. Poll `GET /v1/projects/{projectId}/studio/jobs/{jobId}` for status. The optional `mode` parameter scopes the render: `audio` re-synthesizes narration only; `video` renders video against existing audio; `full` (default) synthesizes audio first if changed, then renders video.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_GenerateRequest" }, "example": { "mode": "full" } } } }, "responses": { "200": { "description": "Render job enqueued. The job id and credit estimate are returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_GenerateResult" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`INSUFFICIENT_CREDITS` — the organization has insufficient render credits to complete the job; `QUOTA_EXCEEDED` — the organization has reached its render quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/jobs/{jobId}": { "get": { "operationId": "scienceStudioGetJob", "summary": "Get the status of a render job", "description": "Returns the current status and progress information for a Studio render job. Poll this endpoint after calling `generate` until the job reaches a terminal state (`completed` or `failed`). The SP resolves the project and production from the job_id and enforces project-membership authorization. Internal token and pinned-secret state are omitted from the response.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "jobId", "in": "path", "required": true, "description": "Render job identifier (UUIDv7) as returned by the generate endpoint.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current job status.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_JobStatus" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/outputs": { "get": { "operationId": "scienceStudioGetOutputs", "summary": "List composed render outputs for a production", "description": "Returns the composed output metadata for the production's published baseline render, or for a specific render when `render_id` is supplied. Only composed outputs are returned — raw pipeline captures are never exposed. Each output record includes the storage key and associated metadata; a future update will presign the key into a short-lived single-object URL via the R2 binding.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "render_id", "in": "query", "required": false, "description": "Render identifier (UUIDv7). When omitted, returns the published baseline render outputs.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Composed render output records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScienceStudio_OutputRecord" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/outputs/{format}": { "get": { "operationId": "scienceStudioGetOutputByFormat", "summary": "Get a specific format's render output for a production", "description": "Returns the composed output record for the specified format (e.g. `mp4_9_16`, `mp4_16_9`) from the production's published baseline render, or from the render identified by `render_id`. Only composed outputs are returned — raw captures are never exposed. The format identifier is the codec/aspect-ratio key assigned during rendering.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "path", "required": true, "description": "Output format key (e.g. `mp4_9_16`, `mp4_16_9`). The available keys are returned in the base outputs list.", "schema": { "type": "string" } }, { "name": "render_id", "in": "query", "required": false, "description": "Render identifier (UUIDv7). When omitted, returns the published baseline render output for this format.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Composed render output record for the specified format.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_OutputRecord" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/script": { "get": { "operationId": "scienceStudioGetScript", "summary": "Get the script for a production", "description": "Returns the current (or a specific versioned) script body for the given production. The script is the primary narration-text content used to drive the TTS synthesis and word-timeline. Pass `?version=` to retrieve a specific version; omit for the latest.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "query", "required": false, "description": "Specific script version number to retrieve. Omit to get the latest version.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The script content for the requested version.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_ScriptContent" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "scienceStudioSetScript", "summary": "Replace the script for a production", "description": "Replaces the entire script body for the production with the supplied content. The stored procedure performs strict validation of the script structure (sections, segments, speaker assignments) and creates a new version; the previous version is retained in the version history. Calling this resets the TTS synthesis state — a re-generate will re-synthesize narration from scratch.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ScriptSetRequest" } } } }, "responses": { "200": { "description": "Script updated. The new script record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_ScriptContent" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/actions": { "get": { "operationId": "scienceStudioGetActions", "summary": "Get the actions list for a production", "description": "Returns the current on-screen actions (cursor moves, click highlights, app-drive events, camera transitions) attached to the production. Actions are keyed by timeline position and used by the video renderer.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The actions array for the production.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Ordered list of on-screen action descriptors. Structure is SP-validated; see `api.studio_actions_get` for the full field set.", "items": { "type": "object", "additionalProperties": true } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "scienceStudioSetActions", "summary": "Replace the actions list for a production", "description": "Replaces the entire ordered actions list for the production (replace-the-set semantics). The stored procedure strictly validates the nested array structure. Used by the Studio editor when the user reorders, adds, or removes on-screen actions in the timeline.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "Actions replaced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/scenes": { "put": { "operationId": "scienceStudioSetScenes", "summary": "Replace the scenes list for a production", "description": "Replaces the entire scenes list for the production (replace-the-set semantics). Scenes define the visual segments of the video — background, screen-demo captures, b-roll imagery, and SVG overlays. The SP strictly validates the nested structure.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "Scenes replaced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/music": { "put": { "operationId": "scienceStudioSetMusic", "summary": "Replace the music placements for a production", "description": "Replaces the entire list of background music placements for the production (replace-the-set semantics). Each placement references an asset_id from the org media library, with a start offset and volume envelope. The SP validates structure and asset existence.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "Music placements replaced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/sfx": { "put": { "operationId": "scienceStudioSetSfx", "summary": "Replace the sound-effect placements for a production", "description": "Replaces the entire list of sound-effect placements for the production (replace-the-set semantics). Each placement references an asset_id from the org media library with a timeline position and volume. The SP validates structure and asset existence.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "SFX placements replaced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/overlays": { "put": { "operationId": "scienceStudioSetOverlays", "summary": "Replace the visual overlays for a production", "description": "Replaces the entire list of visual overlays for the production (replace-the-set semantics). Overlays include SVG graphics, lower-thirds, callout boxes, and other composited visual elements with timeline positions. The SP validates structure and asset references.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "Overlays replaced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/metadata": { "put": { "operationId": "scienceStudioSetMetadata", "summary": "Replace the render metadata for a production", "description": "Replaces the render metadata block for the production (replace-the-set semantics). Metadata includes codec settings, aspect-ratio, output format, chapter markers, and codec-level parameters passed to the render pipeline. The SP validates structure.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "Metadata replaced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}/contributors": { "put": { "operationId": "scienceStudioSetContributors", "summary": "Replace the contributor credits for a production", "description": "Replaces the contributor credits list for the production (replace-the-set semantics). Contributors are credited in the output metadata and optional end-card; the SP validates structure.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "Contributors replaced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/studio/voices": { "get": { "operationId": "scienceStudioListVoices", "summary": "List available voices", "description": "Returns the organization's available TTS voices, including both the platform's built-in voice catalog and any custom voices the organization has added. Voices are referenced by `voice_id` in production script speaker assignments.", "tags": [ "Prove, Science & Studio" ], "responses": { "200": { "description": "List of available voices.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScienceStudio_Voice" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "scienceStudioAddCustomVoice", "summary": "Add a custom voice to the organization library", "description": "Registers a custom TTS provider voice in the organization's voice library by its external provider identifier. The `provider_voice_id` is the identifier assigned by the TTS provider (e.g. ElevenLabs voice id). The voice is available immediately for use in production speaker assignments.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_VoiceAddRequest" }, "example": { "provider_voice_id": "Vek2E11z0mkT8fYiTyI0", "display_name": "Primary Narrator" } } } }, "responses": { "200": { "description": "Voice registered. The new voice record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_Voice" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/studio/voices/{voiceId}": { "patch": { "operationId": "scienceStudioUpdateVoice", "summary": "Update a custom voice in the organization library", "description": "Partially updates a custom voice record (e.g. display_name, settings). The SP is the authority for which fields are mutable; only custom (non-platform) voices owned by the organization may be updated.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "voiceId", "in": "path", "required": true, "description": "Voice identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "Voice updated. The updated voice record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_Voice" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "scienceStudioDeleteVoice", "summary": "Remove a custom voice from the organization library", "description": "Removes a custom voice from the organization's voice library. Only custom (non-platform) voices owned by the organization may be deleted. Voices referenced in existing production scripts are not automatically removed from those scripts.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "name": "voiceId", "in": "path", "required": true, "description": "Voice identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Optional body — ignored by the SP; may be omitted entirely.", "additionalProperties": true } } } }, "responses": { "200": { "description": "Voice removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/studio/media": { "post": { "operationId": "scienceStudioRegisterMedia", "summary": "Register a media asset record in the org media library", "description": "Registers a media asset metadata record in the organization's media library without uploading bytes. Use this endpoint when the bytes are already stored externally or when the caller needs to pre-allocate an `asset_id`. To upload audio bytes and register in a single call, use `POST /v1/studio/media/upload` instead. The SP derives the storage key server-side.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "Media asset record registered. The asset record including `asset_id` and `r2_key` is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_MediaAsset" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/studio/media/upload": { "post": { "operationId": "scienceStudioUploadAudio", "summary": "Upload an audio file to the org media library", "description": "Validates, registers, and stores an audio file (music or SFX) in the organization's media library in a single call. The audio bytes are supplied as a base64-encoded string. The endpoint performs: MIME allow-list check, byte-level magic-byte content sniff, 25 MB size enforcement, and a deny-list hash check. On success the asset row is created with a server-derived R2 storage key and the bytes are written to R2. Returns the `MediaAsset` record including `asset_id` for use in music/SFX production placements.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_UploadAudioRequest" }, "example": { "kind": "music", "mime": "audio/mpeg", "filename": "background-loop.mp3", "data_base64": "", "duration_ms": 120000 } } } }, "responses": { "200": { "description": "Audio uploaded and registered. The `MediaAsset` record including `asset_id` is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_MediaAsset" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` (missing/invalid fields, invalid base64, empty file, file exceeds 25 MB), `UNSUPPORTED_FILE_TYPE` (MIME type not in the audio allow-list, or magic-byte sniff failed), `UPLOAD_SUPPRESSED` (content matches the platform deny list).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — the upload suppression check service or R2 storage binding was unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/studio/shapes": { "get": { "operationId": "scienceStudioListShapes", "summary": "List available shapes in the org shape library", "description": "Returns the organization's available shapes — SVG-based graphic primitives and imported shape assets that can be placed as overlays in productions.", "tags": [ "Prove, Science & Studio" ], "responses": { "200": { "description": "List of available shape records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScienceStudio_ShapeRecord" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/studio/shapes/import": { "post": { "operationId": "scienceStudioImportShape", "summary": "Import a shape into the org shape library", "description": "Imports an SVG shape asset into the organization's shape library. The imported shape is immediately available for use as an overlay in productions. The SP validates the SVG structure and assigns a platform `shape_id`.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ContentSetRequest" } } } }, "responses": { "200": { "description": "Shape imported. The shape record including `shape_id` is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_ShapeRecord" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/science/substrate/clone": { "post": { "operationId": "scienceStudioSubstrateClone", "summary": "Clone the Substrate Framework into the caller's organization", "description": "Copies the canonical read-only Substrate Framework project (all documents and structure) into the authenticated user's organization as a new project. Requires an active Backbuild Science subscription for the organization; organization admin or owner role is required. Subsequent edits to the cloned project are blocked until the clone is forked via `POST /v1/science/substrate/fork`. If an identical clone already exists the operation is idempotent: `already_existed` is `true` and `backfilled` reflects whether any missing documents were re-added.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_CloneRequest" }, "example": { "name": "Substrate Framework", "slug": "substrate-framework" } } } }, "responses": { "201": { "description": "Clone created (or already existed). The project record stub is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_SubstrateCloneResult" } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `VALIDATION_ERROR` (a field failed schema validation — e.g. slug contains illegal characters or exceeds 100 chars).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_REQUIRED` — no valid session token presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller lacks the required admin or owner role within the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a project with the supplied slug already exists in the organization, a duplicate clone conflict occurred, or the organization does not have an active Backbuild Science subscription (paywall precondition not met).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions": { "get": { "operationId": "scienceStudioListProductions", "summary": "List productions in a project", "description": "Returns all active Scripted Media Studio productions belonging to the specified project. The organization and RLS scope are derived from the caller's access token; the project must be accessible to the caller. Productions are ordered by creation time, newest first.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "responses": { "200": { "description": "List of productions for the project.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScienceStudio_Production" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "scienceStudioCreateProduction", "summary": "Create a production", "description": "Creates a new Scripted Media Studio production within the specified project. A production is the top-level container for a scripted video/audio piece — it holds the script, scenes, voice assignments, music/SFX placements, and render metadata. Both `title` and `slug` are required at creation; additional content sections are populated via the dedicated content-setter endpoints.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ProductionCreateRequest" }, "example": { "title": "Introduction to Backbuild AI", "slug": "intro-backbuild-ai" } } } }, "responses": { "200": { "description": "Production created. The created production record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_Production" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/studio/productions/{productionId}": { "get": { "operationId": "scienceStudioGetProduction", "summary": "Get a production", "description": "Returns a single Scripted Media Studio production by id. A production the caller cannot see (wrong org, no project membership, or non-existent) is returned as `404 NOT_FOUND`.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The production record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_Production" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "scienceStudioUpdateProduction", "summary": "Update a production's metadata", "description": "Partially updates a production's top-level metadata (title, slug, description, status, voice assignments, etc.). The body is a free-form JSON object validated and applied by the stored procedure — the SP is the authority for which fields are mutable and enforces project-membership authorization. At least one field must be supplied.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ProductionUpdateRequest" } } } }, "responses": { "200": { "description": "Production updated. The updated production record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_Production" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "scienceStudioDeleteProduction", "summary": "Soft-delete a production", "description": "Marks a production as deleted (soft-delete). The underlying data is preserved for the audit trail; the production is hidden from listings. The stored procedure enforces project-membership and role authorization.", "tags": [ "Prove, Science & Studio" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "productionId", "in": "path", "required": true, "description": "Production identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Optional body — ignored by the SP; may be omitted entirely.", "additionalProperties": true } } } }, "responses": { "200": { "description": "Production soft-deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/science/substrate/fork": { "post": { "operationId": "scienceStudioSubstrateFork", "summary": "Fork a read-only Substrate clone into an editable copy", "description": "Creates a fully editable fork of an existing read-only Substrate Framework clone. This is the standard resolution of a `FORK_REQUIRED` error returned when a caller attempts to edit a readonly clone via `api.document_update` or `api.project_update`. The fork inherits all documents from the source clone; subsequent writes target the fork. Requires organization admin, owner, or developer role.", "tags": [ "Prove, Science & Studio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceStudio_ForkRequest" }, "example": { "source_project_id": "019d0000-0000-7000-8000-000000000000", "name": "My Substrate Fork", "slug": "my-substrate-fork" } } } }, "responses": { "201": { "description": "Fork created. The new editable project record is returned under `data`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScienceStudio_SubstrateForkResult" } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `VALIDATION_ERROR` (a field failed schema validation — e.g. `source_project_id` is not a valid UUID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_REQUIRED` — no valid session token presented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`FORBIDDEN` — caller lacks admin, owner, or developer role, or does not own the source clone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` — `source_project_id` does not exist or is not visible to the caller's organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a project with the supplied slug already exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/roles": { "get": { "operationId": "securityListRoles", "summary": "List RBAC roles", "description": "Returns the system and custom roles available within the caller's organization, suitable for display in the IAM Roles UI. System catalog roles (`is_system=true`) are platform-defined and read-only. Custom roles are org-specific. The response payload is `{ roles: [...], total_count: N }`.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring filter on role name.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum roles to return (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination (default 0).", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of roles.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_RoleListData" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "securityCreateRole", "summary": "Create a custom role", "description": "Creates a new custom role in the caller's organization with an optional set of permission slugs. The role's `is_system` flag is always `false`; clients cannot create system roles. Permission slugs are validated against the platform's system-permission catalog — unknown slugs are rejected. The body uses `.strict()` validation: any unrecognized field (e.g. `is_super_admin`) returns `400 VALIDATION_ERROR`.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_RoleCreateRequest" } } } }, "responses": { "201": { "description": "Role created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Role" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — body failed validation or a permission slug was unrecognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks the `org.manage_roles` permission, or attempted to write to the system catalog (only the root org may do so).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` — a role with that name already exists in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/roles/{roleId}": { "get": { "operationId": "securityGetRole", "summary": "Get a role", "description": "Returns a single role by its slug key. Both system roles (e.g. `owner`, `admin`) and custom roles (lowercase slug) are addressed by their text slug, not a UUID.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "roleId", "in": "path", "required": true, "description": "Role slug key (lowercase alphanumeric with dots, underscores, and hyphens; 1–150 chars).", "schema": { "type": "string", "minLength": 1, "maxLength": 150, "pattern": "^[a-z0-9][a-z0-9._-]*$" } } ], "responses": { "200": { "description": "Role record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Role" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — the roleId path param is not a valid role slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "securityUpdateRole", "summary": "Update a custom role", "description": "Updates a custom role's name, description, permission set, or metadata. System roles (`is_system=true`) cannot be updated via this endpoint. The body uses `.strict()` validation — unknown fields including `is_super_admin` and `is_system` return `400 VALIDATION_ERROR`.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "roleId", "in": "path", "required": true, "description": "Role slug key (1–150 chars, lowercase dot-notation slug).", "schema": { "type": "string", "minLength": 1, "maxLength": 150, "pattern": "^[a-z0-9][a-z0-9._-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_RoleUpdateRequest" } } } }, "responses": { "200": { "description": "Updated role record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Role" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller lacks `org.manage_roles`, the target is a system role, or a role-hierarchy gate was violated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "securityDeleteRole", "summary": "Delete a custom role", "description": "Deletes a custom role by slug. System roles cannot be deleted. Any members currently assigned only this role will lose that assignment.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "roleId", "in": "path", "required": true, "description": "Role slug key.", "schema": { "type": "string", "minLength": 1, "maxLength": 150, "pattern": "^[a-z0-9][a-z0-9._-]*$" } } ], "responses": { "200": { "description": "Role deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — the roleId path param is not a valid role slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/permissions": { "get": { "operationId": "securityListPermissions", "summary": "List permissions", "description": "Returns the permission catalog for the organization. Permissions are referenced by dot-notation slug (e.g. `project.view`, `org.manage_roles`). The response payload is `{ permissions: [...], total_count: N }`.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Filter by name substring.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum permissions to return (1–100, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination (default 0).", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Permission list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_PermissionListData" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "securityCreatePermission", "summary": "Create a permission", "description": "Creates a custom permission in the organization's permission catalog. `resource` and `action` define the access dimension. The body is strict (`.strict()`): any unknown field returns `400 VALIDATION_ERROR`.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_PermissionCreateRequest" } } } }, "responses": { "201": { "description": "Permission created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Permission" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — a permission with the same name or resource/action combination already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/permissions/{permissionId}": { "delete": { "operationId": "securityDeletePermission", "summary": "Delete a permission", "description": "Deletes a permission from the organization's permission catalog by UUID. Roles that reference this permission will have it removed.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "permissionId", "in": "path", "required": true, "description": "Permission UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Permission deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — permissionId is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/effective-permissions": { "get": { "operationId": "securityGetEffectivePermissions", "summary": "Get effective permissions", "description": "Returns the resolved permission set for the target user in the caller's organization, optionally scoped to a specific project. By default queries the authenticated caller's own permissions. Only organization owners, admins, and super-admins may query another user's permissions (returns `403 FORBIDDEN` otherwise).", "tags": [ "Admin & Security" ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "Target user UUID. Omit to query the caller's own permissions.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": false, "description": "Project UUID. When supplied, permissions are further scoped to the given project.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Resolved effective permissions for the target user.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Permission resolution payload (permissions array and metadata as returned by the stored procedure)." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller is not an owner/admin/super-admin and is querying another user's permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/policies": { "get": { "operationId": "securityListPolicies", "summary": "List RBAC policies", "description": "Returns RBAC access policies for the organization with limit/offset pagination. Supports filtering by resource type, search string, and active/inactive status.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Filter by policy name substring.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "resource_type", "in": "query", "required": false, "description": "Filter by resource type.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by active/inactive status. Omit for all.", "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum policies to return (1–100, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination (default 0).", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated policy list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_PolicyListData" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "securityCreatePolicy", "summary": "Create an RBAC policy", "description": "Creates a new RBAC policy. Either `policy_name` or `name` must be supplied. Either `resource_type` or `resource_pattern` must be supplied. Either `operation` or `action_pattern` must be supplied. The body is strict (`additionalProperties: false`).", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_PolicyCreateRequest" } } } }, "responses": { "201": { "description": "Policy created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Policy" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/policies/{policyId}": { "get": { "operationId": "securityGetPolicy", "summary": "Get a policy", "description": "Returns a single RBAC policy by UUID.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "policyId", "in": "path", "required": true, "description": "Policy UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Policy record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Policy" } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — policyId is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "securityUpdatePolicy", "summary": "Update a policy", "description": "Updates fields on an existing RBAC policy. All fields are optional; the body is strict (`additionalProperties: false`).", "tags": [ "Admin & Security" ], "parameters": [ { "name": "policyId", "in": "path", "required": true, "description": "Policy UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_PolicyUpdateRequest" } } } }, "responses": { "200": { "description": "Updated policy record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Policy" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "securityDeletePolicy", "summary": "Delete a policy", "description": "Permanently deletes an RBAC policy.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "policyId", "in": "path", "required": true, "description": "Policy UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Policy deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — policyId is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/departments": { "get": { "operationId": "securityListDepartments", "summary": "List departments", "description": "Lists departments in the organization. Departments are logical groupings of members and projects for RBAC/policy assignment.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Filter by department name substring.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum departments to return (1–100, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination (default 0).", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Department list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_DepartmentListData" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "securityCreateDepartment", "summary": "Create a department", "description": "Creates a new department in the organization. The body uses `.strict()` validation.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_DepartmentCreateRequest" } } } }, "responses": { "201": { "description": "Department created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Department" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/departments/{departmentId}": { "put": { "operationId": "securityUpdateDepartment", "summary": "Update a department", "description": "Updates an existing department's name or description. The body uses `.strict()` validation.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "departmentId", "in": "path", "required": true, "description": "Department UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_DepartmentUpdateRequest" } } } }, "responses": { "200": { "description": "Updated department.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Department" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "securityDeleteDepartment", "summary": "Delete a department", "description": "Permanently deletes a department by UUID. Members and projects are unlinked from the department.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "departmentId", "in": "path", "required": true, "description": "Department UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Department deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/groups": { "get": { "operationId": "securityListGroups", "summary": "List groups", "description": "Lists groups in the organization. Groups are sets of members for policy assignment.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Filter by group name substring.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum groups to return (1–100, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination (default 0).", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Group list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_GroupListData" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "securityCreateGroup", "summary": "Create a group", "description": "Creates a new group in the organization. The body uses `.strict()` validation.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_GroupCreateRequest" } } } }, "responses": { "201": { "description": "Group created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Group" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/rbac/groups/{groupId}": { "put": { "operationId": "securityUpdateGroup", "summary": "Update a group", "description": "Updates an existing group's name or description. The body uses `.strict()` validation.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "Group UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_GroupUpdateRequest" } } } }, "responses": { "200": { "description": "Updated group.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Group" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "securityDeleteGroup", "summary": "Delete a group", "description": "Permanently deletes a group by UUID.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "Group UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Group deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security": { "get": { "operationId": "securityGetOverview", "summary": "Security overview dashboard", "description": "Returns the security posture dashboard for the caller's organization including alert counts, authentication metrics, violation stats, and an overall health score. Optionally includes platform-generated recommendations when `include_recommendations=true`.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "from_date", "in": "query", "required": false, "description": "ISO 8601 datetime. Start of the reporting window.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date", "in": "query", "required": false, "description": "ISO 8601 datetime. End of the reporting window.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_recommendations", "in": "query", "required": false, "description": "When `true`, the response includes up to 10 platform-generated remediation recommendations.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Security overview payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Overview" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/audit/events": { "get": { "operationId": "securityListAuditEvents", "summary": "List audit events", "description": "Returns audit events for the organization with limit/offset pagination. Can be filtered by event type, user, session, severity, and time range. Limit is 1–1000 (default 50).", "tags": [ "Admin & Security" ], "parameters": [ { "name": "event_type", "in": "query", "required": false, "description": "Filter by event type string.", "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "required": false, "description": "Filter events generated by a specific user UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "query", "required": false, "description": "Filter by session ID string.", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "description": "Filter by severity level.", "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "from_date", "in": "query", "required": false, "description": "ISO 8601 datetime lower bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date", "in": "query", "required": false, "description": "ISO 8601 datetime upper bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum events to return (1–1000, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination (default 0).", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated audit event list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_AuditEventListData" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "securityCreateAuditEvent", "summary": "Create an audit event", "description": "Manually records a custom audit event for the organization. Useful for recording actions that originate outside the Backbuild platform (e.g. off-platform admin actions) while maintaining a unified audit trail.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_AuditEventCreateRequest" } } } }, "responses": { "201": { "description": "Audit event created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_AuditEvent" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/alerts": { "get": { "operationId": "securityListAlerts", "summary": "List security alerts", "description": "Returns security alerts for the organization. Supports filtering by alert type, severity, status, and time range. Limit is 1–100 (default 25).", "tags": [ "Admin & Security" ], "parameters": [ { "name": "alert_type", "in": "query", "required": false, "description": "Filter by alert type string.", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "description": "Filter by severity.", "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "active", "acknowledged", "resolved", "false_positive" ] } }, { "name": "from_date", "in": "query", "required": false, "description": "ISO 8601 datetime lower bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date", "in": "query", "required": false, "description": "ISO 8601 datetime upper bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum alerts to return (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination (default 0).", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Alert list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_AlertListData" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "securityCreateAlert", "summary": "Create a security alert", "description": "Creates a new security alert for the organization. Alerts can reference threat indicators, affected resources, and recommended response actions.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_AlertCreateRequest" } } } }, "responses": { "201": { "description": "Alert created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Alert" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/alerts/{alertId}": { "put": { "operationId": "securityUpdateAlert", "summary": "Update a security alert", "description": "Updates a security alert's status, resolution notes, or metadata. Status transitions: `active → acknowledged → resolved` (or `→ false_positive`). Returns `404` if not found.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "alertId", "in": "path", "required": true, "description": "Alert UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_AlertUpdateRequest" } } } }, "responses": { "200": { "description": "Updated alert.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_Alert" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/metrics": { "get": { "operationId": "securityGetMetrics", "summary": "Get security metrics summary", "description": "Returns aggregated security metrics (authentication success/failure rates, anomaly counts, policy violation counts) for the organization within the specified time window.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "from_date", "in": "query", "required": false, "description": "ISO 8601 datetime lower bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date", "in": "query", "required": false, "description": "ISO 8601 datetime upper bound.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Security metrics payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Aggregated security metrics as returned by the stored procedure." } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/dsar": { "post": { "operationId": "securityCreateDsarRequest", "summary": "Create a Data Subject Access Request", "description": "Opens a Data Subject Access Request (DSAR) for an identified data subject. Covers all GDPR Art. 15-20 right types. Requires a **fresh MFA step-up** (within the last 5 minutes) via `requireMfaStepUp()`. API-key sessions cannot call this endpoint. The body is strict — any unrecognized field returns `400`.", "tags": [ "Admin & Security" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_DsarCreateRequest" } } } }, "responses": { "201": { "description": "DSAR request created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_DsarRequest" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`MFA_STEPUP_REQUIRED` — the session does not have a fresh MFA step-up (within the last 5 minutes), or is an API-key session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "securityListDsarRequests", "summary": "List DSAR requests", "description": "Returns DSAR requests for the organization. Requires a **fresh MFA step-up**. Supports filtering by status and limit/offset pagination (limit 1–1000, default 50).", "tags": [ "Admin & Security" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by request status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records to return (1–1000, default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset for pagination (default 0).", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "DSAR request list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_DsarListData" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`MFA_STEPUP_REQUIRED` — fresh MFA step-up is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/dsar/{dsarId}": { "get": { "operationId": "securityGetDsarRequest", "summary": "Get a DSAR request", "description": "Returns a specific DSAR request by UUID. Requires a fresh MFA step-up.", "tags": [ "Admin & Security" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dsarId", "in": "path", "required": true, "description": "DSAR request UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DSAR request record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_DsarRequest" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — dsarId is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`MFA_STEPUP_REQUIRED` — fresh MFA step-up required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/dsar/{dsarId}/export": { "get": { "operationId": "securityExportDsarData", "summary": "Export data for a DSAR request", "description": "Exports all personal data associated with the DSAR request in machine-readable format (GDPR Art. 20 — right to data portability). Requires a fresh MFA step-up.", "tags": [ "Admin & Security" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dsarId", "in": "path", "required": true, "description": "DSAR request UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Exported personal data payload.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Personal data export (structure depends on scope of the request)." } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — dsarId is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`MFA_STEPUP_REQUIRED` — fresh MFA step-up required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/dsar/restrict": { "post": { "operationId": "securityDsarRestrict", "summary": "Activate GDPR Art. 18 processing restriction", "description": "Pauses mutation of the authenticated caller's personal data (GDPR Art. 18 — right to restriction of processing). Storage and Art. 15 read access remain permitted. Downstream write stored procedures will reject with `PROCESSING_RESTRICTED` until the flag is lifted. Requires a fresh MFA step-up. The body is strict — unknown fields return `400`.", "tags": [ "Admin & Security" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_DsarRestrictRequest" } } } }, "responses": { "201": { "description": "Processing restriction activated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`MFA_STEPUP_REQUIRED` — fresh MFA step-up required, or `FORBIDDEN` — caller lacks the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/dsar/unrestrict": { "post": { "operationId": "securityDsarUnrestrict", "summary": "Lift GDPR Art. 18 processing restriction", "description": "Lifts the processing restriction for the caller themselves (self-path, omit `user_id`) or for another user (admin-path, supply `user_id` with `compliance.manage` permission). Per GDPR Art. 18(3), the data subject must be notified before lifting — this obligation is operational; the audit trail records `lifted_by_self`/`lifted_by_admin` for verification. Requires a fresh MFA step-up. Body is strict.", "tags": [ "Admin & Security" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_DsarUnrestrictRequest" } } } }, "responses": { "200": { "description": "Processing restriction lifted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`MFA_STEPUP_REQUIRED` or `FORBIDDEN` — caller lacks `compliance.manage` when targeting another user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/dsar/object": { "post": { "operationId": "securityDsarObject", "summary": "Register a GDPR Art. 21 processing objection", "description": "Records the authenticated data subject's objection to processing under a specific scope (or all scopes). Per-scope flags are stored on the user account; downstream handlers consult them and skip the processing. Requires a fresh MFA step-up. Compliance admins acting on behalf of third-party subjects must use the standard `POST /v1/security/dsar` workflow with `request_type='objection'`. Body is strict.", "tags": [ "Admin & Security" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_DsarObjectionRequest" } } } }, "responses": { "200": { "description": "Objection recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`MFA_STEPUP_REQUIRED` — fresh MFA step-up required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/emergency-access": { "post": { "operationId": "securityGrantEmergencyAccess", "summary": "Invoke break-glass emergency access", "description": "Grants time-limited emergency access to a specific resource (HIPAA 164.312(a)(2)(ii); SOC 2 CC6.1). A mandatory reason of at least 10 characters must be supplied. Creates an immutable critical-severity audit event. The grant is automatically revoked after `duration_minutes` (default 60, max 480). The body is strict — unknown fields are rejected.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_EmergencyAccessRequest" } } } }, "responses": { "201": { "description": "Emergency access granted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Emergency access grant details including grant ID and expiry." } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/consent/cookie": { "post": { "operationId": "securityRecordCookieConsent", "summary": "Record cookie consent decision", "description": "Records the authenticated user's cookie consent decision (GDPR Art. 6-7, ePrivacy Directive). Accepted categories: `necessary`, `analytics`, `marketing`, `preferences`. Body is strict.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_CookieConsentRequest" } } } }, "responses": { "201": { "description": "Cookie consent recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/consent/marketing": { "post": { "operationId": "securityRecordMarketingConsent", "summary": "Record marketing tracking consent", "description": "Records whether the user consents to having conversion data shared with external ad platforms (Meta, Google, Reddit, Bing). For EEA/UK/CH users this consent is required before any PII transfer to US-based platforms occurs (GDPR Art. 49).", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_MarketingConsentRequest" } } } }, "responses": { "201": { "description": "Marketing consent recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/consent/status": { "get": { "operationId": "securityGetConsentStatus", "summary": "Get current consent status", "description": "Returns the most recent consent records for the authenticated user by consent type.", "tags": [ "Admin & Security" ], "responses": { "200": { "description": "Consent records list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Consent records by type." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/parental-consent": { "post": { "operationId": "securityRecordParentalConsent", "summary": "Record parental consent (COPPA)", "description": "Records parental consent for a child user account (COPPA 16 CFR Part 312). Accepted verification methods: `email_verification`, `credit_card`, `phone_call`, `video_conference`, `government_id`.", "tags": [ "Admin & Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_ParentalConsentRequest" } } } }, "responses": { "201": { "description": "Parental consent recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/data-erasure-requests/{erasureRequestId}/execute": { "post": { "operationId": "securityExecuteDataErasure", "summary": "Execute an approved GDPR Art. 17 data erasure request", "description": "Performs an irreversible cascaded deletion of all personal data associated with the erasure request (GDPR Art. 17 — right to erasure). Requires `super_admin` privileges at the edge **and** `compliance.manage` permission at the SP level. Authorization is checked **before** any input validation to prevent enumeration by unauthorized callers — a non-super-admin always receives `403`, never `400` or `404`. The request body must be empty (`{}`); any additional fields return `400`. The request must be in `approved` state; other states return `422 INVALID_STATUS_TRANSITION`.", "tags": [ "Admin & Security" ], "parameters": [ { "name": "erasureRequestId", "in": "path", "required": true, "description": "Data erasure request UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "description": "Body must be empty (`{}`) — any additional fields are rejected.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Erasure executed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Erasure result including affected record counts." } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` — erasureRequestId is not a valid UUID (only returned to authorized callers). Or `VALIDATION_ERROR` — body contains unexpected fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller is not a `super_admin`. Returned before input validation to prevent enumeration by unauthorized callers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "`INVALID_STATUS_TRANSITION` — the erasure request is not in `approved` state, the target user is missing, or the cascade failed mid-flight.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/security/sbom.json": { "get": { "operationId": "securityGetSbom", "summary": "Get Software Bill of Materials", "description": "In production, returns a `302 Found` redirect to the canonical SBOM hosted at `trust.backbuild.ai`. In non-production environments, returns `202 Accepted` with a `Retry-After: 86400` header and `x-placeholder: true` indicating the artifact is not yet available.", "tags": [ "Admin & Security" ], "security": [], "responses": { "202": { "description": "SBOM not yet available (non-production). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying (86400 = 24 h)." }, "x-placeholder": { "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "available": { "type": "boolean", "enum": [ false ] } }, "additionalProperties": false } } } ] } } } }, "302": { "description": "Redirect to the canonical SBOM (production only).", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "URL of the canonical SBOM artifact." } } } } } }, "/v1/security/security.txt": { "get": { "operationId": "securityGetSecurityTxt", "summary": "RFC 9116 security.txt", "description": "Returns the `security.txt` file as per RFC 9116. Response content type is `text/plain; charset=utf-8`. Cached with `Cache-Control: public, max-age=3600`.", "tags": [ "Admin & Security" ], "security": [], "responses": { "200": { "description": "Security contact disclosure file.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Always `public, max-age=3600`." } }, "content": { "text/plain": { "schema": { "type": "string", "description": "RFC 9116 formatted security.txt content." } } } } } } }, "/v1/security/csp-report": { "post": { "operationId": "securityCspReport", "summary": "Receive a Content Security Policy report", "description": "Receives browser-generated CSP violation reports. Unauthenticated endpoint. Rate-limited to 100 requests per minute per IP address. Request body is capped at 16 KB (returns `413 PAYLOAD_TOO_LARGE` on oversize). Accepts `application/csp-report`, `application/reports+json`, and `application/json` content types. Returns `204 No Content` on success.", "tags": [ "Admin & Security" ], "security": [], "requestBody": { "required": true, "content": { "application/csp-report": { "schema": { "type": "object", "additionalProperties": true, "description": "CSP violation report document as defined by the Content Security Policy Level 2 specification." } }, "application/reports+json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Reporting API array of report objects." } }, "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "204": { "description": "Report received (no content returned)." }, "413": { "description": "`PAYLOAD_TOO_LARGE` — request body exceeds the 16 KB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Unsupported content type. Only `application/csp-report`, `application/reports+json`, and `application/json` are accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/mcp": { "post": { "operationId": "securityMcpDispatch", "summary": "MCP JSON-RPC 2.0 dispatch", "description": "Single endpoint that handles all MCP (Model Context Protocol) JSON-RPC 2.0 method calls. Every request body must be a valid JSON-RPC 2.0 object. Supported methods: `initialize`, `tools/list` (with optional `params.full=true`), `tools/call`, `resources/list`, `resources/read`, `ping`. Always returns HTTP `200` for well-formed JSON-RPC requests (including JSON-RPC-level errors per JSON-RPC 2.0 spec). Returns HTTP `401` for missing/invalid API keys, `429` for rate limit exceeded (fail-closed, returns 503 if the rate-limiter service itself is unavailable). OAuth-issued API keys with explicit scopes are supported; direct-mint (legacy) keys without explicit scopes receive a deprecation header in the response.\n\nAPI key format: `bb_live_<8-char-prefix>_<32-or-64-char-secret>` (hex or base64url).", "tags": [ "Admin & Security" ], "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_McpRequest" } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response (includes both successful results and JSON-RPC-level errors per the JSON-RPC 2.0 specification).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Security_McpResponse" } } } }, "401": { "description": "`AUTH_REQUIRED` — API key header is missing. Or `INVALID_API_KEY` — the key does not exist, is revoked, or has an invalid format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — per-key rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — rate-limiter service is unavailable (fail-closed per security policy).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/rbac/sync": { "post": { "operationId": "securitySyncRbac", "summary": "Sync RBAC state", "description": "Triggers a server-side reconciliation of the organization's RBAC state against the platform's system role-and-permission catalog. Requires organization admin privileges. Use this when role/permission drift is detected.", "tags": [ "Admin & Security" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Sync completed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Security_SyncResult" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` — caller is not an organization admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/projects/{projectId}/bbsheets": { "post": { "operationId": "sheetsSlidesCollaborationCreateSheet", "summary": "Create a BB Sheets spreadsheet", "description": "Atomically creates a spreadsheet catalog row and the backing `bb.bbsheet_documents` row via `api.bbsheet_create`, then grants the creating user WRITE access. After creation the spreadsheet is accessible via the grid WebSocket at `/v1/bbsheet/ws`. `org_id` is pinned from the session and is never accepted in the body. The body is strict — unknown keys are rejected with `VALIDATION_ERROR`. Requires the `documents` system feature flag.", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_CreateSheetRequest" }, "example": { "name": "Q2 Budget Tracker" } } } }, "responses": { "201": { "description": "Spreadsheet created. The full document record is returned under `data.document`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "document": { "oneOf": [ { "$ref": "#/components/schemas/SheetsSlidesCollaboration_DocumentRecord" }, { "type": "null" } ], "description": "The created spreadsheet document record." } } } } } ] } } } }, "400": { "description": "`INVALID_JSON` (unparseable body), `VALIDATION_ERROR` (a field failed schema validation; unknown keys are rejected by the strict schema), `INVALID_ID_FORMAT` (malformed projectId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (no `document.create` permission or project membership; enforced by the stored procedure).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project not found or not visible to caller).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` (duplicate spreadsheet in this project).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` (unrecognized SP error) or `INTERNAL_ERROR` (unexpected server error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/projects/{projectId}/bbsheets/{documentId}/comments": { "get": { "operationId": "sheetsSlidesCollaborationListSheetComments", "summary": "List spreadsheet cell comments", "description": "Returns all cell comments and their replies for the specified spreadsheet. Serves as the seed source for the client-side comment adapter; comments anchor to cell rectangles via packed integer coordinates. Authorization (project membership + effective spreadsheet READ access) is enforced entirely by `api.bbsheet_comments_list`.", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Spreadsheet document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "All comments (including replies) for the spreadsheet.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SheetComment" }, "description": "Cell comment threads with embedded replies." } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (malformed projectId or documentId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (no READ access to the spreadsheet).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project or document not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "sheetsSlidesCollaborationCreateSheetComment", "summary": "Create a cell comment on a spreadsheet", "description": "Creates a new comment thread anchored to a cell rectangle in the spreadsheet. The anchor is specified as two packed integer coordinates (`anchorFrom`/`anchorTo`) produced by the client's pure `cellAnchor` module. An optional client-provided `commentId` (UUID) is used as the database row id so the client list stays consistent. Authorization is enforced by `api.bbsheet_comment_create` via the `spreadsheet` effective-access gate. The body is strict — unknown keys are rejected.", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Spreadsheet document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_CreateSheetCommentRequest" } } } }, "responses": { "201": { "description": "Comment created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comment": { "oneOf": [ { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SheetComment" }, { "type": "null" } ] } } } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR` (body field failed validation or unknown key present), `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (no COMMENT access to the spreadsheet).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project or document not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` (duplicate commentId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` (unrecognized SP error) or `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/projects/{projectId}/bbsheets/{documentId}/comments/{commentId}": { "patch": { "operationId": "sheetsSlidesCollaborationResolveSheetComment", "summary": "Resolve or reopen a cell comment", "description": "Toggles the resolved state of a comment thread via `api.bbsheet_comment_resolve`. The body is strict — only `resolved` is accepted. Requires the comment author or an org admin role (enforced by the stored procedure).", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Spreadsheet document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "Comment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_ResolveCommentRequest" } } } }, "responses": { "200": { "description": "Comment updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comment": { "oneOf": [ { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SheetComment" }, { "type": "null" } ] } } } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR`, `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (not the comment author or an org admin).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project, document, or comment not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` (unrecognized SP error) or `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "sheetsSlidesCollaborationDeleteSheetComment", "summary": "Delete a cell comment thread", "description": "Deletes a comment thread and all its replies via `api.bbsheet_comment_delete`. Requires the comment author or an org admin role (enforced by the stored procedure).", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Spreadsheet document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "Comment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ], "description": "Always true on success." } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (malformed path parameter).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (not the comment author or an org admin).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project, document, or comment not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` (unrecognized SP error) or `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/projects/{projectId}/bbsheets/{documentId}/comments/{commentId}/replies": { "post": { "operationId": "sheetsSlidesCollaborationCreateSheetCommentReply", "summary": "Reply to a cell comment", "description": "Appends a reply to an existing comment thread via `api.bbsheet_comment_reply_create`. An optional client-provided `replyId` is used as the database row id. The body is strict — unknown keys are rejected.", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Spreadsheet document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "Parent comment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_CreateCommentReplyRequest" } } } }, "responses": { "201": { "description": "Reply created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "reply": { "oneOf": [ { "type": "object", "additionalProperties": true, "description": "The created reply record." }, { "type": "null" } ] } } } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR`, `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (no COMMENT access to the spreadsheet).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project, document, or comment not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` (duplicate replyId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` (unrecognized SP error) or `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/projects/{projectId}/bbsheets/{documentId}/comments/{commentId}/replies/{replyId}": { "delete": { "operationId": "sheetsSlidesCollaborationDeleteSheetCommentReply", "summary": "Delete a reply from a cell comment", "description": "Deletes a single reply from a comment thread via `api.bbsheet_comment_reply_delete`. Requires the reply author or an org admin role (enforced by the stored procedure).", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Spreadsheet document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "Parent comment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "replyId", "in": "path", "required": true, "description": "Reply identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reply deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (malformed path parameter).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (not the reply author or an org admin).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project, document, comment, or reply not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` (unrecognized SP error) or `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/projects/{projectId}/bbsheets/{documentId}/comments/{commentId}/assign": { "post": { "operationId": "sheetsSlidesCollaborationAssignSheetComment", "summary": "Assign a cell comment to an org member", "description": "Assigns a comment thread to an active organization member and optionally sends a notification via `api.bbsheet_comment_assign`. The assignee must be an existing org member (enforced by the stored procedure). The body is strict — unknown keys are rejected.", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Spreadsheet document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "Comment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_AssignCommentRequest" } } } }, "responses": { "200": { "description": "Comment assigned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comment": { "oneOf": [ { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SheetComment" }, { "type": "null" } ] }, "notified": { "type": "boolean", "description": "Whether the assignee was notified." } } } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR`, `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (no COMMENT access or insufficient permissions).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project, document, comment, or assignee not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` (unrecognized SP error) or `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/projects/{projectId}/bbsheets/{documentId}/comments/{commentId}/assignment-done": { "post": { "operationId": "sheetsSlidesCollaborationMarkSheetCommentAssignmentDone", "summary": "Mark a comment assignment as done", "description": "Marks the assignment task on a comment as completed via `api.bbsheet_comment_assignment_done`. Only the assignee or a project admin can perform this action (enforced by the stored procedure). No request body is required.", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" }, { "name": "documentId", "in": "path", "required": true, "description": "Spreadsheet document identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "description": "Comment identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Assignment marked done.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "comment": { "oneOf": [ { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SheetComment" }, { "type": "null" } ] } } } } } ] } } } }, "400": { "description": "`INVALID_ID_FORMAT` (malformed path parameter).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (not the assignee or a project admin).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project, document, or comment not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` (unrecognized SP error) or `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/projects/{projectId}/bbslides": { "post": { "operationId": "sheetsSlidesCollaborationCreateSlides", "summary": "Create a BB Slides deck", "description": "Atomically creates a presentation deck (catalog row with `content_type='application/x-bbslides'`), a backing `bb.bbprove_documents` row, and the owner WRITE grant via `api.bbslides_create`. The deck reuses the BB Docs editor and its CRDT transport lives at `/v1/yjs/ws`. `org_id` is pinned from the session and is never accepted in the body. The body is strict — unknown keys are rejected. Requires the `documents` system feature flag.", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "$ref": "#/components/parameters/ProjectIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_CreateSlidesRequest" }, "example": { "name": "Product Launch Deck" } } } }, "responses": { "201": { "description": "Deck created. The full document record is returned under `data.document`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "document": { "oneOf": [ { "$ref": "#/components/schemas/SheetsSlidesCollaboration_DocumentRecord" }, { "type": "null" } ] } } } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR` (body field failed or unknown key present), `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (no `document.create` permission or project membership).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (project not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`CONFLICT` (duplicate deck in this project).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`DATABASE_ERROR` (unrecognized SP error) or `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/bbsheet/ws": { "get": { "operationId": "sheetsSlidesCollaborationBbSheetWebSocket", "summary": "Open BB Sheets grid WebSocket", "description": "Upgrades to a WebSocket connection to the `BbSheetGridDO` for a specific spreadsheet. Authentication uses the full session JWT passed as a `?token=` query parameter (not the `Authorization` header — the browser WebSocket API cannot set custom headers). Unlike `POST /v1/collaboration/ticket`, there is no intermediate ticket exchange; the JWT is verified directly. The handler checks `token_version` revocation, runs the spreadsheet effective-access gate (`resolved_kind` must be `spreadsheet`), and derives the socket capability (`read`/`write`) from `can_write`. The Durable Object key is `bbsheet::`. The caller must send an `Upgrade: websocket` header.", "tags": [ "Sheets, Slides & Collaboration" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "A valid session JWT. Required because the browser WebSocket API cannot set `Authorization` headers.", "schema": { "type": "string", "minLength": 1 } }, { "name": "documentId", "in": "query", "required": true, "description": "Spreadsheet document identifier (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "101": { "description": "WebSocket upgrade accepted. The connection is forwarded to the `BbSheetGridDO`." }, "400": { "description": "`VALIDATION_ERROR` (missing or invalid query parameters) or 426 (missing `Upgrade: websocket` header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_TOKEN_INVALID` (JWT malformed or revoked) or `AUTH_TOKEN_EXPIRED` (JWT expired).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`PERMISSION_DENIED` (no read access, document is not a spreadsheet, or effective-access gate errored).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/bbsheet/{documentId}/export": { "get": { "operationId": "sheetsSlidesCollaborationExportSheet", "summary": "Export a spreadsheet", "description": "Streams a freshly materialized export artifact (SQLite, XLSX, CSV, or TSV) for a spreadsheet the caller can read. Authentication uses a JWT in the `token` query parameter (self-authenticating, like the WebSocket endpoint, because a browser anchor download cannot easily set `Authorization` headers). The handler verifies the JWT, checks `token_version` revocation, runs the effective-access gate (requires `resolved_kind=spreadsheet` and `can_read`), then drives the grid Durable Object export op and streams the decoded bytes. The response includes a `Content-Disposition: attachment` header. Exports are never cached (`Cache-Control: no-store`) and the content is bounded by the DO's the configured export-cell limit limit.", "tags": [ "Sheets, Slides & Collaboration" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "Spreadsheet document identifier (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "token", "in": "query", "required": true, "description": "A valid session JWT.", "schema": { "type": "string", "minLength": 1 } }, { "name": "format", "in": "query", "required": true, "description": "Export format.", "schema": { "type": "string", "enum": [ "sqlite", "xlsx", "csv", "tsv" ] } }, { "name": "sheet_id", "in": "query", "required": false, "description": "Zero-based sheet (tab) index. Required by the DO for `csv`/`tsv`; optional for `sqlite`/`xlsx`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "header_row", "in": "query", "required": false, "description": "Whether to include a header row in the export (`true` or `false`).", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "value_mode", "in": "query", "required": false, "description": "Whether to export displayed (formatted) or raw cell values. Defaults to `displayed`.", "schema": { "type": "string", "enum": [ "displayed", "raw" ] } }, { "name": "filename", "in": "query", "required": false, "description": "Optional base filename for the downloaded file (max 200 chars). Sanitized server-side; the extension is appended automatically.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Export artifact streamed as a binary file download.", "headers": { "Content-Disposition": { "description": "`attachment; filename=\"…\"; filename*=UTF-8''…`", "schema": { "type": "string" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.sqlite3": { "schema": { "type": "string", "format": "binary" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } }, "text/tab-separated-values": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "`VALIDATION_ERROR` (missing or invalid query parameters; export too large; unknown sheet), `INVALID_ID_FORMAT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_TOKEN_INVALID` or `AUTH_TOKEN_EXPIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`PERMISSION_DENIED` (no read access or document is not a spreadsheet).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/collaboration/ticket": { "post": { "operationId": "sheetsSlidesCollaborationIssueCollaborationTicket", "summary": "Exchange a JWT for a single-use collaboration WebSocket ticket", "description": "Exchanges a valid session JWT (supplied in the standard `Authorization: Bearer` header) for a cryptographically random, single-use, short-lived (60 s) ticket stored in KV. The ticket is then passed as `?ticket=` on the `/v1/collaboration/ws` WebSocket upgrade. This two-step flow is required because the browser WebSocket API does not support custom headers during the HTTP upgrade handshake. Token-version revocation is checked before the ticket is issued.", "tags": [ "Sheets, Slides & Collaboration" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_CollaborationTicketRequest" } } } }, "responses": { "200": { "description": "Ticket issued.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "ticket", "expiresInSeconds" ], "properties": { "ticket": { "type": "string", "description": "64-character hex-encoded single-use WebSocket ticket." }, "expiresInSeconds": { "type": "integer", "description": "Ticket TTL in seconds (60)." } } } } } ] } } } }, "401": { "description": "`AUTH_REQUIRED` (missing Authorization header), `AUTH_TOKEN_INVALID` (JWT malformed, revoked, or missing required claims), `AUTH_TOKEN_EXPIRED` (JWT expired).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/collaboration/ws": { "get": { "operationId": "sheetsSlidesCollaborationWebSocket", "summary": "Open collaboration WebSocket", "description": "Upgrades to a WebSocket connection to the `CollaborationDO` for the caller's organization. The preferred authentication path uses a single-use `?ticket=` obtained from `POST /v1/collaboration/ticket`. A deprecated fallback accepts a direct JWT as `?token=` (a deprecation warning is logged; this path will be removed in a future release). The DO key is `collab:`. The caller must send an `Upgrade: websocket` header.", "tags": [ "Sheets, Slides & Collaboration" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "ticket", "in": "query", "required": false, "description": "Single-use ticket obtained from `POST /v1/collaboration/ticket`. Preferred authentication path.", "schema": { "type": "string", "minLength": 1 } }, { "name": "token", "in": "query", "required": false, "description": "**Deprecated.** Session JWT passed directly in the query string. Will be removed in a future release.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "101": { "description": "WebSocket upgrade accepted. The connection is forwarded to the `CollaborationDO`." }, "400": { "description": "`VALIDATION_ERROR` (neither `ticket` nor `token` supplied, or the Upgrade header is missing).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_TOKEN_INVALID` (ticket invalid/expired, JWT malformed/revoked), `AUTH_TOKEN_EXPIRED` (JWT expired).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sync/config": { "get": { "operationId": "sheetsSlidesCollaborationGetSyncConfig", "summary": "Get organization offline sync configuration", "description": "Returns the organization's offline sync configuration, which determines which entity types are allowed for offline access. If no configuration exists, returns a default with an empty allowed-types list. Organization and RLS scope are derived from the access token.", "tags": [ "Sheets, Slides & Collaboration" ], "responses": { "200": { "description": "The organization sync configuration (or default).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SyncConfig" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "sheetsSlidesCollaborationUpdateSyncConfig", "summary": "Update organization offline sync configuration", "description": "Replaces the organization's offline sync configuration. Requires the `org.update` permission. Updates which entity types are permitted for offline sync and optional storage/interval caps. Per-org policy is enforced inside the stored procedures via `bb.org_sync_configs`.", "tags": [ "Sheets, Slides & Collaboration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_UpdateSyncConfigRequest" } } } }, "responses": { "200": { "description": "Updated sync configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SyncConfig" } } } ] } } } }, "400": { "description": "`INVALID_JSON` or `VALIDATION_ERROR` (invalid field value, out-of-range limit, or disallowed sync type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`PERMISSION_DENIED` (missing `org.update` permission).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sync/preferences": { "get": { "operationId": "sheetsSlidesCollaborationGetSyncPreferences", "summary": "Get user offline sync preferences", "description": "Returns the authenticated user's offline sync preferences within their current organization. If no preferences exist, returns defaults (empty enabled types, `auto_sync: true`, `sync_on_wifi_only: false`, `max_local_size_mb: 500`).", "tags": [ "Sheets, Slides & Collaboration" ], "responses": { "200": { "description": "The user's sync preferences (or defaults).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SyncPreferences" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "sheetsSlidesCollaborationUpdateSyncPreferences", "summary": "Update user offline sync preferences", "description": "Replaces the authenticated user's offline sync preferences. The requested `enabled_sync_types` must be a subset of the organization's `allowed_sync_types`; types not permitted by the org config are rejected with `VALIDATION_ERROR`.", "tags": [ "Sheets, Slides & Collaboration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_UpdateSyncPreferencesRequest" } } } }, "responses": { "200": { "description": "Updated sync preferences.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SyncPreferences" } } } ] } } } }, "400": { "description": "`INVALID_JSON`, `VALIDATION_ERROR` (field validation failure, or requested types not allowed by org config).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sync/{resourceType}": { "get": { "operationId": "sheetsSlidesCollaborationSyncPull", "summary": "Delta-sync pull for offline sync", "description": "Serves the offline sync engine's bulk download (omit `since`) and incremental changed-since pulls (`since` epoch-ms) with keyset pagination. Supports 6 resource types: `entities`, `relationships`, `documents`, `tasks`, `comments`, `specs`. Incremental items may carry `_deleted: true` tombstones so clients can evict rows. Response is camelCased to the client contract (`items`, `hasMore`, `nextCursor`, `watermark`).", "tags": [ "Sheets, Slides & Collaboration" ], "parameters": [ { "name": "resourceType", "in": "path", "required": true, "description": "The resource type to sync. Must be one of the 6 supported types; any other value is a 404.", "schema": { "type": "string", "enum": [ "entities", "relationships", "documents", "tasks", "comments", "specs" ] } }, { "name": "since", "in": "query", "required": false, "description": "Epoch milliseconds timestamp (non-negative integer up to 15 digits). When supplied, returns only records changed after this timestamp (incremental pull). Omit for a full bulk download.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return per page (1–500, default 500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Keyset pagination cursor in the format `:` (max 200 chars).", "schema": { "type": "string", "maxLength": 200 } }, { "name": "project_ids", "in": "query", "required": false, "description": "Comma-separated list of project UUIDs to filter by (max 50 IDs).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync page.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SyncPullResponse" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` (malformed `since`, `limit`, `cursor`, or `project_ids`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`FORBIDDEN` (offline sync is not enabled for this resource type in the org config).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`NOT_FOUND` (unknown resource type — not in the 6-type allowlist).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/preferences/offline-sync": { "get": { "operationId": "sheetsSlidesCollaborationGetOfflineSyncPreferences", "summary": "Get offline sync preferences (client shortcut)", "description": "Returns a simplified offline sync preferences summary derived from `api.sync_preferences_get`. This is a client-facing shortcut that normalizes the user's sync settings into a flat object (`enabled`, `max_items`, `sync_on_reconnect`, `storage_limit_mb`). On any database error it returns safe defaults rather than an error response, ensuring the client always has a usable baseline.", "tags": [ "Sheets, Slides & Collaboration" ], "responses": { "200": { "description": "Offline sync preferences summary (or safe defaults on error).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_OfflineSyncPreferencesSummary" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/yjs/ws": { "get": { "operationId": "sheetsSlidesCollaborationYjsWebSocket", "summary": "Open Yjs CRDT document WebSocket", "description": "Upgrades to a WebSocket connection to the `YjsDocDO` for a specific document. Used by BB Docs, BB Slides, and entity collaborative editing. Authentication is performed via the JWT in the `token` query parameter. The handler verifies the JWT, checks `token_version` revocation, and runs the `api.yjs_document_effective_access` gate to resolve the server-authoritative document kind (`bbprove_document` for BB Docs / BB Slides, or `entity`). The client-supplied `?docKind=` is intentionally ignored; the kind is resolved server-side to prevent doc-kind spoofing attacks. The derived capability (`read`/`write`) and access level are forwarded to the DO; the DO re-verifies on join. The DO key is `yjs::`.", "tags": [ "Sheets, Slides & Collaboration" ], "security": [ { "oneTimeTicket": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "A valid session JWT.", "schema": { "type": "string", "minLength": 1 } }, { "name": "documentId", "in": "query", "required": true, "description": "Document identifier (UUID). Used by both `bbprove_document` and `entity` kinds.", "schema": { "type": "string", "format": "uuid" } }, { "name": "docKind", "in": "query", "required": false, "description": "**Ignored by the server.** Accepted for backward-compatibility with existing clients but never trusted; the server resolves the document kind from `documentId`.", "schema": { "type": "string", "enum": [ "entity", "bbprove_document" ] } } ], "responses": { "101": { "description": "WebSocket upgrade accepted. The connection is forwarded to the `YjsDocDO`." }, "400": { "description": "`VALIDATION_ERROR` (missing or invalid query parameters, or missing `Upgrade: websocket` header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`AUTH_TOKEN_INVALID` (JWT malformed or revoked), `AUTH_TOKEN_EXPIRED` (JWT expired).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`PERMISSION_DENIED` (no read access, document not found under caller org, or effective-access gate errored fail-closed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/auth/sso/oidc/authorize": { "get": { "operationId": "sSOSCIMOidcAuthorize", "summary": "Initiate OIDC authorization", "description": "Begins an OIDC authorization-code flow with PKCE (S256). Performs OIDC discovery on the issuer, generates state/nonce/PKCE artifacts, stores HMAC-bound flow state (TTL 10 min), and redirects the user-agent to the IdP authorization endpoint. Rate-limited per client IP (20 req/60 s). On success the response is a `302 Found` redirect to the IdP — NOT a JSON body. Error conditions that are detectable before the redirect return a JSON error envelope. PUBLIC — no credentials required.", "tags": [ "SSO & SCIM" ], "security": [ {} ], "parameters": [ { "name": "config_id", "in": "query", "required": true, "description": "UUID of the SSO configuration to use (from POST /v1/auth/lookup).", "schema": { "type": "string", "format": "uuid" } }, { "name": "org_id", "in": "query", "required": true, "description": "Organization UUID that owns the SSO configuration.", "schema": { "type": "string", "format": "uuid" } }, { "name": "redirect_uri", "in": "query", "required": false, "description": "Optional post-login redirect URI within the allowed app origin. Silently ignored when it points to a disallowed domain (open-redirect prevention).", "schema": { "type": "string", "format": "uri" } } ], "responses": { "302": { "description": "Redirect to the IdP authorization endpoint." }, "400": { "description": "`VALIDATION_ERROR` — a query parameter failed validation. `SSO_CONFIG_INACTIVE` — the SSO configuration is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`SSO_CONFIG_NOT_FOUND` — the config_id/org_id pair does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — per-IP rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "description": "`SSO_DISCOVERY_FAILED` — OIDC discovery document could not be fetched from the IdP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — SSO service is misconfigured or temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/auth/sso/oidc/callback": { "get": { "operationId": "sSOSCIMOidcCallback", "summary": "OIDC IdP callback", "description": "Receives the browser redirect from the IdP after the user authenticates (authorization-code + state). Validates state, HMAC integrity, PKCE, and the ID token; completes the SSO login; then sets an HttpOnly `__Secure-bb_sso_pickup` cookie (TTL 60 s, path-scoped to `/v1/auth/sso/token-exchange`) and redirects the browser to `/auth/sso/complete?flow=pickup`. On MFA-required flows, redirects to `/auth/mfa/challenge` instead. Rate-limited. PUBLIC — no credentials required. On error, redirects to `/auth/sso/error?code=...&message=...` (browser redirect, not a JSON body).", "tags": [ "SSO & SCIM" ], "security": [ {} ], "parameters": [ { "name": "code", "in": "query", "required": false, "description": "Authorization code from the IdP.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "State parameter echoed by the IdP (bound to the stored flow state).", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "OAuth 2.0 error code sent by the IdP on failure.", "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "description": "Human-readable OAuth 2.0 error description from the IdP.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the frontend SSO completion page (success), MFA challenge page, or the SSO error page (failure). Error details are in `code` and `message` query parameters on the error redirect. The specific `error.code` values that may appear are: `SSO_CALLBACK_ERROR`, `SSO_STATE_INVALID`, `SSO_STATE_EXPIRED`, `SSO_TOKEN_VALIDATION_FAILED`, `SSO_CONFIG_NOT_FOUND`, `SSO_DISCOVERY_FAILED`, `SSO_LOGIN_FAILED`, `INTERNAL_ERROR`, `SERVICE_UNAVAILABLE`." } } } }, "/v1/auth/sso/token-exchange": { "post": { "operationId": "sSOSCIMOidcTokenExchange", "summary": "Exchange SSO one-time pickup cookie for auth tokens", "description": "Completes the SSO login by consuming the `__Secure-bb_sso_pickup` HttpOnly cookie set by the OIDC callback or SAML ACS handler. The cookie carries a single-use 64-hex-char exchange code (TTL 60 s). The endpoint requires an exact-origin `Origin` header (CSRF protection), clears the cookie on read, and returns the access/refresh tokens in the same envelope shape as `POST /v1/auth/login`. Rate-limited per client IP. PUBLIC — no credentials required (the cookie IS the credential).", "tags": [ "SSO & SCIM" ], "security": [ {} ], "requestBody": { "required": false, "description": "No body required. The exchange code is read from the `__Secure-bb_sso_pickup` HttpOnly cookie.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Tokens issued. The `isNewUser` field is intentionally omitted to prevent account enumeration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_TokenExchangeResponse" } } } ] } } } }, "400": { "description": "`SSO_TOKEN_EXCHANGE_INVALID` — cookie is missing, malformed, or the code format is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`SSO_TOKEN_EXCHANGE_INVALID` — the exchange code is expired or has already been consumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`SSO_TOKEN_EXCHANGE_INVALID` — `Origin` header is missing, malformed, or does not match the allowed app origin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — per-IP rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — SSO service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/auth/sso/saml/login": { "get": { "operationId": "sSOSCIMSamlLogin", "summary": "Initiate SAML SP-initiated SSO", "description": "Begins a SAML 2.0 SP-initiated authentication flow. Loads the SAML configuration (decrypting the SP signing key if present), builds a signed `AuthnRequest` (HTTP-Redirect binding), stores HMAC-bound flow state (TTL 10 min), and redirects the user-agent to the IdP SSO URL. Rate-limited per client IP. PUBLIC — no credentials required.", "tags": [ "SSO & SCIM" ], "security": [ {} ], "parameters": [ { "name": "config_id", "in": "query", "required": true, "description": "UUID of the SAML SSO configuration.", "schema": { "type": "string", "format": "uuid" } }, { "name": "org_id", "in": "query", "required": true, "description": "Organization UUID that owns the SAML configuration.", "schema": { "type": "string", "format": "uuid" } }, { "name": "redirect_uri", "in": "query", "required": false, "description": "Optional post-login redirect URI within the allowed app origin.", "schema": { "type": "string", "format": "uri" } } ], "responses": { "302": { "description": "Redirect to the IdP SSO URL." }, "400": { "description": "`VALIDATION_ERROR` — a query parameter failed validation. `SSO_CONFIG_NOT_FOUND` — config not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — per-IP rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — SSO service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/auth/sso/saml/acs": { "post": { "operationId": "sSOSCIMSamlAcs", "summary": "SAML Assertion Consumer Service (ACS)", "description": "Receives the SAML Response from the IdP via HTTP-POST binding (`application/x-www-form-urlencoded` body with `SAMLResponse` + `RelayState`). Validates the response: XML signature, assertion expiry, audience, replay protection (per-org assertion ID table), and optional MFA context class. On success, sets the `__Secure-bb_sso_pickup` HttpOnly cookie and redirects to `/auth/sso/complete?flow=pickup`. On MFA-required flows, redirects to `/auth/mfa/challenge`. On error, redirects to `/auth/sso/error`. Rate-limited. Body size capped at 512 KB. PUBLIC — no credentials required.", "tags": [ "SSO & SCIM" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SSOSCIM_SamlAcsBody" } } } }, "responses": { "302": { "description": "Redirect to the SSO completion page, MFA challenge page, or error page. Error codes on the error redirect: `SAML_RESPONSE_INVALID`, `SSO_STATE_INVALID`, `SSO_STATE_EXPIRED`, `SAML_SIGNATURE_INVALID`, `SAML_ASSERTION_EXPIRED`, `SAML_AUDIENCE_MISMATCH`, `SAML_REPLAY_DETECTED`, `SSO_LOGIN_FAILED`, `SSO_CALLBACK_ERROR`, `SERVICE_UNAVAILABLE`." } } } }, "/v1/auth/sso/saml/slo": { "post": { "operationId": "sSOSCIMSamlSlo", "summary": "SAML Single Logout (IdP-initiated)", "description": "Receives a `SAMLRequest` (LogoutRequest) from the IdP via HTTP-POST binding. Validates the XML signature against the configured IdP certificate, checks IssueInstant freshness (-5 min .. +1 min window), enforces KV-backed replay protection (10 min TTL), looks up and revokes the target user's session(s) (by SessionIndex when present, by global opt-in fallback when not), and returns an auto-submitting HTML form that POSTs the signed `SAMLResponse` back to the IdP SLO endpoint. Rate-limited (5 req/min/IP). Body capped at 512 KB. Requires `config_id` form field (UUID) so the org can be resolved. PUBLIC — no credentials required (the SAML XML signature IS the credential).", "tags": [ "SSO & SCIM" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SSOSCIM_SamlSloBody" } } } }, "responses": { "200": { "description": "HTML auto-submit form that POSTs the SAML LogoutResponse back to the IdP.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request — missing/invalid `SAMLRequest`, missing/invalid `config_id`, IssueInstant out of window, issuer mismatch, XML parse error, or signature verification failed. Response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "The SAMLRequest ID has already been processed (replay protection). Response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds 512 KB limit. Response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "Per-IP rate limit exceeded (5 req/min). Response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Server error — SP signing key not configured or SLO URL missing. Response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "SSO service temporarily unavailable. Response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/auth/sso/saml/metadata/{configId}": { "get": { "operationId": "sSOSCIMSamlMetadata", "summary": "Serve SAML SP metadata XML", "description": "Returns the SP metadata XML (`application/samlmetadata+xml`) for the given SAML configuration. IdP administrators import this document to configure the trust relationship. The `org_id` query parameter is required to scope the config lookup and prevent enumeration. Responds with `404 SSO_CONFIG_NOT_FOUND` for any failure (including unknown org, wrong config, or a non-SAML config type) to prevent enumeration. Rate-limited per IP and per tenant config. Cached 1 hour (`Cache-Control: public, max-age=3600`). PUBLIC — no credentials required.", "tags": [ "SSO & SCIM" ], "security": [ {} ], "parameters": [ { "name": "configId", "in": "path", "required": true, "description": "UUID of the SAML SSO configuration.", "schema": { "type": "string", "format": "uuid" } }, { "name": "org_id", "in": "query", "required": true, "description": "Organization UUID that owns the SAML configuration (required to scope the lookup).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SAML SP metadata XML document.", "content": { "application/samlmetadata+xml": { "schema": { "type": "string" } } } }, "404": { "description": "`SSO_CONFIG_NOT_FOUND` — config not found, org_id missing, or any other failure (responses are uniform to prevent enumeration).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded (per-IP or per-config tenant limit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sso/configs": { "post": { "operationId": "sSOSCIMCreateSsoConfig", "summary": "Create SSO configuration", "description": "Creates a new SAML or OIDC SSO configuration for the caller's organization. `provider_config` is an object whose keys must be from the platform allowlist (unknown keys are rejected with `VALIDATION_ERROR` naming the offending key). For OIDC, the `issuer` URL is validated against the SSRF blocklist. For SAML, the `sso_url` is similarly validated. Per-org quota: maximum 50 SSO configs. Secrets (e.g., `client_secret_ref`, `sp_signing_key_ref`) must be pre-encrypted references — raw secrets are never accepted. Returns the created config with sensitive fields redacted. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_CreateSsoConfigRequest" } } } }, "responses": { "201": { "description": "SSO configuration created. Provider config is returned with secrets redacted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_SsoConfig" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — a field failed validation, unknown `provider_config` keys, SSRF-blocked URL, or `BILLING_PLAN_LIMIT_REACHED` — 50-config org quota exceeded. `INVALID_JSON` — body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`PERMISSION_DENIED` or `FORBIDDEN` — missing `identity.manage` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "sSOSCIMListSsoConfigs", "summary": "List SSO configurations", "description": "Returns the SSO configurations for the caller's organization, with optional filtering by `auth_method` and `is_active`. Paginated (default page 1, page_size 25, max 100). Provider config fields are redacted (secrets and key references are replaced with presence flags). Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "auth_method", "in": "query", "required": false, "description": "Filter by SSO protocol (`saml` or `oidc`).", "schema": { "type": "string", "enum": [ "saml", "oidc" ] } }, { "name": "is_active", "in": "query", "required": false, "description": "Filter by active status (`true` or `false` as strings).", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based, default 1).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (1-100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "List of SSO configurations (secrets redacted).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SSOSCIM_SsoConfig" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sso/configs/{id}": { "put": { "operationId": "sSOSCIMUpdateSsoConfig", "summary": "Update SSO configuration", "description": "Updates an existing SSO configuration. All fields are optional; supply only the fields to change. Unknown `provider_config` keys are rejected. SSRF-blocked URLs are rejected. When `is_active` is set to `false`, all sessions authenticated via this config are force-revoked (session cascade); if revocation fails the update returns `500` and the caller should retry. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the SSO configuration to update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_UpdateSsoConfigRequest" } } } }, "responses": { "200": { "description": "Updated SSO configuration (secrets redacted).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_SsoConfig" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — invalid UUID path param, unknown `provider_config` key, SSRF-blocked URL, or body parse failure. `INVALID_JSON` — body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SSO_CONFIG_NOT_FOUND` — the configuration does not exist or belongs to another org.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`INTERNAL_ERROR` — includes the case where the config was disabled but session revocation failed (safe to retry).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "sSOSCIMDeleteSsoConfig", "summary": "Delete SSO configuration", "description": "Deletes an SSO configuration. Force-revokes all sessions authenticated via this config BEFORE deleting the row (so sessions can be located by `sso_config_id`). If revocation fails the deletion is aborted and the caller receives `500` (safe to retry). Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the SSO configuration to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Configuration deleted. `revoked_sessions` is the number of sessions that were force-revoked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "revoked_sessions": { "type": "integer", "description": "Number of active sessions that were force-revoked before deletion." } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — config ID is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SSO_CONFIG_NOT_FOUND` — not found or belongs to another org.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`INTERNAL_ERROR` — session revocation failed; the config was NOT deleted. Retry is safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sso/configs/import-oidc": { "post": { "operationId": "sSOSCIMImportOidcConfig", "summary": "Import OIDC configuration from discovery URL", "description": "Fetches the OIDC discovery document from `/.well-known/openid-configuration`, validates all discovered endpoint URLs (SSRF protection + issuer-origin match per OIDC Discovery), encrypts the `client_secret` using a platform-managed key, and persists a new OIDC SSO configuration with `is_active=true`. Returns the created config with the secret redacted. Redirects are followed manually (per-hop SSRF re-check). Timeout: 10 s. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ImportOidcRequest" } } } }, "responses": { "201": { "description": "OIDC configuration created from discovery document.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_SsoConfig" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — body failed validation, SSRF-blocked URL, issuer-origin mismatch, or discovery document missing required fields. `INVALID_JSON` — body is not valid JSON. `SSO_DISCOVERY_FAILED` — discovery document is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "description": "`SSO_DISCOVERY_FAILED` — the discovery endpoint returned an error status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`SERVICE_UNAVAILABLE` — encryption service (a platform-managed key) not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "`TIMEOUT` — the OIDC discovery request timed out (10 s).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sso/configs/import-saml": { "post": { "operationId": "sSOSCIMImportSamlConfig", "summary": "Import SAML configuration from IdP metadata URL", "description": "Fetches the IdP metadata XML from `metadata_url`, parses SSO URL / entity ID / certificate / NameID formats / SLO URL, and persists a new SAML SSO configuration. The SP entity ID and ACS URL are derived from the API base URL. Redirects followed manually (per-hop SSRF check). Timeout: 10 s. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ImportSamlRequest" } } } }, "responses": { "201": { "description": "SAML configuration created from IdP metadata.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_SsoConfig" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — body failed validation or SSRF-blocked URL. `SAML_RESPONSE_INVALID` — metadata XML is malformed. `INVALID_JSON` — body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "description": "`SSO_DISCOVERY_FAILED` — the metadata endpoint returned an error status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "504": { "description": "`TIMEOUT` — the metadata fetch timed out (10 s).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sso/configs/{id}/test": { "post": { "operationId": "sSOSCIMTestSsoConfig", "summary": "Test SSO configuration connectivity", "description": "Performs a live connectivity test against the SSO configuration: for OIDC, fetches the discovery document and checks the JWKS endpoint; for SAML, fetches and validates the metadata XML and checks certificate presence. Returns a `200` with `status: 'ok'` or `status: 'error'` in the `data` payload regardless of the underlying reachability result (test results never cause a non-2xx status). Auth and validation failures still produce non-200 responses. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the SSO configuration to test.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Test completed. `data.status` is `ok` when connectivity checks passed, `error` when any check failed. `data.details` contains per-check results.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_SsoTestResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — config ID is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`SSO_CONFIG_NOT_FOUND` — configuration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sso/identities": { "get": { "operationId": "sSOSCIMListSsoIdentities", "summary": "List linked SSO identities", "description": "Returns the SSO identity records (IdP subject bindings) for users in the caller's organization. Filterable by `provider` string and `user_id`. Paginated. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "provider", "in": "query", "required": false, "description": "Filter by provider identifier string (max 200 chars).", "schema": { "type": "string", "maxLength": 200 } }, { "name": "user_id", "in": "query", "required": false, "description": "Filter by user UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based, default 1).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (1-100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated list of SSO identity records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SSOSCIM_SsoIdentity" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sso/identities/{id}": { "delete": { "operationId": "sSOSCIMDeleteSsoIdentity", "summary": "Unlink SSO identity", "description": "Removes an SSO identity record (IdP subject binding) from the organization. The user account itself is NOT deleted; only the IdP link is removed. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the SSO identity record to unlink.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Identity unlinked.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — identity ID is not a valid UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — identity record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sso/domains": { "post": { "operationId": "sSOSCIMCreateDomainMapping", "summary": "Create email domain mapping", "description": "Maps an email domain to an authentication method (and optionally an SSO config). The domain is normalized to canonical Punycode form. Public/consumer email domains (gmail.com, outlook.com, etc.) are rejected. Per-org quota: 100 domains. After creation, the domain is unverified — call `POST /v1/sso/domains/{domain}/verify` to verify via DNS TXT record. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_CreateDomainRequest" } } } }, "responses": { "201": { "description": "Domain mapping created (unverified). Response includes `verification_token` which must be published as `_backbuild-verify.` TXT record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_DomainMapping" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — body failed validation, domain normalization error, public email provider, or `BILLING_PLAN_LIMIT_REACHED` — 100-domain org quota exceeded. `INVALID_JSON` — body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`CONFLICT` — domain is already mapped to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — domain quota check failed (KV unavailable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "sSOSCIMListDomainMappings", "summary": "List email domain mappings", "description": "Returns the email domain mappings for the caller's organization, paginated. The response includes `rows`, `page`, `page_size`, `total`, and `total_pages` inside `data`. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number (1-based, default 1).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Records per page (1-100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated domain mappings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_DomainListPage" } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sso/domains/{domain}": { "delete": { "operationId": "sSOSCIMDeleteDomainMapping", "summary": "Delete email domain mapping", "description": "Removes an email domain mapping. The `domain` path parameter is URL-decoded and normalized to Punycode before lookup. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain name to remove (URL-encoded if it contains special characters, max 253 chars).", "schema": { "type": "string", "maxLength": 253 } } ], "responses": { "200": { "description": "Domain mapping deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — domain is empty, exceeds 253 chars, or normalization failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — domain mapping not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/sso/domains/{domain}/verify": { "post": { "operationId": "sSOSCIMVerifyDomain", "summary": "Verify email domain via DNS TXT record", "description": "Performs a DNS TXT record lookup (via Cloudflare DoH) for `_backbuild-verify.` and compares the observed value against the stored token. The SP persists the verification result (audit-logged). Rate-limited: 10 attempts per (org, domain) per 10 minutes. If already verified, returns success immediately without re-querying DNS. On mismatch, returns `400` with `details.record_name` and `details.record_type` for the caller's reference. Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain to verify (max 253 chars, must match an existing domain mapping).", "schema": { "type": "string", "maxLength": 253 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Verification succeeded. `data.is_verified` is `true`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_DomainVerifyResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — domain is invalid, normalization failed, or DNS TXT record was not found or did not match. The `error.details` contains `record_name`, `record_type`, and a propagation hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — domain mapping does not exist for this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — 10 verification attempts per (org, domain) per 10 minutes exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — KV rate-limiter unavailable (fail-closed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sso/domains/{domain}/regenerate-token": { "post": { "operationId": "sSOSCIMRegenerateDomainToken", "summary": "Rotate domain verification token", "description": "Rotates the DNS verification token for a domain mapping. Sets `is_verified = false` and clears `verified_at` (but preserves `last_verified_at` for audit history). The org must re-publish the new token as a DNS TXT record and call `POST /v1/sso/domains/{domain}/verify` again. Rate-limited: 3 rotations per (org, domain) per 24 hours (fail-closed if KV is unavailable). Requires `identity.manage` permission.", "tags": [ "SSO & SCIM" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain whose token to rotate (max 253 chars).", "schema": { "type": "string", "maxLength": 253 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "New verification token issued. `data.verification_token` is the new token to publish as `_backbuild-verify.` TXT record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SSOSCIM_DomainTokenRotateResult" } } } ] } } } }, "400": { "description": "`VALIDATION_ERROR` — domain is invalid or normalization failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "`NOT_FOUND` — domain mapping not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — 3 rotations per domain per 24 hours exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "`SERVICE_UNAVAILABLE` — KV rate-limiter unavailable (fail-closed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/scim/v2/ServiceProviderConfig": { "get": { "operationId": "sSOSCIMScimServiceProviderConfig", "summary": "SCIM ServiceProviderConfig (discovery)", "description": "Returns the SCIM 2.0 ServiceProviderConfig document describing platform capabilities: filter support (`maxResults=200`), patch support, no bulk/sort/changePassword. Used by IdP onboarding tooling to discover capabilities. PUBLIC — no credentials required. Rate-limited: 60 req/min/IP.", "tags": [ "SSO & SCIM" ], "security": [ {} ], "responses": { "200": { "description": "SCIM ServiceProviderConfig document.", "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Per-IP rate limit exceeded (60 req/min).", "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/scim/v2/ResourceTypes": { "get": { "operationId": "sSOSCIMScimResourceTypes", "summary": "SCIM ResourceTypes (discovery)", "description": "Returns the list of SCIM resource types supported by the platform. Only the `User` resource type is advertised (Group provisioning is not implemented). PUBLIC — no credentials required. Rate-limited: 60 req/min/IP.", "tags": [ "SSO & SCIM" ], "security": [ {} ], "responses": { "200": { "description": "SCIM ListResponse containing the User resource type.", "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Per-IP rate limit exceeded.", "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/scim/v2/Schemas": { "get": { "operationId": "sSOSCIMScimSchemas", "summary": "SCIM Schemas (discovery)", "description": "Returns the SCIM schema definitions for the User resource type (RFC 7643 subset: `userName`, `externalId`, `displayName`, `active`, `name.givenName`, `name.familyName`, `name.formatted`, `emails`). PUBLIC — no credentials required. Rate-limited: 60 req/min/IP.", "tags": [ "SSO & SCIM" ], "security": [ {} ], "responses": { "200": { "description": "SCIM ListResponse containing the User schema definition.", "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Per-IP rate limit exceeded.", "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/scim/v2/Users": { "post": { "operationId": "sSOSCIMScimCreateUser", "summary": "SCIM: Create user", "description": "Provisions a new user in the organization bound to the SCIM bearer token. `userName` (email) is required and lowercased. The primary email (from `emails[primary=true].value` or `userName`) must pass RFC 5321 format validation (rejects control bytes, BIDI overrides, malformed structure). `active` defaults to `true`. All write operations are audit-logged. Returns `201 Created` with `Location` header. Requires a valid `scimToken` bearer token.", "tags": [ "SSO & SCIM" ], "security": [ { "scimToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimUserCreateRequest" } } } }, "responses": { "201": { "description": "User created. `Location` header contains the canonical URL.", "headers": { "Location": { "description": "Canonical SCIM user URL.", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimUser" } } } }, "400": { "description": "SCIM error `invalidSyntax` — body is not valid JSON. `invalidValue` — `userName` missing or primary email fails RFC 5321 validation.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "401": { "description": "SCIM bearer token missing, malformed, revoked, or expired (`SCIM_UNAUTHORIZED`).", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "409": { "description": "SCIM error `uniqueness` — a user with this `userName` or `externalId` already exists in the organization.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "429": { "description": "SCIM rate limit exceeded (1000 req/min per token).", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "500": { "description": "Server error.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } } } }, "get": { "operationId": "sSOSCIMScimListUsers", "summary": "SCIM: List / search users", "description": "Returns a SCIM ListResponse of users in the bound organization. Supports a narrow filter grammar: `userName eq \"\"`, `externalId eq \"\"`, `id eq \"\"`, and ` and `. Filters outside this grammar are rejected with `invalidFilter`. `startIndex` is 1-based (max 10 000). `count` defaults to 100 and is capped at 200. Requires `scimToken` bearer.", "tags": [ "SSO & SCIM" ], "security": [ { "scimToken": [] } ], "parameters": [ { "name": "filter", "in": "query", "required": false, "description": "SCIM filter expression (narrow grammar: `userName eq`, `externalId eq`, `id eq`, and AND of two). Anything outside this grammar is rejected as `invalidFilter`.", "schema": { "type": "string" } }, { "name": "startIndex", "in": "query", "required": false, "description": "1-based start index for pagination (max 10 000, default 1).", "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } }, { "name": "count", "in": "query", "required": false, "description": "Number of results to return (default 100, max 200).", "schema": { "type": "integer", "minimum": 0, "maximum": 200 } } ], "responses": { "200": { "description": "SCIM ListResponse.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimListResponse" } } } }, "400": { "description": "SCIM error `invalidFilter` — filter is outside the supported grammar. `tooMany` — `startIndex` exceeds 10 000.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "401": { "description": "SCIM bearer token invalid or expired.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "429": { "description": "SCIM rate limit exceeded.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "500": { "description": "Server error.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } } } } }, "/v1/scim/v2/Users/{id}": { "get": { "operationId": "sSOSCIMScimGetUser", "summary": "SCIM: Get user", "description": "Returns the SCIM User resource for the given user UUID. Returns `404` (SCIM error envelope) for non-UUID IDs or unknown users. Requires `scimToken` bearer.", "tags": [ "SSO & SCIM" ], "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User UUID (UUIDv4/v7).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The SCIM User resource.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimUser" } } } }, "401": { "description": "SCIM bearer token invalid.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "404": { "description": "User not found (also returned for non-UUID `id` values).", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "429": { "description": "SCIM rate limit exceeded.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "500": { "description": "Server error.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } } } }, "put": { "operationId": "sSOSCIMScimReplaceUser", "summary": "SCIM: Replace user (full update)", "description": "Full-replace of a SCIM User resource. `userName` is immutable — it cannot be changed via PUT. Updatable fields: `displayName`, `name.givenName`, `name.familyName`, `active`. Setting `active=false` triggers session revocation inside the SP. The response reflects what the SP actually persisted (re-fetched after update). Requires `scimToken` bearer.", "tags": [ "SSO & SCIM" ], "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimUserPutRequest" } } } }, "responses": { "200": { "description": "Updated SCIM User resource.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimUser" } } } }, "400": { "description": "SCIM error `invalidSyntax` — body is not valid JSON.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "401": { "description": "SCIM bearer token invalid.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "404": { "description": "User not found.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "429": { "description": "SCIM rate limit exceeded.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "500": { "description": "Server error.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } } } }, "patch": { "operationId": "sSOSCIMScimPatchUser", "summary": "SCIM: Patch user (partial update)", "description": "Applies a SCIM PATCH (`Operations` array) to the user. Only `op: \"replace\"` is supported. Supported paths: `active`, `displayName`, `name.givenName`, `name.familyName`, `emails[primary eq true].value` (no-op — `userName` is immutable). Maximum 100 operations per request. Setting `active=false` triggers session revocation. Audit-logged. Requires `scimToken` bearer.", "tags": [ "SSO & SCIM" ], "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimPatchRequest" } } } }, "responses": { "200": { "description": "Updated SCIM User resource (re-fetched from DB).", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimUser" } } } }, "400": { "description": "SCIM error `invalidSyntax` — body not valid JSON or `Operations` is empty/not an array. `tooMany` — more than 100 operations. `invalidPath` — unsupported PATCH path. `invalidValue` — invalid field value. `mutability` — attempt to mutate an immutable field (`userName`).", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "401": { "description": "SCIM bearer token invalid.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "404": { "description": "User not found.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "429": { "description": "SCIM rate limit exceeded.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "500": { "description": "Server error.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } } } }, "delete": { "operationId": "sSOSCIMScimDeleteUser", "summary": "SCIM: Deprovision user", "description": "Removes the user from the organization and revokes all their active sessions. Returns `204 No Content` with no body on success, per RFC 7644. Audit-logged. Requires `scimToken` bearer.", "tags": [ "SSO & SCIM" ], "security": [ { "scimToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "User deprovisioned. No response body." }, "401": { "description": "SCIM bearer token invalid.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "404": { "description": "User not found.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "429": { "description": "SCIM rate limit exceeded.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } }, "500": { "description": "Server error.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/SSOSCIM_ScimError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Session access token (JWT) issued by `/v1/auth/login`, `/v1/auth/refresh`, or the SSO/OAuth flows. Supplied as `Authorization: Bearer `. The token is bound to a user, organization, and active environment; the API re-scopes the database session for Row-Level-Security on every request." }, "apiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "Organization API key, supplied as `Authorization: Bearer bb_live_`. Used by machine clients (MCP, CLI publish pipelines, vision/document-publish callers, CI security-scan ingest, deploy containers). Each key carries a scope set; routes that require a particular scope reject keys lacking it with `API_KEY_SCOPE_DENIED`." }, "scimToken": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "Per-organization SCIM 2.0 bearer token issued to an Identity Provider for user provisioning/deprovisioning against `/v1/scim/v2/*`. Not a user JWT; invalid/expired tokens return `SCIM_UNAUTHORIZED`." }, "containerDataToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Short-TTL Ed25519-signed container DATA token (verified offline against the JWKS at `/v1/containers/.well-known/jwks.json`). Presented by the in-container agent/gateway on the container data-plane (`/v1/containers/data/*`, `/v1/containers/internal/*`). Bound to a single (sub, sid); never a user JWT." }, "oneTimeTicket": { "type": "apiKey", "in": "query", "name": "token", "description": "Single-use connection ticket passed as a `?token=` query parameter on WebSocket upgrades (realtime collaboration `/v1/yjs/ws`, mailbox `/v1/bbmail/ws`, file bridge, RDP signaling). Minted by an authenticated REST call, redeemable once, short-lived — it is NOT a bearer token and grants only the single channel it was minted for." }, "webhookSignature": { "type": "apiKey", "in": "header", "name": "Signature", "description": "Provider-specific HMAC/RSA signature header verified inside the handler before any work (e.g. `Stripe-Signature`, `svix-signature` for Resend, AWS SNS RSA signature, `x-hub-signature-256` for GitHub deploy). These endpoints take no JWT; the signature IS the credential. The exact header name varies per provider and is noted on each operation." } }, "parameters": { "OrgIdPath": { "name": "orgId", "in": "path", "required": true, "description": "Organization identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, "ProjectIdPath": { "name": "projectId", "in": "path", "required": true, "description": "Project identifier (UUIDv7).", "schema": { "type": "string", "format": "uuid" } }, "LimitQuery": { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return. Default and ceiling are endpoint-specific (commonly default 25–50, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, "OffsetQuery": { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip for offset pagination.", "schema": { "type": "integer", "minimum": 0 } } }, "schemas": { "SuccessEnvelope": { "type": "object", "required": [ "success" ], "description": "Standard success envelope. `data` carries the endpoint-specific payload.", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "description": "Endpoint-specific payload." }, "requestId": { "type": "string", "format": "uuid", "description": "Correlation id echoed for tracing (present on some endpoints)." } } }, "ErrorEnvelope": { "type": "object", "required": [ "success", "error" ], "description": "Standard error envelope returned for every non-2xx response.", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "description": "Human-readable description. Database-derived messages are sanitized to avoid leaking internals." }, "details": { "type": "object", "additionalProperties": true, "description": "Optional structured context (e.g. failing fields)." } } } } }, "PaginationMeta": { "type": "object", "description": "Pagination metadata. Endpoints use either page/pageSize or limit/offset style; fields present depend on the endpoint.", "properties": { "total": { "type": "integer", "description": "Total records matching the query before pagination." }, "page": { "type": "integer", "description": "Current 1-based page (page/pageSize style)." }, "pageSize": { "type": "integer", "description": "Records per page (page/pageSize style)." }, "totalPages": { "type": "integer", "description": "Total pages available (page/pageSize style)." }, "limit": { "type": "integer", "description": "Requested limit (limit/offset style)." }, "offset": { "type": "integer", "description": "Requested offset (limit/offset style)." }, "has_more": { "type": "boolean", "description": "Whether more records exist beyond this page (limit/offset style)." } } }, "ErrorCode": { "type": "string", "description": "Canonical machine-readable error codes returned in `error.code`. Codes follow `DOMAIN_SPECIFIC_ERROR` and map to an HTTP status as grouped here. Mirrors `ErrorCodes` in `src/types/api.ts`.", "enum": [ "AUTH_REQUIRED", "UNAUTHORIZED", "AUTH_TOKEN_EXPIRED", "AUTH_TOKEN_INVALID", "AUTH_REFRESH_TOKEN_INVALID", "AUTH_SESSION_EXPIRED", "AUTH_INVALID_CREDENTIALS", "AUTH_ACCOUNT_LOCKED", "AUTH_EMAIL_NOT_VERIFIED", "AUTH_OAUTH_FAILED", "AUTH_MFA_REQUIRED", "AUTH_MFA_INVALID", "AUTH_MFA_TOKEN_EXPIRED", "MFA_JWT_REPLAY", "TOKEN_REVOKED", "SESSION_IDLE_TIMEOUT", "SESSION_INVALID", "MFA_VERIFICATION_REQUIRED", "MFA_ALREADY_ENROLLED", "INVALID_API_KEY", "API_KEY_SCOPE_DENIED", "DATABASE_UNAVAILABLE", "PERMISSION_DENIED", "FORBIDDEN", "TARGET_NOT_ELIGIBLE", "REAUTH_REQUIRED", "MFA_STEPUP_REQUIRED", "ORG_MEMBERSHIP_REQUIRED", "ORG_ADMIN_REQUIRED", "INSUFFICIENT_PERMISSIONS", "TENANT_ACCESS_DENIED", "TENANT_NOT_FOUND", "FEATURE_DISABLED", "VALIDATION_ERROR", "MISSING_REQUIRED_FIELD", "INVALID_FIELD_VALUE", "INVALID_JSON", "INVALID_ID_FORMAT", "INVALID_PARAMETER", "PAYLOAD_TOO_LARGE", "CONTENT_POLICY_VIOLATION", "NOT_FOUND", "PROJECT_NOT_FOUND", "TASK_NOT_FOUND", "SPEC_NOT_FOUND", "PHASE_NOT_FOUND", "CATEGORY_NOT_FOUND", "USER_NOT_FOUND", "ORG_NOT_FOUND", "SESSION_NOT_FOUND", "BREACHED_PASSWORD", "GONE", "CONFLICT", "EMAIL_ALREADY_EXISTS", "PROJECT_SLUG_EXISTS", "PACKAGE_SLUG_EXISTS", "CONCURRENT_MODIFICATION", "INVITATION_ALREADY_ACCEPTED", "RATE_LIMIT_EXCEEDED", "AUTH_RATE_LIMIT_EXCEEDED", "QUOTA_EXCEEDED", "BILLING_SUBSCRIPTION_REQUIRED", "BILLING_SUBSCRIPTION_PAST_DUE", "BILLING_SUBSCRIPTION_CANCELLED", "BILLING_PLAN_LIMIT_REACHED", "BILLING_TIER_UPGRADE_REQUIRED", "BILLING_ADDON_REQUIRED", "BILLING_PAYMENT_FAILED", "BILLING_PLAN_CHANGE_DENIED", "BILLING_TRIAL_EXPIRED", "PAYMENT_METHOD_NOT_OWNED", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE", "CONSOLE_EXECUTION_UNAVAILABLE", "DATABASE_ERROR", "EXTERNAL_SERVICE_ERROR", "TIMEOUT", "NOT_IMPLEMENTED", "DOMAIN_RESOLUTION_FAILED", "RATE_LIMIT_UNAVAILABLE", "REGION_BLOCKED", "DUAL_APPROVAL_REQUIRED", "SAAS_PACKAGE_NOT_FOUND", "SAAS_PACKAGE_NOT_PUBLISHABLE", "SAAS_PACKAGE_HAS_SUBSCRIBERS", "DOMAIN_NOT_FOUND", "DOMAIN_ALREADY_EXISTS", "DOMAIN_VERIFICATION_FAILED", "PRICING_PLAN_NOT_FOUND", "PRICING_PLAN_HAS_SUBSCRIBERS", "SUBSCRIPTION_NOT_FOUND", "SELF_SUBSCRIPTION_NOT_ALLOWED", "DUPLICATE_SUBSCRIPTION", "SUBSCRIPTION_ALREADY_CANCELLED", "INVALID_STATUS_TRANSITION", "STRIPE_CONNECT_EXISTS", "STRIPE_CONNECT_NOT_FOUND", "TENANT_PROVISION_NOT_FOUND", "TENANT_ALREADY_PROVISIONED", "TENANT_SLUG_EXISTS", "MARKETING_PAGE_NOT_FOUND", "SEED_DATA_NOT_FOUND", "CONNECTOR_NOT_FOUND", "APP_CONFIG_NOT_FOUND", "APP_CONFIG_DUPLICATE_PLATFORM", "DATA_BUNDLE_NOT_FOUND", "NO_CURRENT_BUNDLE", "BUILD_JOB_NOT_FOUND", "BUILD_JOB_NOT_CANCELLABLE", "SCREEN_NOT_FOUND", "SCREEN_KEY_EXISTS", "INSUFFICIENT_BUILD_CREDITS", "CHECKOUT_FAILED", "THEME_IN_USE", "PROVIDER_UNAVAILABLE", "PROVIDER_NOT_CONNECTED", "LOCATOR_SCOPE", "SSO_CONFIG_NOT_FOUND", "SSO_CONFIG_INACTIVE", "SSO_STATE_INVALID", "SSO_STATE_EXPIRED", "SSO_CALLBACK_ERROR", "SSO_TOKEN_VALIDATION_FAILED", "SSO_USER_NOT_PROVISIONED", "SSO_EMAIL_MISMATCH", "SSO_EMAIL_UNVERIFIED", "SSO_DISCOVERY_FAILED", "SSO_TOKEN_EXCHANGE_INVALID", "SAML_RESPONSE_INVALID", "SAML_SIGNATURE_INVALID", "SAML_ASSERTION_EXPIRED", "SAML_AUDIENCE_MISMATCH", "SAML_REPLAY_DETECTED", "SSO_MFA_REQUIRED", "SSO_EXISTING_USER_REQUIRES_LINK", "SSO_USER_NOT_ORG_MEMBER", "SSO_ACCOUNT_LOCKED", "SSO_LOOKUP_FAILED", "SSO_PROVISION_FAILED", "SSO_SESSION_FAILED", "SSO_LOGIN_FAILED", "SCIM_UNAUTHORIZED", "SCIM_INVALID_FILTER", "SCIM_INVALID_PATH", "SCIM_INVALID_VALUE", "SCIM_MUTABILITY_VIOLATION", "SCIM_UNIQUENESS_CONFLICT", "SCIM_NOT_IMPLEMENTED", "PROJECT_LIMIT_REACHED", "MEMBER_LIMIT_REACHED", "FILE_SIZE_LIMIT_EXCEEDED", "UNSUPPORTED_FILE_TYPE", "PDF_CONTAINS_JS_ACTION", "UPLOAD_SUPPRESSED", "PUBKEY_MISMATCH", "CRYPTO_FLOOR_VIOLATION", "STRIPE_CREDENTIALS_MISSING", "INVALID_POLICY", "VERIFICATION_OFFLINE", "PUBLISH_NO_DRAFT", "PUBLISH_CONFLICT", "TOO_MANY_RECIPIENTS", "ATTACHMENT_NOT_FOUND", "RESTRICTED_ENV", "OWNERSHIP_NOT_PROVEN", "DOMAIN_NOT_ON_CLOUDFLARE", "NEEDS_PROVIDER_CONNECTION", "DOMAIN_ALREADY_CLAIMED", "CONSENT_PENDING", "CONSENT_DENIED", "INVALID_REQUEST", "LIMIT_EXCEEDED", "MISSING_EVENTS", "UNSUPPORTED_MEDIA_TYPE", "BATCH_TOO_LARGE", "PROCESSING_RESTRICTED", "INSUFFICIENT_CREDITS", "FORK_REQUIRED" ] }, "Admin_VerifyTurnstileRequest": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 1, "description": "Cloudflare Turnstile challenge token returned by the browser widget." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Optional UUID for Turnstile idempotency (prevents the same challenge response being used twice)." } } }, "Admin_TurnstileVerifyResult": { "type": "object", "description": "Cloudflare Turnstile verification result.", "properties": { "success": { "type": "boolean" }, "hostname": { "type": "string", "nullable": true }, "challenge_ts": { "type": "string", "format": "date-time", "nullable": true }, "error_codes": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "Admin_Dashboard": { "type": "object", "description": "Platform-wide admin dashboard snapshot (counts, health, alerts).", "properties": { "organizations": { "type": "object", "additionalProperties": true }, "users": { "type": "object", "additionalProperties": true }, "events": { "type": "object", "additionalProperties": true }, "health": { "type": "object", "additionalProperties": true }, "alerts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Admin_AgentRecord": { "type": "object", "description": "An agent type summary as surfaced in the admin console.", "properties": { "id": { "type": "string", "description": "Agent type identifier." }, "name": { "type": "string", "description": "Human-readable agent type name." }, "type": { "type": "string", "description": "Agent type slug." }, "activeCount": { "type": "integer", "minimum": 0, "description": "Number of currently active agent instances of this type." }, "avgDuration": { "type": "string", "description": "Formatted average session duration (e.g. `2.3s` or `45ms`)." }, "status": { "type": "string", "enum": [ "active", "idle", "disabled", "error" ] } } }, "Admin_EventRecord": { "type": "object", "description": "Observability event row from the platform event log.", "properties": { "event_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid", "nullable": true }, "event_type": { "type": "string" }, "severity": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] }, "message": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Admin_OrgNameRecord": { "type": "object", "description": "Minimal org identity record for lookups and autocompletion.", "properties": { "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string", "nullable": true } } }, "Admin_OrganizationRecord": { "type": "object", "description": "Organization record as surfaced in the admin console.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "memberCount": { "type": "integer", "minimum": 0 }, "createdDate": { "type": "string", "format": "date-time" }, "plan": { "type": "string", "nullable": true, "description": "Plan slug or null for orgs that have not yet selected a plan." }, "status": { "type": "string", "enum": [ "active", "trial", "suspended", "churned" ] } } }, "Admin_Pagination": { "type": "object", "description": "Pagination envelope (camelCase, matches the admin list stored procedures).", "properties": { "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalCount": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } } }, "Admin_UserRecord": { "type": "object", "description": "Cross-organization user record. Email is masked as `fi***@domain` before transmission per privacy policy. `lastActive` is coarsened to a calendar-day string (e.g. `2026-06-19`) or `Never`.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "description": "Masked email: first two chars + `***@domain`." }, "orgCount": { "type": "integer", "minimum": 0 }, "lastActive": { "type": "string", "description": "Coarsened to `YYYY-MM-DD` or `Never`." }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ] } } }, "Admin_ConversationRecord": { "type": "object", "description": "Conversation list item in the admin console.", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "orgId": { "type": "string", "format": "uuid" }, "orgName": { "type": "string" }, "userId": { "type": "string", "format": "uuid" }, "userName": { "type": "string" }, "messageCount": { "type": "integer", "minimum": 0 }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "archived", "flagged" ] } } }, "Admin_ConversationDetail": { "type": "object", "description": "Full conversation record with ordered message list.", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "orgId": { "type": "string", "format": "uuid" }, "orgName": { "type": "string" }, "userId": { "type": "string", "format": "uuid" }, "userName": { "type": "string" }, "messageCount": { "type": "integer", "minimum": 0 }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "archived", "flagged" ] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "content": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "Admin_DatabaseStats": { "type": "object", "description": "Database health and storage snapshot. Scoped to the `bb` schema; raw SQL and credentials are never exposed.", "properties": { "totalSize": { "type": "string", "description": "Human-readable total database size (e.g. `1.2 GB`)." }, "connectionPoolUsed": { "type": "integer", "minimum": 0 }, "connectionPoolMax": { "type": "integer", "minimum": 0 }, "avgQueryTime": { "type": "string", "description": "Formatted average query time (e.g. `2.3ms`)." }, "slowQueries24h": { "type": "integer", "minimum": 0 }, "tables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "rowCount": { "type": "integer", "minimum": 0 }, "size": { "type": "string", "description": "Human-readable table size." }, "lastVacuum": { "type": "string", "description": "ISO date string or `Never`." } } } } } }, "Admin_Funnel": { "type": "object", "description": "Platform conversion funnel data.", "properties": { "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "conversionRate": { "type": "number", "minimum": 0, "maximum": 100 }, "dropoffRate": { "type": "number", "minimum": 0, "maximum": 100 } } } }, "period": { "type": "string", "enum": [ "7d", "30d", "90d" ] }, "totalVisitors": { "type": "integer", "minimum": 0 } } }, "Admin_KvStats": { "type": "object", "description": "KV namespace inventory and overall cache metrics.", "properties": { "namespaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Namespace identifier (`backbuild` or `engine`)." }, "name": { "type": "string", "description": "Human-readable namespace name." }, "keyCount": { "type": "integer", "minimum": 0 }, "totalSize": { "type": "string", "description": "Human-readable total size (e.g. `4.2 MB`) or `Unavailable` when the scan exceeded the limit." } } } }, "cacheHitRate": { "type": "number", "minimum": 0, "maximum": 100, "description": "24-hour cache hit rate as a percentage." }, "cacheMissRate": { "type": "number", "minimum": 0, "maximum": 100 }, "totalReads24h": { "type": "integer", "minimum": 0 }, "totalWrites24h": { "type": "integer", "minimum": 0 } } }, "Admin_KvEntry": { "type": "object", "description": "KV key metadata. Values are never returned.", "properties": { "key": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "description": "Value size in bytes." }, "expiration": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO-8601 expiry time derived from the KV expiration unix timestamp, or null when the key has no TTL." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true } } }, "Admin_ThirdPartyData": { "type": "object", "description": "Health summary for all configured third-party integrations. Sorted worst-first by status (down → degraded → healthy).", "properties": { "integrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider type identifier (e.g. `stripe`, `anthropic`)." }, "name": { "type": "string", "description": "Human-readable provider name." }, "status": { "type": "string", "enum": [ "healthy", "degraded", "down" ] }, "lastCheck": { "type": "string", "description": "Relative time string (e.g. `5 mins ago`, `Just now`, or `Never`)." }, "avgResponseTime": { "type": "string", "description": "Formatted average response time (e.g. `120ms`)." }, "callCount24h": { "type": "integer", "minimum": 0 }, "errorRate": { "type": "number", "minimum": 0, "maximum": 100 } } } }, "totalCalls24h": { "type": "integer", "minimum": 0 }, "overallErrorRate": { "type": "number", "minimum": 0, "maximum": 100 } } }, "Admin_MaintenanceRequest": { "type": "object", "additionalProperties": false, "required": [ "task" ], "properties": { "task": { "type": "string", "enum": [ "cleanup_expired_sessions", "rotate_keys", "vacuum_kv", "reindex_search", "flush_observability", "backup_databases" ], "description": "Maintenance task to enqueue." }, "options": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Task-specific options." } } }, "Admin_EmbedRequest": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "all", "dense", "colbert" ], "description": "Which embedding index to backfill. Default `all`." } } }, "Admin_R2Summary": { "type": "object", "description": "Top-level R2 bucket summary: delimited top-level prefixes and the object count in the listed result.", "properties": { "prefixes": { "type": "array", "items": { "type": "string" }, "description": "Delimited top-level prefixes (e.g. org UUID paths)." }, "objectCount": { "type": "integer", "minimum": 0, "description": "Number of objects in the listed top-level result (not the full bucket total)." } } }, "Admin_R2ObjectsResponse": { "type": "object", "description": "Paginated R2 object metadata list. Object content is never returned.", "properties": { "objects": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "size": { "type": "string", "description": "Human-readable file size (e.g. `1.2 MB`). R2 sizes are formatted server-side." }, "uploaded": { "type": "string", "format": "date-time" }, "etag": { "type": "string" } } } }, "cursor": { "type": "string", "nullable": true, "description": "Pass in a subsequent request to page forward; absent or null when the result is not truncated." }, "truncated": { "type": "boolean" } } }, "Admin_IpBlacklistEntry": { "type": "object", "description": "An IP/CIDR bucket entry in the global blacklist. Buckets use the same normaliser as the rate limiter.", "properties": { "bucket": { "type": "string", "description": "Normalised IP bucket (output of the rate-limiter normalisation function)." }, "reason": { "type": "string" }, "addedBy": { "type": "string", "format": "uuid", "description": "User ID of the super-admin who added the entry." }, "addedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } } }, "Admin_IpBlacklistAddRequest": { "type": "object", "additionalProperties": false, "required": [ "ip", "reason" ], "properties": { "ip": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IP address or CIDR to normalise and block." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Mandatory justification (audit logged)." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO-8601 timestamp after which the block is automatically removed." } } }, "Admin_IpBlacklistRemoveRequest": { "type": "object", "additionalProperties": false, "required": [ "ip" ], "properties": { "ip": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IP address or CIDR to unblock. Normalised by the same function used when adding." } } }, "Admin_OrgEmailCapRequest": { "type": "object", "additionalProperties": false, "required": [ "org_id", "cap" ], "properties": { "org_id": { "type": "string", "format": "uuid" }, "cap": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum outbound emails per UTC day (1–1 000 000)." }, "reason": { "type": "string", "maxLength": 1000, "nullable": true } } }, "Admin_CostAttribution": { "type": "object", "description": "Per-tenant cost attribution rollup sorted by descending AI token consumption.", "properties": { "window": { "type": "string", "enum": [ "1h", "24h", "7d", "30d" ] }, "tenants": { "type": "array", "items": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Null for unattributed events." }, "total_events": { "type": "integer", "minimum": 0 }, "total_ai_tokens": { "type": "integer", "minimum": 0 }, "categories": { "type": "object", "additionalProperties": { "type": "object", "properties": { "event_count": { "type": "integer" }, "ai_tokens_used": { "type": "integer" }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } }, "category_totals": { "type": "object", "additionalProperties": { "type": "object", "properties": { "event_count": { "type": "integer" }, "ai_tokens_used": { "type": "integer" } } }, "description": "Aggregated totals per cost category across all tenants." }, "row_count": { "type": "integer", "minimum": 0, "description": "Total raw SP rows processed." } } }, "Admin_AiProvider": { "type": "object", "description": "AI provider configuration. Credential secrets are never included.", "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "maxLength": 500 }, "protocol_type": { "type": "string", "enum": [ "anthropic", "openai", "google", "custom" ] }, "api_base_url": { "type": "string", "format": "uri", "nullable": true }, "is_enabled": { "type": "boolean" }, "sort_order": { "type": "integer", "nullable": true }, "config": { "type": "object", "additionalProperties": true, "nullable": true } } }, "Admin_AiProviderUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "protocol_type": { "type": "string", "enum": [ "anthropic", "openai", "google", "custom" ] }, "api_base_url": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "env_secret_name": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z][A-Za-z0-9_]*$", "nullable": true, "description": "Name of the environment variable that holds this provider's API credential. Must start with a letter; only letters, digits, and underscores allowed." }, "is_enabled": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true, "nullable": true }, "sort_order": { "type": "integer" } } }, "Admin_AiModel": { "type": "object", "description": "AI model configuration record.", "properties": { "id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "maxLength": 500 }, "model_string": { "type": "string", "maxLength": 200 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "nullable": true }, "max_context_tokens": { "type": "integer", "minimum": 1 }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "thinking_token_budget": { "type": "integer", "minimum": 0, "nullable": true }, "supports_voice": { "type": "boolean" }, "supports_image": { "type": "boolean" }, "supports_video": { "type": "boolean" }, "input_cost_per_million_tokens_usd": { "type": "number", "minimum": 0 }, "output_cost_per_million_tokens_usd": { "type": "number", "minimum": 0 }, "input_credits_per_million_tokens": { "type": "integer", "minimum": 0 }, "output_credits_per_million_tokens": { "type": "integer", "minimum": 0 }, "is_enabled": { "type": "boolean" }, "sort_order": { "type": "integer", "nullable": true }, "config": { "type": "object", "additionalProperties": true, "nullable": true } } }, "Admin_AiModelCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "provider_id", "display_name", "model_string", "max_context_tokens", "max_output_tokens", "input_cost_per_million_tokens_usd", "output_cost_per_million_tokens_usd", "input_credits_per_million_tokens", "output_credits_per_million_tokens" ], "properties": { "provider_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "model_string": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Provider-specific model identifier (e.g. `claude-opus-4-5`)." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_context_tokens": { "type": "integer", "minimum": 1 }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "thinking_token_budget": { "type": "integer", "minimum": 0 }, "supports_voice": { "type": "boolean" }, "supports_image": { "type": "boolean" }, "supports_video": { "type": "boolean" }, "input_cost_per_million_tokens_usd": { "type": "number", "minimum": 0 }, "output_cost_per_million_tokens_usd": { "type": "number", "minimum": 0 }, "input_credits_per_million_tokens": { "type": "integer", "minimum": 0 }, "output_credits_per_million_tokens": { "type": "integer", "minimum": 0 }, "is_enabled": { "type": "boolean" }, "sort_order": { "type": "integer" }, "config": { "type": "object", "additionalProperties": true } } }, "Admin_AiModelUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "model_string": { "type": "string", "minLength": 1, "maxLength": 200 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "nullable": true }, "max_context_tokens": { "type": "integer", "minimum": 1 }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "thinking_token_budget": { "type": "integer", "minimum": 0, "nullable": true }, "supports_voice": { "type": "boolean" }, "supports_image": { "type": "boolean" }, "supports_video": { "type": "boolean" }, "input_cost_per_million_tokens_usd": { "type": "number", "minimum": 0 }, "output_cost_per_million_tokens_usd": { "type": "number", "minimum": 0 }, "input_credits_per_million_tokens": { "type": "integer", "minimum": 0 }, "output_credits_per_million_tokens": { "type": "integer", "minimum": 0 }, "is_enabled": { "type": "boolean" }, "sort_order": { "type": "integer" }, "config": { "type": "object", "additionalProperties": true, "nullable": true } } }, "Admin_AnalyticsSummary": { "type": "object", "description": "Analytics summary for the requested product and date range.", "properties": { "product": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "metrics": { "type": "object", "additionalProperties": true } } }, "Admin_AnalyticsVisitorRecord": { "type": "object", "properties": { "visitor_id": { "type": "string" }, "first_seen": { "type": "string", "format": "date-time" }, "last_seen": { "type": "string", "format": "date-time" }, "page_views": { "type": "integer" }, "sessions": { "type": "integer" } } }, "Admin_AnalyticsEventRecord": { "type": "object", "properties": { "event_name": { "type": "string" }, "count": { "type": "integer" }, "unique_visitors": { "type": "integer" }, "first_seen": { "type": "string", "format": "date-time" }, "last_seen": { "type": "string", "format": "date-time" } } }, "Admin_AnalyticsFunnelRecord": { "type": "object", "properties": { "funnel_id": { "type": "string" }, "name": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "overall_conversion_rate_pct": { "type": "number" } } }, "Admin_DbUsageRecord": { "type": "object", "description": "Database compute and storage usage for the current billing period.", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "org_rows": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total_size_bytes": { "type": "integer" }, "compute_ms": { "type": "integer" } } }, "Admin_DbTableListResult": { "type": "object", "properties": { "schema": { "type": "string", "enum": [ "bb", "api", "internal", "audit", "meta" ] }, "tables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "table", "view", "materialized_view" ] }, "row_count_approx": { "type": "integer" }, "size_bytes": { "type": "integer", "nullable": true } } } } } }, "Admin_DbObjectSchema": { "type": "object", "description": "Column definitions for a database table or view.", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "column_name": { "type": "string" }, "data_type": { "type": "string" }, "is_nullable": { "type": "boolean" }, "column_default": { "type": "string", "nullable": true } } } } } }, "Admin_DrEventRecord": { "type": "object", "description": "A disaster-recovery runbook event.", "properties": { "id": { "type": "string", "format": "uuid" }, "phase": { "type": "string", "enum": [ "test_started", "phase_completed", "test_passed", "test_failed", "switchover_executed", "switchback_executed", "emergency_switchback" ] }, "status": { "type": "string", "enum": [ "started", "success", "failure", "warning", "in_progress" ] }, "message": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "triggered_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "Admin_DrEventRequest": { "type": "object", "additionalProperties": false, "required": [ "phase", "status", "message" ], "properties": { "phase": { "type": "string", "enum": [ "test_started", "phase_completed", "test_passed", "test_failed", "switchover_executed", "switchback_executed", "emergency_switchback" ] }, "status": { "type": "string", "enum": [ "started", "success", "failure", "warning", "in_progress" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "metadata": { "type": "object", "additionalProperties": true }, "triggered_by": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "Admin_DrTriggerRequest": { "type": "object", "additionalProperties": false, "required": [ "environment" ], "properties": { "environment": { "type": "string", "enum": [ "dev", "staging", "prod" ] }, "skip_switchback": { "type": "boolean", "description": "When true, no automatic switchback occurs after the failover test. Default false." } } }, "Admin_DsarReplayRequest": { "type": "object", "additionalProperties": false, "properties": { "chunk_size": { "type": "integer", "minimum": 100, "maximum": 50000, "description": "Records per pseudonymization batch (default 1 000)." } } }, "Admin_LatencyHealth": { "type": "object", "description": "Real-time API and DB latency health snapshot computed from the observability event log.", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "critical" ] }, "windowMinutes": { "type": "integer", "description": "Rolling window size in minutes (currently 15)." }, "sampleCount": { "type": "integer", "minimum": 0 }, "http": { "type": "object", "properties": { "p50": { "type": "number", "nullable": true, "description": "Median HTTP response latency (ms). Null when no samples in the window." }, "p95": { "type": "number", "nullable": true }, "p99": { "type": "number", "nullable": true } } }, "db": { "type": "object", "properties": { "p95": { "type": "number", "nullable": true, "description": "95th-percentile DB round-trip latency (ms)." }, "sampleCount": { "type": "integer", "minimum": 0 } } }, "thresholds": { "type": "object", "properties": { "degradedMs": { "type": "number", "description": "p95 threshold above which status becomes `degraded`." }, "criticalMs": { "type": "number", "description": "p95 threshold above which status becomes `critical`." } } }, "worstEndpoints": { "type": "array", "description": "Up to 5 endpoints with the highest p95 in the window.", "items": { "type": "object", "properties": { "path": { "type": "string" }, "p95": { "type": "number", "nullable": true }, "count": { "type": "integer" } } } }, "shardsScanned": { "type": "integer", "minimum": 0 }, "computedAt": { "type": "string", "format": "date-time" }, "cached": { "type": "boolean", "description": "True when served from the 30-second KV cache." } } }, "Admin_AlertRule": { "type": "object", "description": "An alert rule definition.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 200 }, "event_type": { "type": "string", "maxLength": 100, "nullable": true }, "trigger_type": { "type": "string", "maxLength": 100, "nullable": true }, "description": { "type": "string", "maxLength": 2000, "nullable": true }, "condition": { "type": "string", "maxLength": 10000, "nullable": true }, "conditions": { "type": "object", "additionalProperties": true, "nullable": true }, "channels": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Admin_AlertRuleCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable rule name (trimmed)." }, "event_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "trigger_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 2000, "nullable": true }, "condition": { "type": "string", "maxLength": 10000, "nullable": true }, "conditions": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Structured condition (bounded JSON, max 64 KB)." }, "channels": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": true }, "nullable": true } } }, "Admin_BreakGlassEntry": { "type": "object", "description": "A break-glass account row returned by the stored procedure.", "properties": { "user_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "display_name": { "type": "string", "nullable": true }, "is_break_glass": { "type": "boolean" }, "break_glass_last_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "org_id": { "type": "string", "format": "uuid" }, "org_name": { "type": "string" } } }, "Admin_BreakGlassSetResult": { "type": "object", "description": "Result of toggling the break-glass flag.", "properties": { "user_id": { "type": "string", "format": "uuid" }, "is_break_glass": { "type": "boolean" } } }, "Admin_BreakGlassToggleRequest": { "type": "object", "additionalProperties": false, "required": [ "user_id", "is_break_glass" ], "properties": { "user_id": { "type": "string", "format": "uuid", "description": "Target user. An admin cannot toggle their own break-glass flag — `403 FORBIDDEN` is returned." }, "is_break_glass": { "type": "boolean", "description": "True to grant break-glass access; false to revoke." } } }, "Admin_MfaResetResult": { "type": "object", "properties": { "methods_deactivated": { "type": "integer", "minimum": 0, "description": "Number of MFA methods deactivated." }, "sessions_revoked": { "type": "integer", "minimum": 0, "description": "Number of active sessions revoked." } } }, "Admin_ProveClearMockStateRequest": { "type": "object", "additionalProperties": false, "required": [ "reason", "instances" ], "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 500, "description": "Mandatory audit justification (10–500 chars)." }, "instances": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "orgId", "projectId" ], "properties": { "orgId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" } } } } } }, "Admin_ProveClearMockStateResult": { "type": "object", "description": "Per-instance result of the mock-state clear operation.", "properties": { "orgId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "hadMock": { "type": "boolean", "description": "True when the DO had a legacy mock blob that was cleared. Only present on `ok` results." }, "cleared": { "type": "integer", "minimum": 0, "description": "Number of storage keys removed. Only present on `ok` results." }, "error": { "type": "string", "description": "Error message. Only present on `error` results." } } }, "Backbuild_Spec": { "type": "object", "description": "A specification document linked to a project.", "properties": { "spec_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "content": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Backbuild_Task": { "type": "object", "description": "A task in a project's spec or task list.", "properties": { "task_id": { "type": "string", "format": "uuid" }, "spec_id": { "type": "string", "format": "uuid", "nullable": true }, "project_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "phase": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Backbuild_TaskActivity": { "type": "object", "description": "An activity log entry for a task.", "properties": { "activity_id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "actor_id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "detail": { "type": "object", "additionalProperties": true, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Backbuild_TaskStatus": { "type": "object", "description": "A task status definition.", "properties": { "status_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true }, "sort_order": { "type": "integer" } } }, "Backbuild_Category": { "type": "object", "description": "A task or spec category.", "properties": { "category_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true } } }, "Backbuild_Phase": { "type": "object", "description": "A project phase.", "properties": { "phase_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sort_order": { "type": "integer" } } }, "AiCore_ConversationSummary": { "type": "object", "description": "Summary view of a conversation (list items).", "additionalProperties": false, "required": [ "id", "org_id", "user_id", "title", "is_archived", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "task_id": { "type": [ "string", "null" ], "format": "uuid" }, "context_type": { "type": "string", "enum": [ "project", "task", "assistant", "general" ] }, "model": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "is_archived": { "type": "boolean" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "message_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCore_ConversationDetail": { "type": "object", "description": "Full conversation record including message history.", "additionalProperties": false, "required": [ "id", "org_id", "user_id", "title", "is_archived", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "task_id": { "type": [ "string", "null" ], "format": "uuid" }, "context_type": { "type": "string", "enum": [ "project", "task", "assistant", "general" ] }, "model": { "type": [ "string", "null" ] }, "system_prompt": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "is_archived": { "type": "boolean" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_ConversationMessage" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCore_ConversationMessage": { "type": "object", "description": "A single message in a conversation.", "additionalProperties": false, "required": [ "id", "conversation_id", "role", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "assistant", "system", "tool" ] }, "content": { "type": [ "string", "null" ] }, "content_blocks": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true }, "description": "Structured content blocks (multi-modal)." }, "tool_name": { "type": [ "string", "null" ] }, "tool_call_id": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "AiCore_ConversationCreateRequest": { "type": "object", "description": "Request body for creating a conversation.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "project_id": { "type": "string", "format": "uuid" }, "task_id": { "type": "string", "format": "uuid" }, "context_type": { "type": "string", "enum": [ "project", "task", "assistant", "general" ] }, "model": { "type": "string", "maxLength": 100 }, "system_prompt": { "type": "string", "maxLength": 10000 }, "metadata": { "type": "object", "additionalProperties": true } } }, "AiCore_ConversationUpdateRequest": { "type": "object", "description": "Request body for updating a conversation. At least one field required.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "is_archived": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true } } }, "AiCore_AttachmentCreateRequest": { "type": "object", "description": "Request body for attaching a file to a message. Unknown keys rejected (`.strict()`).", "additionalProperties": false, "required": [ "file_name", "file_url" ], "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "file_url": { "type": "string", "maxLength": 4096, "description": "URL of the already-uploaded file (e.g. an R2 pre-signed URL)." }, "file_size": { "type": "integer", "minimum": 0 }, "mime_type": { "type": "string", "maxLength": 200 } } }, "AiCore_Attachment": { "type": "object", "description": "A file attachment on a conversation message.", "additionalProperties": false, "required": [ "id", "message_id", "file_name", "file_url", "mime_type", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "file_url": { "type": "string", "format": "uri" }, "mime_type": { "type": "string" }, "file_size": { "type": [ "integer", "null" ], "minimum": 0 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "AiCore_ConversationCostCreateRequest": { "type": "object", "description": "Request body for recording a per-message AI cost entry. Unknown keys rejected (`.strict()`).", "additionalProperties": false, "required": [ "model", "input_tokens", "output_tokens", "cost_usd" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "input_tokens": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "output_tokens": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "cost_usd": { "type": "number", "minimum": 0, "maximum": 9999, "description": "USD cost for this invocation (stored as NUMERIC(10,6); must be 0–9999)." }, "message_id": { "type": "string", "format": "uuid", "description": "If cost is attributable to a specific message. Omit for conversation-level aggregate cost." } } }, "AiCore_ConversationCost": { "type": "object", "description": "A recorded AI cost entry.", "additionalProperties": false, "required": [ "id", "conversation_id", "model", "input_tokens", "output_tokens", "cost_usd", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": [ "string", "null" ], "format": "uuid" }, "model": { "type": "string" }, "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "cost_usd": { "type": "number", "minimum": 0 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "AiCore_ArtifactUpdateRequest": { "type": "object", "description": "Request body for updating a conversation artifact. At least one field required. Unknown keys rejected (`.strict()`).", "additionalProperties": false, "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "r2_key": { "type": "string", "minLength": 1, "maxLength": 1024 }, "mime_type": { "type": "string", "maxLength": 200 }, "file_size": { "type": "integer", "minimum": 0 }, "checksum_sha256": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$", "description": "Lowercase or uppercase hex SHA-256 digest (exactly 64 hex characters)." }, "metadata": { "type": "object", "additionalProperties": true } } }, "AiCore_Artifact": { "type": "object", "description": "A conversation artifact (generated file).", "additionalProperties": false, "required": [ "id", "conversation_id", "file_name", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "r2_key": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ], "minimum": 0 }, "checksum_sha256": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCore_EnvMatrixEntry": { "type": "object", "description": "A single environment's read/write permission in an AI session matrix.", "additionalProperties": false, "required": [ "env_id", "can_read", "can_write" ], "properties": { "env_id": { "type": "string", "format": "uuid", "description": "Environment identifier." }, "can_read": { "type": "boolean" }, "can_write": { "type": "boolean" } } }, "AiCore_EnvMatrix": { "type": "object", "description": "Per-session multi-environment access matrix.", "additionalProperties": false, "required": [ "conversation_id", "matrix" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "matrix": { "type": "array", "maxItems": 16, "items": { "$ref": "#/components/schemas/AiCore_EnvMatrixEntry" } } } }, "AiCore_EnvMatrixSetRequest": { "type": "object", "description": "Request body for setting the conversation environment matrix.", "additionalProperties": false, "required": [ "matrix" ], "properties": { "matrix": { "type": "array", "maxItems": 16, "description": "Full replacement list of environment access entries. Empty array clears the matrix.", "items": { "$ref": "#/components/schemas/AiCore_EnvMatrixEntry" } } } }, "AiCore_Share": { "type": "object", "description": "A sharing grant on a conversation or artifact.", "additionalProperties": false, "required": [ "id", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "user", "role", "group", "department", "project", "org", "global", "public" ] }, "capability": { "type": "string", "enum": [ "read", "write" ] }, "target_id": { "type": [ "string", "null" ] }, "recipient_org_id": { "type": [ "string", "null" ], "format": "uuid" }, "recipient_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "AiCore_ShareCreateRequest": { "type": "object", "description": "Request body for creating a conversation or artifact share. Unknown keys rejected (`.strict()`). All fields are optional — the stored procedure enforces the pairing rules (e.g., `scope` required for in-org shares).", "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "user", "role", "group", "department", "project", "org", "global", "public" ] }, "target_id": { "type": "string", "maxLength": 255 }, "capability": { "type": "string", "enum": [ "read", "write" ] }, "recipient_org_id": { "type": "string", "format": "uuid" }, "recipient_user_id": { "type": "string", "format": "uuid" } } }, "AiCore_OrgAiModel": { "type": "object", "description": "An org-level AI model catalog entry.", "additionalProperties": false, "required": [ "id", "org_id", "provider_id", "display_name", "model_key", "is_enabled", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "model_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "capabilities": { "type": "array", "items": { "type": "string" } }, "is_enabled": { "type": "boolean" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCore_SystemAiModelWithOverride": { "type": "object", "description": "A system AI model with the org's enabled/disabled override state.", "additionalProperties": false, "required": [ "id", "display_name", "model_string", "provider_name", "protocol_type", "is_enabled_for_org" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "model_string": { "type": "string" }, "provider_name": { "type": "string" }, "protocol_type": { "type": "string", "enum": [ "anthropic", "openai", "google", "custom" ] }, "supports_voice": { "type": "boolean" }, "supports_image": { "type": "boolean" }, "supports_video": { "type": "boolean" }, "input_cost_per_million_tokens_usd": { "type": [ "number", "string" ] }, "output_cost_per_million_tokens_usd": { "type": [ "number", "string" ] }, "input_credits_per_million_tokens": { "type": [ "number", "string" ] }, "output_credits_per_million_tokens": { "type": [ "number", "string" ] }, "is_enabled_for_org": { "type": "boolean", "description": "`true` if the org has not disabled this system model." } } }, "AiCore_AiModelCreateRequest": { "type": "object", "description": "Request body for creating an org AI model. `context_window` is required; all cost/credit fields are per-million-token.", "required": [ "provider_id", "display_name", "model_key", "context_window" ], "properties": { "provider_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "model_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "context_window": { "type": "integer", "minimum": 1, "description": "Context window size in tokens." }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "capabilities": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 50 } }, "input_cost_per_million_tokens": { "type": "number", "minimum": 0 }, "output_cost_per_million_tokens": { "type": "number", "minimum": 0 }, "input_credits_per_million_tokens": { "type": "number", "minimum": 0 }, "output_credits_per_million_tokens": { "type": "number", "minimum": 0 }, "is_enabled": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true } } }, "AiCore_AiModelUpdateRequest": { "type": "object", "description": "Request body for updating an org AI model. All fields are optional; only supplied fields are changed.", "properties": { "provider_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "model_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "context_window": { "type": "integer", "minimum": 1 }, "max_output_tokens": { "type": "integer", "minimum": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "capabilities": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 50 } }, "input_cost_per_million_tokens": { "type": "number", "minimum": 0 }, "output_cost_per_million_tokens": { "type": "number", "minimum": 0 }, "input_credits_per_million_tokens": { "type": "number", "minimum": 0 }, "output_credits_per_million_tokens": { "type": "number", "minimum": 0 }, "is_enabled": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true } } }, "AiCore_AvailableAiModel": { "type": "object", "description": "A resolved available AI model entry — system catalog merged with org overrides.", "additionalProperties": false, "required": [ "id", "display_name", "model_string", "provider_name", "protocol_type", "is_system_model" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "model_string": { "type": "string" }, "provider_name": { "type": "string" }, "protocol_type": { "type": "string" }, "api_base_url": { "type": [ "string", "null" ] }, "temperature": { "type": [ "number", "null" ] }, "max_context_tokens": { "type": [ "integer", "null" ] }, "max_output_tokens": { "type": [ "integer", "null" ] }, "thinking_token_budget": { "type": "integer" }, "supports_voice": { "type": "boolean" }, "supports_image": { "type": "boolean" }, "supports_video": { "type": "boolean" }, "input_cost_per_million_tokens_usd": { "type": [ "number", "string" ] }, "output_cost_per_million_tokens_usd": { "type": [ "number", "string" ] }, "input_credits_per_million_tokens": { "type": [ "number", "string" ] }, "output_credits_per_million_tokens": { "type": [ "number", "string" ] }, "is_system_model": { "type": "boolean" }, "sort_order": { "type": "integer" } } }, "AiCore_SystemModelOverrideItem": { "type": "object", "description": "A single system model enabled/disabled override.", "additionalProperties": false, "required": [ "system_model_id", "is_enabled" ], "properties": { "system_model_id": { "type": "string", "format": "uuid" }, "is_enabled": { "type": "boolean" } } }, "AiCore_SystemModelToggleRequest": { "type": "object", "description": "Batch system model override request. Unknown keys rejected.", "additionalProperties": false, "required": [ "overrides" ], "properties": { "overrides": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/AiCore_SystemModelOverrideItem" } } } }, "AiCore_AiProviderConfigEntry": { "type": "object", "description": "Provider entry in the org AI model catalog configuration. `id` is a free-form slug (not a UUID).", "additionalProperties": false, "required": [ "id", "name", "enabled" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Provider slug (e.g. `anthropic`, `openai`). Free-form string — not a UUID." }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "cloudflare_secret_name": { "type": [ "string", "null" ], "maxLength": 200, "description": "Name of the Cloudflare secret holding the API key for this provider. Must be scoped to the organization using the prefix `org___`. Cross-tenant references are rejected with `400 VALIDATION_ERROR`. Raw uppercase env-var names (e.g. `ANTHROPIC_API_KEY`) are also rejected." }, "api_base_url": { "type": [ "string", "null" ], "maxLength": 500 }, "enabled": { "type": "boolean" } } }, "AiCore_AiModelConfigEntry": { "type": "object", "description": "Model entry in the org AI model catalog configuration. `id` and `provider_id` are free-form slugs matching the provider entries.", "additionalProperties": false, "required": [ "id", "provider_id", "name", "model_string", "temperature", "max_context_tokens", "max_output_tokens", "thinking_token_budget", "supports_voice", "supports_image", "supports_video", "input_cost_per_million_tokens_usd", "output_cost_per_million_tokens_usd", "input_credits_per_million_tokens", "output_credits_per_million_tokens", "enabled" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Model slug (free-form, must be unique within the catalog)." }, "provider_id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Must reference an existing provider `id` in the same catalog." }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "model_string": { "type": "string", "minLength": 1, "maxLength": 200 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_context_tokens": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "max_output_tokens": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "thinking_token_budget": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "supports_voice": { "type": "boolean" }, "supports_image": { "type": "boolean" }, "supports_video": { "type": "boolean" }, "input_cost_per_million_tokens_usd": { "type": "number", "minimum": 0, "maximum": 1000000 }, "output_cost_per_million_tokens_usd": { "type": "number", "minimum": 0, "maximum": 1000000 }, "input_credits_per_million_tokens": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "output_credits_per_million_tokens": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "enabled": { "type": "boolean" } } }, "AiCore_AiModelConfig": { "type": "object", "description": "Merged org AI model catalog configuration (JSONB-stored org overrides fused with the relational system catalog; org values win on collision).", "additionalProperties": false, "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_AiProviderConfigEntry" } }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_AiModelConfigEntry" } }, "default_model_id": { "type": [ "string", "null" ], "description": "Id of the default model (references a model `id` in this catalog)." }, "usage": { "type": [ "object", "null" ], "description": "Optional usage statistics for the current billing period.", "additionalProperties": false, "properties": { "total_tokens": { "type": "integer", "minimum": 0 }, "total_cost_usd": { "type": "number", "minimum": 0 }, "requests_count": { "type": "integer", "minimum": 0 }, "period": { "type": "string" } } } } }, "AiCore_AiModelCatalogUpdateRequest": { "type": "object", "description": "Request body for full-replace of the org AI model catalog. Provider ids must be unique; model `provider_id` must reference an existing provider. `default_model_id` must reference an existing model. `cloudflare_secret_name` values must be org-scoped.", "additionalProperties": false, "required": [ "providers", "models" ], "properties": { "providers": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/AiCore_AiProviderConfigEntry" } }, "models": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/AiCore_AiModelConfigEntry" } }, "default_model_id": { "type": [ "string", "null" ], "maxLength": 100, "description": "Must reference a model `id` in the submitted catalog." } } }, "AiCore_AiProvider": { "type": "object", "description": "An org AI provider configuration (API key never included).", "additionalProperties": false, "required": [ "id", "org_id", "provider_name", "protocol_type", "is_enabled", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "provider_name": { "type": "string" }, "protocol_type": { "type": "string", "enum": [ "anthropic", "openai", "google", "custom" ] }, "api_base_url": { "type": [ "string", "null" ] }, "is_enabled": { "type": "boolean" }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 0 }, "rate_limit_tpm": { "type": [ "integer", "null" ], "minimum": 0 }, "config": { "type": [ "object", "null" ], "additionalProperties": true }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCore_AiProviderCreateRequest": { "type": "object", "description": "Request body for creating an AI provider. Unknown keys rejected (`.strict()`). `api_key` is optional — if omitted the provider record is created without credentials (an enabled provider without a key will fail at runtime). The API key is stored encrypted; never returned.", "additionalProperties": false, "required": [ "provider_name", "protocol_type" ], "properties": { "provider_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "protocol_type": { "type": "string", "enum": [ "anthropic", "openai", "google", "custom" ] }, "api_base_url": { "type": [ "string", "null" ], "maxLength": 2048, "description": "Base URL for the provider API. Must use HTTPS. For `anthropic`/`openai`/`google` protocol types the hostname must match the vendor's canonical domain. For `custom` the URL undergoes DNS-resolve SSRF validation — private/RFC-1918 IPs are rejected." }, "api_key": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Provider API key. Stored encrypted; never returned in any response." }, "rate_limit_rpm": { "type": "integer", "minimum": 1 }, "rate_limit_tpm": { "type": "integer", "minimum": 1 }, "config": { "type": "object", "additionalProperties": true } } }, "AiCore_AiProviderUpdateRequest": { "type": "object", "description": "Request body for updating an AI provider. All fields are optional.", "properties": { "provider_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "protocol_type": { "type": "string", "enum": [ "anthropic", "openai", "google", "custom" ] }, "api_base_url": { "type": [ "string", "null" ], "maxLength": 2048, "description": "Same SSRF constraints as on create." }, "api_key": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000, "description": "Provide a new key to rotate. Pass `null` to clear the stored credential." }, "is_enabled": { "type": "boolean" }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1 }, "rate_limit_tpm": { "type": [ "integer", "null" ], "minimum": 1 }, "config": { "type": "object", "additionalProperties": true } } }, "AiCore_SystemPrompt": { "type": "object", "description": "A global AI system prompt definition or override entry.", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Unique slug key for this prompt." }, "template": { "type": [ "string", "null" ], "description": "The current prompt content (compiled default or active KV override)." }, "is_overridden": { "type": "boolean", "description": "`true` when a KV override is active for this prompt key." }, "updated_by": { "type": [ "string", "null" ], "description": "Email or user id of the last editor." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AiCore_SystemPromptUpsertRequest": { "type": "object", "description": "Request body for creating or replacing a global system prompt override.", "additionalProperties": false, "required": [ "template" ], "properties": { "template": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "The new prompt template content." } } }, "AiCore_EngineSession": { "type": "object", "description": "A multi-agent engine session record.", "additionalProperties": false, "required": [ "id", "org_id", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "paused", "completed", "cancelled", "failed" ] }, "agent_count": { "type": "integer", "minimum": 0 }, "task_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCore_EngineSessionStatus": { "type": "object", "description": "Detailed status for a multi-agent engine session.", "additionalProperties": false, "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "paused", "completed", "cancelled", "failed" ] }, "progress": { "type": [ "object", "null" ], "additionalProperties": true }, "error": { "type": [ "string", "null" ] } } }, "AiCore_EngineTask": { "type": "object", "description": "A task within a multi-agent engine session.", "additionalProperties": false, "required": [ "id", "session_id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ] }, "assigned_agent_id": { "type": [ "string", "null" ], "format": "uuid" }, "result": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCore_EngineAgent": { "type": "object", "description": "An agent participant in a multi-agent engine session.", "additionalProperties": false, "required": [ "id", "session_id", "agent_type", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "agent_type": { "type": "string" }, "status": { "type": "string", "enum": [ "idle", "active", "done", "failed" ] }, "model": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "AiCore_SkillPolicy": { "type": "object", "description": "A visibility policy available for assignment to skills in the org.", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Policy identifier." }, "policy_name": { "type": [ "string", "null" ], "description": "Internal policy name slug." }, "display_name": { "type": "string", "description": "Human-readable display name." }, "description": { "type": "string", "description": "Optional description of what the policy allows." }, "disabled": { "type": "boolean", "description": "True when this policy cannot be directly assigned (clone required)." }, "clone_required": { "type": "boolean", "description": "True when the caller must clone this policy before assigning it." }, "is_default": { "type": "boolean", "description": "True when this is a built-in Backbuild default policy." } } }, "AiCore_SkillState": { "type": "object", "description": "A single FSM state in a skill.", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "prompt": { "type": "string", "maxLength": 50000 }, "model_override": { "type": [ "string", "null" ], "maxLength": 200 }, "is_initial": { "type": "boolean" }, "is_terminal": { "type": "boolean" }, "is_question_answer": { "type": "boolean" } } }, "AiCore_SkillTransition": { "type": "object", "description": "A transition between FSM states in a skill.", "additionalProperties": false, "required": [ "id", "name", "from_state_id", "to_state_id", "trigger_type" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "from_state_id": { "type": "string" }, "to_state_id": { "type": "string" }, "trigger_type": { "type": "string", "enum": [ "auto", "manual", "condition", "event" ] }, "drop_context_state_ids": { "type": "array", "items": { "type": "string" } }, "drop_tool_call_results": { "type": "boolean" }, "drop_user_input": { "type": "boolean" }, "drop_ai_responses": { "type": "boolean" } } }, "AiCore_Skill": { "type": "object", "description": "A skill definition (FSM-based AI workflow).", "additionalProperties": false, "required": [ "id", "org_id", "name", "skill_type", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "skill_type": { "type": "string", "enum": [ "prompt", "chain", "agent", "composite" ] }, "config": { "type": [ "object", "null" ], "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "draft", "disabled" ] }, "overall_prompt": { "type": [ "string", "null" ], "maxLength": 50000 }, "default_model": { "type": [ "string", "null" ], "maxLength": 200 }, "prompt_template": { "type": [ "string", "null" ], "maxLength": 50000 }, "visibility_policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "test_visibility_policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "live_visibility_policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "states": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/AiCore_SkillState" } }, "transitions": { "type": "array", "maxItems": 300, "items": { "$ref": "#/components/schemas/AiCore_SkillTransition" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCore_SkillCreateRequest": { "type": "object", "description": "Request body for creating a skill. `name` is required; all other fields are optional. Unknown keys rejected (`.strict()`).", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "skill_type": { "type": "string", "enum": [ "prompt", "chain", "agent", "composite" ], "description": "Defaults to `agent` when omitted." }, "config": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "draft", "disabled" ] }, "overall_prompt": { "type": "string", "maxLength": 50000 }, "default_model": { "type": [ "string", "null" ], "maxLength": 200 }, "prompt_template": { "type": "string", "maxLength": 50000, "description": "Alias for `overall_prompt`; merged at write time." }, "visibility_policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "test_visibility_policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "live_visibility_policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "states": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/AiCore_SkillStateInput" } }, "transitions": { "type": "array", "maxItems": 300, "items": { "$ref": "#/components/schemas/AiCore_SkillTransitionInput" } } } }, "AiCore_SkillUpdateRequest": { "type": "object", "description": "Request body for updating a skill. All fields are optional. Unknown keys rejected (`.strict()`).", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "skill_type": { "type": "string", "enum": [ "prompt", "chain", "agent", "composite" ] }, "config": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "draft", "disabled" ] }, "overall_prompt": { "type": "string", "maxLength": 50000 }, "default_model": { "type": [ "string", "null" ], "maxLength": 200 }, "prompt_template": { "type": "string", "maxLength": 50000 }, "visibility_policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "test_visibility_policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "live_visibility_policy_id": { "type": [ "string", "null" ], "format": "uuid" }, "states": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/AiCore_SkillStateInput" } }, "transitions": { "type": "array", "maxItems": 300, "items": { "$ref": "#/components/schemas/AiCore_SkillTransitionInput" } } } }, "AiCore_SkillPublishRequest": { "type": "object", "description": "Optional request body for publishing a skill. If omitted, the current skill version is used.", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1, "description": "Explicit version number to publish. Defaults to the skill's current version when omitted." } } }, "AiCore_SkillStateInput": { "type": "object", "description": "A FSM state to create or update within a skill.", "additionalProperties": false, "required": [ "name" ], "properties": { "id": { "type": "string", "description": "Existing state UUID to update. Omit to create a new state." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "prompt": { "type": "string", "maxLength": 50000 }, "model_override": { "type": [ "string", "null" ], "maxLength": 200 }, "is_initial": { "type": "boolean" }, "is_terminal": { "type": "boolean" }, "is_question_answer": { "type": "boolean" } } }, "AiCore_SkillTransitionInput": { "type": "object", "description": "A FSM transition to create within a skill. All transitions are replaced on update.", "additionalProperties": false, "required": [ "name", "from_state_id", "to_state_id" ], "properties": { "id": { "type": "string", "description": "Client-side transition id (for idempotency). Optional." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "from_state_id": { "type": "string", "minLength": 1, "description": "Source state UUID (or client-side temporary id)." }, "to_state_id": { "type": "string", "minLength": 1, "description": "Target state UUID (or client-side temporary id)." }, "trigger_type": { "type": "string", "enum": [ "auto", "manual", "condition", "event" ], "description": "Defaults to `manual` when omitted." }, "drop_context_state_ids": { "type": "array", "items": { "type": "string" }, "description": "State ids whose context is dropped when this transition fires." }, "drop_tool_call_results": { "type": "boolean" }, "drop_user_input": { "type": "boolean" }, "drop_ai_responses": { "type": "boolean" } } }, "AiCore_SkillFeatureRequestCreate": { "type": "object", "description": "Request body for creating a skill capability feature request.", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 5000 }, "stage": { "type": "string", "enum": [ "test", "live" ], "description": "Which skill stage this request is against. Defaults to `test`." } } }, "AiCore_SkillFeatureRequest": { "type": "object", "description": "A capability/feature request record for a skill.", "additionalProperties": false, "required": [ "id", "skill_id", "title" ], "properties": { "id": { "type": "string", "format": "uuid" }, "skill_id": { "type": "string", "format": "uuid" }, "stage": { "type": "string", "enum": [ "test", "live" ] }, "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 5000 }, "requested_by": { "type": "string", "format": "uuid", "description": "User who created the request." }, "status": { "type": "string", "description": "Request status (e.g. `open`, `in_progress`, `resolved`)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCore_SkillModelOption": { "type": "object", "description": "An AI model option available to the org's active pricing plan for use in skills.", "additionalProperties": false, "required": [ "value", "label" ], "properties": { "value": { "type": "string", "description": "Model identifier string (used as `default_model` or state `model_override`)." }, "label": { "type": "string", "description": "Human-readable display label." }, "description": { "type": [ "string", "null" ] } } }, "AiCore_SkillPlanEntitlements": { "type": "object", "description": "Pricing-plan entitlements relevant to the skill editor.", "additionalProperties": false, "required": [ "plan_id", "plan_name", "model_options", "capabilities" ], "properties": { "plan_id": { "type": [ "string", "null" ], "description": "Active pricing plan UUID." }, "plan_name": { "type": [ "string", "null" ], "description": "Pricing plan display name." }, "credits_monthly": { "type": [ "number", "null" ], "description": "Monthly AI credits included in the plan." }, "storage_bytes": { "type": [ "integer", "null" ], "description": "Storage quota in bytes." }, "db_storage_bytes": { "type": [ "integer", "null" ], "description": "Database storage quota in bytes." }, "model_options": { "type": "array", "items": { "$ref": "#/components/schemas/AiCore_SkillModelOption" } }, "capabilities": { "type": "object", "additionalProperties": false, "required": [ "image_generation", "image_interaction", "video_generation", "video_interaction", "audio_generation", "audio_interaction", "sandbox_enabled" ], "properties": { "image_generation": { "type": "boolean" }, "image_interaction": { "type": "boolean" }, "video_generation": { "type": "boolean" }, "video_interaction": { "type": "boolean" }, "audio_generation": { "type": "boolean" }, "audio_interaction": { "type": "boolean" }, "sandbox_enabled": { "type": "boolean" } } } } }, "AiCore_VisionVerdictRequest": { "type": "object", "description": "Request body for the AI vision verdict endpoint. Unknown keys rejected.", "additionalProperties": false, "required": [ "image_b64", "prompt" ], "properties": { "image_b64": { "type": "string", "minLength": 1, "description": "Base64-encoded image data. Maximum decoded size is 5 MB." }, "image_mime": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/gif", "image/webp", "image/heic", "image/heif" ], "default": "image/png", "description": "MIME type of the image." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "The question or instruction to send to the vision model alongside the image." }, "provider": { "type": "string", "enum": [ "workers-ai", "anthropic" ], "default": "workers-ai" }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Optional model override. Defaults to the provider's configured default vision model." }, "redact_pii": { "type": "boolean", "default": true, "description": "When `true`, PII found in the image or AI response is redacted before storage." } } }, "AiCore_VisionVerdictResponse": { "type": "object", "description": "Structured result from the vision verdict endpoint.", "additionalProperties": false, "required": [ "verdict", "model", "provider", "latency_ms" ], "properties": { "verdict": { "type": "string", "enum": [ "yes", "no", "unclear", "refused" ], "description": "`yes`/`no` when the model can answer the prompt clearly; `unclear` when confidence is low; `refused` when the model declines due to content policy." }, "reason": { "type": [ "string", "null" ], "description": "Human-readable explanation of the verdict from the model." }, "model": { "type": "string", "description": "The exact model identifier used." }, "provider": { "type": "string", "description": "The provider that served the request." }, "latency_ms": { "type": "integer", "minimum": 0, "description": "End-to-end model call latency in milliseconds." }, "usage": { "type": "object", "description": "Token usage for this call.", "additionalProperties": false, "properties": { "input": { "type": "integer", "minimum": 0 }, "output": { "type": "integer", "minimum": 0 } } } } }, "AiOps_WrappedSearchResults": { "type": "object", "description": "Search results with nonce-delimited wrapping so a downstream LLM treats chunk content as data, not instructions.", "properties": { "safety_notice": { "type": "string", "description": "Human/LLM-facing notice describing the nonce-wrapping contract." }, "delimiter_nonce": { "type": "string", "description": "Per-response nonce delimiting wrapped chunk content." }, "chunkCount": { "type": "integer", "description": "Number of returned chunks." }, "chunks": { "type": "array", "description": "Matched document chunks (metadata + wrapped content).", "items": { "type": "object", "additionalProperties": true } }, "raw": { "type": "object", "additionalProperties": true, "description": "Any additional top-level fields the search returned (e.g. pagination)." } } }, "AiOps_VectorSearchRequest": { "type": "object", "required": [ "embedding" ], "description": "Dense vector search request.", "properties": { "embedding": { "type": "string", "minLength": 1, "maxLength": 32000, "description": "Serialized query embedding, e.g. \"[0.1,0.2,...]\" or a bare comma-separated list." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum chunks to return." }, "threshold": { "type": "number", "minimum": 0.55, "maximum": 1, "description": "Minimum cosine similarity (default 0.65). Values below the 0.55 floor are rejected to prevent fishing." }, "project_id": { "type": "string", "format": "uuid", "description": "Restrict the search to a single project." } } }, "AiOps_HybridSearchRequest": { "type": "object", "required": [ "embedding" ], "description": "Hybrid (dense + optional ColBERT rerank) search request.", "properties": { "embedding": { "type": "string", "minLength": 1, "maxLength": 32000, "description": "Serialized dense query embedding." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum chunks to return." }, "threshold": { "type": "number", "minimum": 0.55, "maximum": 1, "description": "Minimum cosine similarity (default 0.65)." }, "project_id": { "type": "string", "format": "uuid", "description": "Restrict the search to a single project." }, "rerank": { "type": "boolean", "description": "When true, rerank dense candidates with ColBERT late interaction." }, "colbert_embedding": { "type": "array", "maxItems": 128, "items": { "type": "string", "maxLength": 32000 }, "description": "Per-token ColBERT query embeddings used when reranking." } } }, "AiOps_NaturalSearchRequest": { "type": "object", "required": [ "query" ], "description": "Natural-language search request (embedded server-side).", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Natural-language query text." }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Maximum chunks to return (default 8)." }, "threshold": { "type": "number", "minimum": 0.55, "maximum": 1, "description": "Minimum cosine similarity (default 0.65)." }, "project_id": { "type": "string", "format": "uuid", "description": "Restrict the search to a single project." } } }, "AiOps_GenerateDataRequest": { "type": "object", "required": [ "name", "vector_count" ], "description": "Synthetic benchmark dataset generation request.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Dataset name." }, "vector_count": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Number of vectors to generate." }, "dimensions": { "type": "integer", "minimum": 1, "maximum": 4096, "description": "Vector dimensionality." }, "distribution": { "type": "string", "enum": [ "uniform", "gaussian", "clustered" ], "description": "Synthetic value distribution." }, "seed": { "type": "integer", "description": "Deterministic RNG seed." } } }, "AiOps_RunSuiteRequest": { "type": "object", "required": [ "dataset_id" ], "description": "Benchmark suite run request.", "properties": { "dataset_id": { "type": "string", "format": "uuid", "description": "Dataset to benchmark against." }, "techniques": { "type": "array", "description": "Index techniques to benchmark.", "items": { "type": "string", "enum": [ "hnsw", "diskann", "vchordrq", "vchordg", "colbert_maxsim", "hybrid_dense_colbert" ] } }, "query_count": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Number of query vectors per technique." }, "k": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Top-k neighbours to retrieve." } } }, "AiOps_AssetCreateRequest": { "type": "object", "required": [ "asset_type", "name", "draft_snapshot" ], "description": "Create a test asset (scenario/personality/test-data).", "properties": { "asset_type": { "type": "string", "enum": [ "scenario", "personality", "test_data" ], "description": "Kind of asset." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Asset name." }, "description": { "type": "string", "maxLength": 2000, "description": "Optional description." }, "draft_snapshot": { "description": "Draft content; shape depends on asset_type (scenario graph, personality prompt, or test-data values)." }, "live_snapshot": { "description": "Optional live content of the same shape." }, "is_enabled": { "type": "boolean", "description": "Whether the asset is active." } } }, "AiOps_AssetUpdateRequest": { "type": "object", "description": "Update a test asset (all fields optional).", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "draft_snapshot": { "description": "Replacement draft content." }, "live_snapshot": { "description": "Replacement live content." }, "is_enabled": { "type": "boolean" } } }, "AiOps_RunScenarioRequest": { "type": "object", "description": "Scenario run options.", "properties": { "stage": { "type": "string", "enum": [ "draft", "live" ], "description": "Which asset stage to execute." } } }, "AiOps_RunAllRequest": { "type": "object", "description": "Run-all options.", "properties": { "stage": { "type": "string", "enum": [ "draft", "live", "mixed" ], "description": "Which stage(s) to execute across all scenarios." } } }, "AiOps_CloneTypeRequest": { "type": "object", "additionalProperties": false, "required": [ "source_type_id" ], "properties": { "source_type_id": { "type": "string", "format": "uuid", "description": "Source training type to clone." }, "source_scope": { "type": "string", "enum": [ "system", "org" ], "description": "Whether the source is a system or org type." }, "rename": { "type": "string", "minLength": 1, "maxLength": 200, "description": "New name for the clone." }, "add_fields": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Additional field definitions." }, "parent_uuid": { "type": "string", "format": "uuid", "description": "Optional parent type." } } }, "AiOps_CreateCourseRequest": { "type": "object", "additionalProperties": false, "required": [ "project_id", "entity_type_id", "title" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "entity_type_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "slug": { "type": "string", "maxLength": 128, "description": "URL slug (lowercase alphanumeric + hyphens)." }, "description": { "type": "string", "maxLength": 10000 }, "locale": { "type": "string", "maxLength": 35 }, "estimated_minutes": { "type": "integer", "minimum": 0, "maximum": 100000 }, "difficulty": { "type": "string", "maxLength": 64 }, "access_model": { "type": "string", "enum": [ "public_free", "subscription", "org_internal" ] }, "pricing_type": { "type": "string", "enum": [ "free", "one_time", "subscription" ] }, "certificate_ttl_days": { "type": "integer", "minimum": 1, "maximum": 36500 }, "settings": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true } } }, "AiOps_PublishCourseRequest": { "type": "object", "additionalProperties": false, "properties": { "is_free": { "type": "boolean" }, "saas_package_id": { "type": "string", "format": "uuid" }, "pricing_plan_id": { "type": "string", "format": "uuid" }, "feature_flag_id": { "type": "string", "format": "uuid" }, "flag_source": { "type": "string", "enum": [ "system", "custom" ] }, "listing_id": { "type": "string", "format": "uuid" }, "visibility": { "type": "string", "enum": [ "marketplace", "package_only", "unlisted" ] } } }, "AiOps_CourseUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "At least one field required.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "maxLength": 10000 }, "locale": { "type": "string", "maxLength": 35 }, "estimated_minutes": { "type": "integer", "minimum": 0, "maximum": 100000 }, "difficulty": { "type": "string", "maxLength": 64 }, "access_model": { "type": "string", "enum": [ "public_free", "subscription", "org_internal" ] }, "settings": { "type": "object", "additionalProperties": true } } }, "AiOps_NodeUpsertRequest": { "type": "object", "additionalProperties": false, "required": [ "project_id", "entity_type_id", "title" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "entity_type_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 1000 }, "entity_id": { "type": "string", "format": "uuid", "description": "Existing node to update (omit to create)." }, "parent_id": { "type": "string", "format": "uuid", "description": "Parent node." }, "metadata": { "type": "object", "additionalProperties": true }, "sort_order": { "type": "integer" } } }, "AiOps_EnrollRequest": { "type": "object", "additionalProperties": false, "required": [ "course_id" ], "properties": { "course_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid", "description": "Target user (assigners only; defaults to caller)." }, "source": { "type": "string", "enum": [ "self", "assigned", "required" ] }, "due_at": { "type": "string", "format": "date-time" } } }, "AiOps_ProgressBatchRequest": { "type": "object", "additionalProperties": false, "required": [ "enrollment_id", "nodes" ], "properties": { "enrollment_id": { "type": "string", "format": "uuid" }, "nodes": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/AiOps_ProgressNode" } }, "total_steps": { "type": "integer", "minimum": 0, "maximum": 100000 }, "last_entity_id": { "type": "string", "format": "uuid" } } }, "AiOps_ProgressNode": { "type": "object", "additionalProperties": false, "required": [ "entity_id" ], "properties": { "entity_id": { "type": "string", "format": "uuid" }, "node_kind": { "type": "string", "enum": [ "course", "chapter", "lesson", "step" ] }, "status": { "type": "string", "enum": [ "not_started", "in_progress", "completed", "skipped" ] }, "progress_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "position": { "type": "object", "additionalProperties": true } } }, "AiOps_AttemptRequest": { "type": "object", "additionalProperties": false, "required": [ "enrollment_id", "entity_id", "submitted_answer" ], "properties": { "enrollment_id": { "type": "string", "format": "uuid" }, "entity_id": { "type": "string", "format": "uuid" }, "submitted_answer": { "type": "object", "additionalProperties": true, "description": "The learner answer payload." }, "action_ts_ms": { "type": "integer", "description": "Client action timestamp (ms)." } } }, "AiOps_CertificateRevokeRequest": { "type": "object", "additionalProperties": false, "description": "Provide enrollment_id or serial.", "properties": { "enrollment_id": { "type": "string", "format": "uuid" }, "serial": { "type": "string", "minLength": 1, "maxLength": 64 }, "reason": { "type": "string", "maxLength": 2000 } } }, "AiOps_AssignRequest": { "type": "object", "additionalProperties": false, "required": [ "course_id", "user_ids" ], "properties": { "course_id": { "type": "string", "format": "uuid" }, "user_ids": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string", "format": "uuid" } }, "due_at": { "type": "string", "format": "date-time" } } }, "AiOps_RequiredSetRequest": { "type": "object", "additionalProperties": false, "required": [ "course_id" ], "properties": { "course_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "org", "role", "group", "user" ] }, "scope_ref": { "type": "string", "format": "uuid" }, "recurrence_interval": { "type": "string", "enum": [ "once", "annual", "biennial", "custom_days" ] }, "recurrence_days": { "type": "integer", "minimum": 1, "maximum": 36500 }, "is_active": { "type": "boolean" } } }, "AiOps_LearnerEraseRequest": { "type": "object", "additionalProperties": false, "required": [ "learner_user_id" ], "properties": { "learner_user_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "all", "course", "enrollment" ] }, "scope_ref": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 2000 } } }, "AiOps_AttemptGradeRequest": { "type": "object", "additionalProperties": false, "required": [ "attempt_id", "kind" ], "properties": { "attempt_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "override", "feedback" ] }, "new_score": { "type": "number" }, "new_is_correct": { "type": "boolean" }, "instructor_feedback": { "type": "string", "minLength": 1, "maxLength": 10000 }, "reason": { "type": "string", "maxLength": 2000 } } }, "Authentication_LookupRequest": { "type": "object", "description": "Request body for email lookup.", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 } }, "required": [ "email" ], "additionalProperties": false }, "Authentication_LookupResponse": { "type": "object", "properties": { "action": { "type": "string", "description": "Recommended login action: `password`, `passkey`, `sso`, or `register`." } }, "required": [ "action" ], "additionalProperties": false }, "Authentication_RegisterRequest": { "type": "object", "description": "Request body for new account registration.", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "password": { "type": "string", "minLength": 12, "maxLength": 128, "description": "Password meeting complexity requirements: uppercase, lowercase, digit, and special character. Must not appear in known breach databases." }, "displayName": { "type": "string", "minLength": 1, "maxLength": 100 }, "orgId": { "type": "string", "format": "uuid", "description": "Optional organization to join upon registration." } }, "required": [ "email", "password" ], "additionalProperties": false }, "Authentication_InitiateRequest": { "type": "object", "description": "Request body to initiate an email verification flow.", "properties": { "identifier": { "type": "string", "format": "email", "maxLength": 255 }, "identifier_type": { "type": "string", "enum": [ "email", "phone" ], "default": "email", "description": "Type of identifier. Currently only `email` is supported." } }, "required": [ "identifier" ], "additionalProperties": false }, "Authentication_InitiateResponse": { "type": "object", "properties": { "flow_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "required": [ "flow_id", "message" ], "additionalProperties": false }, "Authentication_RegistrationValidateRequest": { "type": "object", "description": "Request body to validate a registration verification code.", "properties": { "flow_id": { "type": "string", "format": "uuid" }, "verification_code": { "type": "string", "minLength": 1, "maxLength": 10 }, "identifier": { "type": "string", "format": "email", "maxLength": 255 } }, "required": [ "flow_id", "verification_code", "identifier" ], "additionalProperties": false }, "Authentication_CompleteRegistrationRequest": { "type": "object", "description": "Request body to complete an email-verified registration flow.", "properties": { "flow_id": { "type": "string", "format": "uuid" }, "verification_code": { "type": "string", "minLength": 1, "maxLength": 10 }, "identifier": { "type": "string", "format": "email", "maxLength": 255 }, "password": { "type": "string", "minLength": 12, "maxLength": 128, "description": "Password meeting complexity requirements. Must not appear in known breach databases." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "flow_id", "verification_code", "identifier", "password" ], "additionalProperties": false }, "Authentication_LoginRequest": { "type": "object", "description": "Request body for email/password login.", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "password": { "type": "string", "minLength": 1, "maxLength": 128 }, "mfaDeviceToken": { "type": "string", "minLength": 16, "maxLength": 128, "description": "Optional remembered-device token to bypass interactive MFA challenge." } }, "required": [ "email", "password" ], "additionalProperties": false }, "Authentication_RefreshRequest": { "type": "object", "description": "Request body for token refresh.", "properties": { "refreshToken": { "type": "string", "minLength": 1 } }, "required": [ "refreshToken" ], "additionalProperties": false }, "Authentication_SwitchOrgRequest": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" } }, "required": [ "org_id" ], "additionalProperties": false }, "Authentication_SwitchEnvRequest": { "type": "object", "properties": { "env_id": { "type": "string", "format": "uuid" } }, "required": [ "env_id" ], "additionalProperties": false }, "Authentication_GoogleOAuthRequest": { "type": "object", "description": "Request body for Google OAuth authentication.", "properties": { "code": { "type": "string", "minLength": 1, "description": "Authorization code from Google." }, "redirectUri": { "type": "string", "format": "uri", "description": "Redirect URI used in the OAuth flow (must be in the allowlist)." }, "mfaDeviceToken": { "type": "string", "minLength": 16, "maxLength": 128, "description": "Optional remembered-device token to bypass MFA challenge." }, "mfaDeviceTokens": { "type": "array", "items": { "type": "string", "minLength": 16, "maxLength": 128 }, "maxItems": 8, "description": "Optional array of device tokens for multi-org remembered-device bypass." } }, "required": [ "code", "redirectUri" ], "additionalProperties": false }, "Authentication_GoogleConfirmLinkRequest": { "type": "object", "properties": { "linkToken": { "type": "string", "minLength": 1, "description": "Token received from `/google-oauth` when `google_link_required` is returned." } }, "required": [ "linkToken" ], "additionalProperties": false }, "Authentication_OtpCreateRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "purpose": { "type": "string", "enum": [ "login", "verify_email", "reset_password" ] } }, "required": [ "email", "purpose" ], "additionalProperties": false }, "Authentication_OtpVerifyRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "code": { "type": "string", "minLength": 1, "maxLength": 10 }, "purpose": { "type": "string", "enum": [ "login", "verify_email", "reset_password" ] } }, "required": [ "email", "code", "purpose" ], "additionalProperties": false }, "Authentication_PasswordResetRequestBody": { "type": "object", "properties": { "identifier": { "type": "string", "format": "email", "maxLength": 255 } }, "required": [ "identifier" ], "additionalProperties": false }, "Authentication_PasswordResetBody": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "code": { "type": "string", "minLength": 1, "maxLength": 10 }, "new_password": { "type": "string", "minLength": 12, "maxLength": 128, "description": "New password meeting complexity requirements. Must not appear in known breach databases." } }, "required": [ "email", "code", "new_password" ], "additionalProperties": false }, "Authentication_PasswordChangeRequest": { "type": "object", "properties": { "old_password": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Current password. Required unless this is an initial password set." }, "new_password": { "type": "string", "minLength": 12, "maxLength": 128, "description": "New password meeting complexity requirements." } }, "required": [ "new_password" ], "additionalProperties": false }, "Authentication_PasskeyPrimaryOverrideRequest": { "type": "object", "properties": { "override": { "type": "string", "enum": [ "inherit", "force_on", "force_off" ] } }, "required": [ "override" ], "additionalProperties": false }, "Authentication_WebauthnAssertionOptions": { "type": "object", "properties": { "options": { "type": "object", "description": "WebAuthn PublicKeyCredentialRequestOptions." }, "assertion_nonce": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Nonce to submit alongside the credential in `/webauthn/assertion/verify`." } }, "required": [ "options", "assertion_nonce" ], "additionalProperties": false }, "Authentication_WebauthnAssertionVerifyRequest": { "type": "object", "properties": { "assertion_nonce": { "type": "string", "minLength": 1, "maxLength": 100 }, "credential": { "$ref": "#/components/schemas/Authentication_WebauthnCredential" } }, "required": [ "assertion_nonce", "credential" ], "additionalProperties": false }, "Authentication_WebauthnCredential": { "type": "object", "description": "WebAuthn PublicKeyCredential assertion.", "properties": { "id": { "type": "string" }, "rawId": { "type": "string" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string" }, "authenticatorData": { "type": "string" }, "signature": { "type": "string" }, "userHandle": { "type": "string" } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, "clientExtensionResults": { "type": "object" }, "type": { "type": "string", "enum": [ "public-key" ] }, "authenticatorAttachment": { "type": "string" } }, "required": [ "id", "rawId", "response", "type" ], "additionalProperties": false }, "Authentication_LandingHint": { "type": "object", "properties": { "recognized": { "type": "boolean", "description": "Whether the visitor appears to be a returning user." }, "passwordless_enabled": { "type": "boolean", "description": "Whether passwordless (passkey) login is enabled for this org." } }, "required": [ "recognized", "passwordless_enabled" ], "additionalProperties": false }, "Authentication_MeResponse": { "type": "object", "description": "Authenticated user identity and first-paint bootstrap data.", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "displayName": { "type": "string" }, "orgId": { "type": "string", "format": "uuid" }, "orgSlug": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "mfaEnabled": { "type": "boolean" }, "envId": { "type": "string", "format": "uuid" } }, "required": [ "id", "email", "orgId" ], "additionalProperties": true }, "Authentication_TokenPair": { "type": "object", "description": "Session token pair.", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token." }, "refreshToken": { "type": "string", "description": "Long-lived opaque refresh token." }, "accessTokenExpiresAt": { "type": "string", "format": "date-time" }, "refreshTokenExpiresAt": { "type": "string", "format": "date-time" } }, "required": [ "accessToken", "refreshToken", "accessTokenExpiresAt", "refreshTokenExpiresAt" ], "additionalProperties": false }, "Authentication_AuthResult": { "type": "object", "description": "Result of an authentication attempt. Exactly one of the discriminant fields is present.", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "accessTokenExpiresAt": { "type": "string", "format": "date-time" }, "refreshTokenExpiresAt": { "type": "string", "format": "date-time" }, "mfa_required": { "type": "boolean", "description": "When true, the user must complete an MFA challenge. Use `mfa_challenge_token` to call `/v1/mfa/challenge/*`." }, "mfa_challenge_token": { "type": "string", "description": "Short-lived JWT for MFA challenge flows. Present only when `mfa_required` is true." }, "mfa_enrollment_required": { "type": "boolean", "description": "When true, the user must enroll an MFA method. Use `mfa_enrollment_token` to call `/v1/mfa/*` enrollment endpoints." }, "mfa_enrollment_token": { "type": "string", "description": "Short-lived JWT for MFA enrollment flows. Present only when `mfa_enrollment_required` is true." } }, "additionalProperties": false }, "Authentication_GoogleOAuthResult": { "type": "object", "description": "Result of a Google OAuth authentication attempt.", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "accessTokenExpiresAt": { "type": "string", "format": "date-time" }, "refreshTokenExpiresAt": { "type": "string", "format": "date-time" }, "mfa_required": { "type": "boolean" }, "mfa_challenge_token": { "type": "string" }, "mfa_enrollment_required": { "type": "boolean" }, "mfa_enrollment_token": { "type": "string" }, "google_link_required": { "type": "boolean", "description": "When true, the Google identity matches an existing account but the accounts are not yet linked. Submit `linkToken` to `/google-oauth/confirm-link` while authenticated." }, "linkToken": { "type": "string", "description": "Token to pass to `/google-oauth/confirm-link`. Present only when `google_link_required` is true." } }, "additionalProperties": false }, "Authentication_DeviceAuthorizeRequest": { "type": "object", "description": "Request body to initiate the device authorization flow.", "properties": { "redirect_uri": { "type": "string", "format": "uri" }, "code_challenge": { "type": "string", "description": "PKCE S256 code challenge." }, "code_challenge_method": { "type": "string", "enum": [ "S256" ], "description": "Must be `S256`." }, "state": { "type": "string" } }, "required": [ "redirect_uri", "code_challenge" ], "additionalProperties": false }, "Authentication_DeviceAuthorizeResponse": { "type": "object", "properties": { "auth_url": { "type": "string", "format": "uri", "description": "URL the user should visit to authorize the device." }, "device_code": { "type": "string" }, "session_id": { "type": "string", "format": "uuid" }, "user_code": { "type": "string", "description": "Short alphanumeric code displayed to the user." }, "verification_uri": { "type": "string", "format": "uri" }, "verification_uri_complete": { "type": "string", "format": "uri", "description": "Verification URI with `user_code` pre-filled." }, "expires_in": { "type": "integer", "description": "Seconds until the device code expires." }, "interval": { "type": "integer", "description": "Minimum polling interval in seconds." } }, "required": [ "auth_url", "device_code", "session_id", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval" ], "additionalProperties": false }, "Authentication_DeviceCompleteRequest": { "type": "object", "properties": { "user_code": { "type": "string", "description": "The user code displayed on the device." } }, "required": [ "user_code" ], "additionalProperties": false }, "Authentication_DeviceCompleteResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "redirect_uri": { "type": "string", "format": "uri" }, "code": { "type": "string", "description": "Authorization code for the device to exchange." }, "state": { "type": "string" } }, "required": [ "success", "redirect_uri", "code" ], "additionalProperties": false }, "Authentication_DeviceTokenRequest": { "type": "object", "description": "Request body to exchange a device authorization code for tokens.", "properties": { "code": { "type": "string" }, "code_verifier": { "type": "string", "description": "PKCE verifier matching the challenge from `/device/authorize`." }, "grant_type": { "type": "string", "enum": [ "authorization_code" ] }, "token_type": { "type": "string", "enum": [ "jwt", "api_key" ], "description": "Requested token type. `api_key` (default) returns a long-lived opaque key; `jwt` returns a short-lived JWT with a refresh token." } }, "required": [ "code", "code_verifier", "grant_type" ], "additionalProperties": false }, "Authentication_DeviceTokenResponse": { "type": "object", "description": "RFC 6749 token response from the device token endpoint.", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer", "description": "Present for JWT token_type only." }, "refresh_token": { "type": "string", "description": "Present for JWT token_type only." } }, "required": [ "access_token", "token_type" ], "additionalProperties": false }, "Authentication_OAuthErrorResponse": { "type": "object", "description": "RFC 6749 / RFC 7591 error response.", "properties": { "error": { "type": "string", "description": "Machine-readable error code." }, "error_description": { "type": "string", "description": "Human-readable error description." } }, "required": [ "error" ], "additionalProperties": false }, "Authentication_MfaMethod": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "Method type: `totp`, `webauthn`, or `email_otp`." }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "webauthn_aaguid": { "type": "string" }, "webauthn_transports": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "type", "name", "created_at", "is_active" ], "additionalProperties": false }, "Authentication_TotpSetupRequest": { "type": "object", "properties": { "friendlyName": { "type": "string", "maxLength": 100 } }, "additionalProperties": false }, "Authentication_TotpSetupResponse": { "type": "object", "properties": { "methodId": { "type": "string", "format": "uuid" }, "secret": { "type": "string", "description": "Base32-encoded TOTP secret for manual entry." }, "uri": { "type": "string", "description": "otpauth:// URI for QR code generation." }, "encryptedSecret": { "type": "string", "description": "Encrypted secret to submit to `/totp/confirm`." }, "session": { "$ref": "#/components/schemas/Authentication_TokenPair" } }, "required": [ "methodId", "secret", "uri", "encryptedSecret" ], "additionalProperties": false }, "Authentication_TotpConfirmRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d+$", "description": "6-digit TOTP code." }, "methodId": { "type": "string", "format": "uuid" }, "encryptedSecret": { "type": "string", "minLength": 1 } }, "required": [ "code", "methodId", "encryptedSecret" ], "additionalProperties": false }, "Authentication_TotpChallengeRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d+$", "description": "6-digit TOTP code." }, "rememberDevice": { "type": "boolean" }, "rememberDeviceDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "deviceName": { "type": "string", "maxLength": 120 } }, "required": [ "code" ], "additionalProperties": false }, "Authentication_MfaEnrollResult": { "type": "object", "properties": { "verified": { "type": "boolean" }, "methodId": { "type": "string", "format": "uuid" }, "isFirstMethod": { "type": "boolean" }, "recoveryCodes": { "type": "array", "items": { "type": "string" }, "description": "One-time recovery codes. Only present when this is the first MFA method enrolled." }, "session": { "$ref": "#/components/schemas/Authentication_TokenPair" } }, "required": [ "verified", "methodId" ], "additionalProperties": false }, "Authentication_MfaChallengeResult": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "accessTokenExpiresAt": { "type": "string", "format": "date-time" }, "refreshTokenExpiresAt": { "type": "string", "format": "date-time" }, "mfaDeviceToken": { "type": "string", "description": "Device trust token for remembered-device bypass on future logins. Present only when `rememberDevice` was requested." } }, "required": [ "accessToken", "refreshToken", "accessTokenExpiresAt", "refreshTokenExpiresAt" ], "additionalProperties": false }, "Authentication_WebauthnChallengeOptions": { "type": "object", "properties": { "options": { "type": "object", "description": "WebAuthn PublicKeyCredentialRequestOptions or CreationOptions." }, "challenge_token": { "type": "string", "description": "HMAC-signed JWT challenge to submit with the credential verify call." } }, "required": [ "options", "challenge_token" ], "additionalProperties": false }, "Authentication_WebauthnRegisterVerifyRequest": { "type": "object", "properties": { "attestationResponse": { "type": "object", "properties": { "id": { "type": "string" }, "rawId": { "type": "string" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string" }, "attestationObject": { "type": "string" } }, "required": [ "clientDataJSON", "attestationObject" ], "additionalProperties": true }, "type": { "type": "string", "enum": [ "public-key" ] }, "friendlyName": { "type": "string", "maxLength": 100 } }, "required": [ "id", "rawId", "response", "type" ], "additionalProperties": true } }, "required": [ "attestationResponse" ], "additionalProperties": false }, "Authentication_WebauthnStepUpVerifyRequest": { "type": "object", "properties": { "credential": { "$ref": "#/components/schemas/Authentication_WebauthnCredential" }, "challenge_token": { "type": "string", "minLength": 8, "maxLength": 2048 }, "rememberDevice": { "type": "boolean" }, "rememberDeviceDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "deviceName": { "type": "string", "maxLength": 2048, "description": "Truncated to 100 characters server-side." } }, "additionalProperties": false }, "Authentication_WebauthnChallengeVerifyRequest": { "type": "object", "properties": { "credential": { "$ref": "#/components/schemas/Authentication_WebauthnCredential" }, "id": { "type": "string" }, "rawId": { "type": "string" }, "type": { "type": "string" }, "response": { "type": "object" }, "challenge_token": { "type": "string", "minLength": 8, "maxLength": 2048 }, "rememberDevice": { "type": "boolean" }, "rememberDeviceDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "deviceName": { "type": "string", "maxLength": 2048, "description": "Truncated to 100 characters server-side." } }, "additionalProperties": false }, "Authentication_EmailOtpSetupResponse": { "type": "object", "properties": { "methodId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "isFirstMethod": { "type": "boolean" }, "recoveryCodes": { "type": "array", "items": { "type": "string" } }, "session": { "$ref": "#/components/schemas/Authentication_TokenPair" } }, "required": [ "methodId", "email" ], "additionalProperties": false }, "Authentication_EmailOtpVerifyRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d+$" }, "rememberDevice": { "type": "boolean" }, "rememberDeviceDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "deviceName": { "type": "string", "maxLength": 120 } }, "required": [ "code" ], "additionalProperties": false }, "Authentication_EmailOtpSendResponse": { "type": "object", "properties": { "sent": { "type": "boolean" }, "email": { "type": "string", "description": "Masked email address (e.g. `u***@example.com`)." }, "expiresInMinutes": { "type": "integer" } }, "required": [ "sent", "email", "expiresInMinutes" ], "additionalProperties": false }, "Authentication_RecoveryCodeRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 8, "maxLength": 32 }, "rememberDevice": { "type": "boolean" }, "rememberDeviceDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "deviceName": { "type": "string", "maxLength": 120 } }, "required": [ "code" ], "additionalProperties": false }, "Authentication_MfaDeleteMethodResponse": { "type": "object", "properties": { "methodId": { "type": "string", "format": "uuid" }, "remainingMethods": { "type": "integer" }, "mfaDisenrolled": { "type": "boolean", "description": "True if all MFA methods have been removed." } }, "required": [ "methodId", "remainingMethods", "mfaDisenrolled" ], "additionalProperties": false }, "Authentication_MfaRenameRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ], "additionalProperties": false }, "Authentication_MfaRenameResponse": { "type": "object", "properties": { "methodId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "renamedAt": { "type": "string", "format": "date-time" } }, "required": [ "methodId", "name", "renamedAt" ], "additionalProperties": false }, "Authentication_RecoveryCodesResponse": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" }, "warning": { "type": "string", "description": "Advisory message reminding the user to store codes safely." } }, "required": [ "codes", "count" ], "additionalProperties": false }, "Authentication_OAuthProtectedResourceMeta": { "type": "object", "description": "RFC 9728 protected resource metadata.", "properties": { "resource": { "type": "string", "format": "uri" }, "authorization_servers": { "type": "array", "items": { "type": "string", "format": "uri" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } }, "resource_documentation": { "type": "string", "format": "uri" } }, "required": [ "resource", "authorization_servers" ], "additionalProperties": false }, "Authentication_OAuthAuthorizationServerMeta": { "type": "object", "description": "RFC 8414 authorization server metadata.", "properties": { "issuer": { "type": "string", "format": "uri" }, "authorization_endpoint": { "type": "string", "format": "uri" }, "token_endpoint": { "type": "string", "format": "uri" }, "registration_endpoint": { "type": "string", "format": "uri" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint" ], "additionalProperties": false }, "Authentication_OAuthClientRegistrationRequest": { "type": "object", "description": "RFC 7591 dynamic client registration request.", "properties": { "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1 }, "client_name": { "type": "string" } }, "required": [ "redirect_uris" ], "additionalProperties": false }, "Authentication_OAuthClientRegistrationResponse": { "type": "object", "description": "RFC 7591 dynamic client registration response.", "properties": { "client_id": { "type": "string" }, "client_id_issued_at": { "type": "integer", "description": "Unix timestamp of client creation." }, "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "grant_types": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "type": "string" }, "application_type": { "type": "string" } }, "required": [ "client_id", "client_id_issued_at", "redirect_uris" ], "additionalProperties": false }, "Authentication_OAuthTokenRequest": { "type": "object", "description": "OAuth 2.0 token request body.", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code" ] }, "code": { "type": "string" }, "code_verifier": { "type": "string", "description": "PKCE verifier." } }, "required": [ "grant_type", "code", "code_verifier" ], "additionalProperties": false }, "Authentication_OAuthTokenResponse": { "type": "object", "description": "RFC 6749 token response.", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ], "additionalProperties": false }, "Authentication_TotpStepUpRequest": { "type": "object", "description": "Request body for TOTP step-up. Only the 6-digit code is accepted; device-remember fields are not applicable to step-up.", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d+$", "description": "6-digit TOTP code from the authenticator app." } }, "required": [ "code" ], "additionalProperties": false }, "Authentication_DevPurgeTestOrgRequest": { "type": "object", "description": "Request body to purge a test organization. Only available in the development environment.", "properties": { "org_id": { "type": "string", "format": "uuid", "description": "UUID of the test organization to purge." }, "user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100, "description": "Optional list of specific user UUIDs to purge. When omitted, all users in the org are purged." } }, "required": [ "org_id" ], "additionalProperties": false }, "ProveOps_PinnedHash": { "type": "object", "additionalProperties": false, "description": "A content-hash pin entry. `hash` is a 64-character lowercase hex SHA-256; `pin_pinned` controls whether the hash is actively pinned.", "required": [ "hash", "pin_pinned" ], "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 content hash — 64 lowercase hex characters." }, "pin_pinned": { "type": "boolean", "description": "Whether the hash is currently pinned (`true`) or being unpinned (`false`)." } } }, "ProveOps_OperationRegisterRequest": { "type": "object", "additionalProperties": false, "description": "Request body for registering a solver-DAG operation.", "required": [ "scope", "name", "strategy_kind" ], "properties": { "scope": { "type": "string", "enum": [ "global", "tenant", "project" ], "description": "Visibility scope for the operation." }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Unique operation name within its scope." }, "strategy_kind": { "type": "string", "enum": [ "normalize_to_fixpoint", "pattern_isolate", "decision_procedure", "symbolic_rewrite", "compute", "custom" ], "description": "The rewrite strategy this operation implements." }, "project_scope_id": { "type": "string", "format": "uuid", "description": "Required when `scope=project`. Project identifier (UUIDv7)." }, "description": { "type": "string", "maxLength": 100000, "description": "Optional prose description." }, "strategy_config": { "type": "object", "additionalProperties": true, "description": "Optional strategy-specific configuration parameters." }, "parent_op_id": { "type": "string", "format": "uuid", "description": "Optional parent operation this one specializes (UUIDv7)." }, "rule_filter": { "type": "object", "additionalProperties": true, "description": "Optional filter expression applied during rule matching." }, "pinned_content_hashes": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/ProveOps_PinnedHash" }, "description": "Optional set of pinned content hashes (up to 1000)." }, "audit_notes": { "type": "string", "maxLength": 100000, "description": "Optional audit notes." } } }, "ProveOps_RuleRow": { "type": "object", "description": "An operation–theorem rewrite-rule association.", "required": [ "operation_id", "theorem_id" ], "properties": { "operation_id": { "type": "string", "format": "uuid", "description": "Owning operation identifier." }, "theorem_id": { "type": "string", "format": "uuid", "description": "Associated theorem identifier." }, "rule_order": { "type": "integer", "description": "Application priority (lower = higher priority)." }, "direction": { "type": "string", "enum": [ "forward", "backward", "both" ], "description": "Allowed application direction." }, "created_at": { "type": "string", "format": "date-time", "description": "When the rule was added." } } }, "ProveOps_OperationRow": { "type": "object", "description": "A solver-DAG operation record.", "required": [ "id", "scope", "name", "strategy_kind", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Operation identifier (UUIDv7)." }, "org_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Owning organization (null for global-scope operations)." }, "scope": { "type": "string", "enum": [ "global", "tenant", "project" ], "description": "Visibility scope." }, "name": { "type": "string", "description": "Operation name (unique within scope)." }, "strategy_kind": { "type": "string", "enum": [ "normalize_to_fixpoint", "pattern_isolate", "decision_procedure", "symbolic_rewrite", "compute", "custom" ], "description": "Strategy kind." }, "project_scope_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project scope id when `scope=project`." }, "description": { "type": [ "string", "null" ], "description": "Prose description." }, "strategy_config": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Strategy-specific configuration." }, "parent_op_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Parent operation id." }, "rule_filter": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Rule filter expression." }, "pinned_content_hashes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ProveOps_PinnedHash" }, "description": "Pinned content hashes." }, "is_superseded": { "type": "boolean", "description": "Whether this operation has been superseded." }, "superseded_by_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Id of the superseding operation (if superseded)." }, "rules": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ProveOps_RuleRow" }, "description": "Associated theorem rules (present only when `include_rules=true`)." }, "created_at": { "type": "string", "format": "date-time", "description": "Registration timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last-update timestamp." } } }, "ProveOps_RuleAddRequest": { "type": "object", "additionalProperties": false, "description": "Request body for tagging a theorem as a rewrite rule on a solver-DAG operation.", "required": [ "theorem_id" ], "properties": { "theorem_id": { "type": "string", "format": "uuid", "description": "Theorem to associate as a rewrite rule (UUIDv7)." }, "rule_order": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Optional priority order; lower values are applied first." }, "direction": { "type": "string", "enum": [ "forward", "backward", "both" ], "description": "Constrains the rule's application direction." }, "audit_notes": { "type": "string", "maxLength": 100000, "description": "Optional audit notes." } } }, "ProveOps_SupersedeRequest": { "type": "object", "additionalProperties": false, "description": "Request body for superseding (soft-retracting) a solver-DAG operation.", "required": [ "new_operation_id" ], "properties": { "new_operation_id": { "type": "string", "format": "uuid", "description": "The replacement operation (UUIDv7)." }, "audit_notes": { "type": "string", "maxLength": 100000, "description": "Optional audit notes." } } }, "ProveOps_TestCaseAddRequest": { "type": "object", "additionalProperties": false, "description": "Request body for adding a static test case to a solver-DAG operation.", "required": [ "scope", "input_latex" ], "properties": { "scope": { "type": "string", "enum": [ "global", "tenant", "project" ], "description": "Scope level for the test case." }, "input_latex": { "type": "string", "minLength": 1, "maxLength": 10000000, "description": "LaTeX source of the input expression (up to 10 MB)." }, "project_scope_id": { "type": "string", "format": "uuid", "description": "Required when `scope=project`. Project identifier (UUIDv7)." }, "expected_output": { "type": "string", "maxLength": 10000000, "description": "Optional expected output for oracle comparison (up to 10 MB)." }, "oracle_kind": { "type": "string", "enum": [ "exact", "sympy", "manual", "none" ], "description": "How the kernel evaluates the expected output against actual output." }, "audit_notes": { "type": "string", "maxLength": 100000, "description": "Optional audit notes." } } }, "ProveOps_TestCaseRow": { "type": "object", "description": "A static test case for a solver-DAG operation.", "required": [ "id", "operation_id", "scope", "input_latex", "is_active", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Test case identifier (UUIDv7)." }, "operation_id": { "type": "string", "format": "uuid", "description": "Owning operation identifier." }, "scope": { "type": "string", "enum": [ "global", "tenant", "project" ], "description": "Scope of the test case." }, "input_latex": { "type": "string", "description": "LaTeX input expression." }, "expected_output": { "type": [ "string", "null" ], "description": "Expected output for oracle comparison." }, "oracle_kind": { "type": [ "string", "null" ], "enum": [ "exact", "sympy", "manual", "none", null ], "description": "Oracle evaluation kind." }, "is_active": { "type": "boolean", "description": "`false` when the test case has been soft-deleted." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." } } }, "ProveOps_TenantBlockAddRequest": { "type": "object", "additionalProperties": false, "description": "Request body for adding a tenant-scope content hash block.", "required": [ "blocked_content_hash" ], "properties": { "blocked_content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 content hash to block — 64 lowercase hex characters." }, "project_scope_id": { "type": "string", "format": "uuid", "description": "Optional project scope restriction for the block (UUIDv7)." }, "block_reason": { "type": "string", "maxLength": 10000, "description": "Optional reason for blocking this content hash." } } }, "ProveOps_TenantBlockRow": { "type": "object", "description": "A tenant-scope content hash block record.", "required": [ "id", "blocked_content_hash", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Block identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Organization that owns this block." }, "blocked_content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Blocked SHA-256 content hash." }, "project_scope_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional project scope restriction." }, "block_reason": { "type": [ "string", "null" ], "description": "Reason for the block." }, "created_by": { "type": [ "string", "null" ], "format": "uuid", "description": "User who created the block." }, "created_at": { "type": "string", "format": "date-time", "description": "When the block was created." } } }, "ProveOps_TheoremRegisterRequest": { "type": "object", "additionalProperties": false, "description": "Request body for registering a solver-DAG theorem.", "required": [ "scope", "name", "proof_latex", "conclusion" ], "properties": { "scope": { "type": "string", "enum": [ "global", "tenant", "project" ], "description": "Visibility scope for the theorem." }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Unique theorem name within its scope." }, "proof_latex": { "type": "string", "minLength": 1, "maxLength": 10000000, "description": "Full LaTeX proof source (up to 10 MB)." }, "conclusion": { "type": "string", "minLength": 1, "maxLength": 1000000, "description": "Formal statement of the theorem's conclusion (up to 1 MB)." }, "project_scope_id": { "type": "string", "format": "uuid", "description": "Required when `scope=project`. Project identifier (UUIDv7)." }, "dep_theorem_ids": { "type": "array", "maxItems": 1000, "items": { "type": "string", "format": "uuid" }, "description": "Optional dependency theorem ids (up to 1000)." }, "pinned_content_hashes": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/ProveOps_PinnedHash" }, "description": "Optional content-hash pins (up to 1000)." }, "proof_class": { "type": "string", "enum": [ "equational_unconditional", "equational_unscoped", "implicational", "propositional", "unaudited" ], "description": "Classification of the proof's audit status." }, "kernel_verified": { "type": "boolean", "description": "When `true`, marks this theorem as kernel-verified. Requires platform-staff permission (`bbprove.global.write`)." }, "audit_notes": { "type": "string", "maxLength": 100000, "description": "Optional audit notes." } } }, "ProveOps_TheoremRow": { "type": "object", "description": "A solver-DAG theorem record.", "required": [ "id", "scope", "name", "conclusion", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Theorem identifier (UUIDv7)." }, "org_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Owning organization (null for global-scope theorems)." }, "scope": { "type": "string", "enum": [ "global", "tenant", "project" ], "description": "Visibility scope." }, "name": { "type": "string", "description": "Theorem name (unique within scope)." }, "conclusion": { "type": "string", "description": "Formal conclusion statement." }, "proof_class": { "type": [ "string", "null" ], "enum": [ "equational_unconditional", "equational_unscoped", "implicational", "propositional", "unaudited", null ], "description": "Proof audit classification." }, "kernel_verified": { "type": "boolean", "description": "Whether the theorem is kernel-verified." }, "project_scope_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project scope id when `scope=project`." }, "dep_theorem_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Dependency theorem ids." }, "pinned_content_hashes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ProveOps_PinnedHash" }, "description": "Pinned content hashes." }, "is_superseded": { "type": "boolean", "description": "Whether this theorem has been superseded." }, "superseded_by_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Id of the superseding theorem (if superseded)." }, "created_at": { "type": "string", "format": "date-time", "description": "Registration timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last-update timestamp." } } }, "ProveOps_TheoremSupersedeRequest": { "type": "object", "additionalProperties": false, "description": "Request body for superseding a DAG theorem.", "required": [ "new_theorem_id" ], "properties": { "new_theorem_id": { "type": "string", "format": "uuid", "description": "The replacement theorem (UUIDv7)." }, "audit_notes": { "type": "string", "maxLength": 100000, "description": "Optional audit notes." } } }, "ProveOps_ArtifactEdge": { "type": "object", "description": "A directed dependency edge between two artifact nodes.", "required": [ "source", "target" ], "properties": { "source": { "type": "string", "format": "uuid", "description": "Source artifact identifier (UUIDv7)." }, "target": { "type": "string", "format": "uuid", "description": "Target artifact identifier (UUIDv7)." }, "edge_kind": { "type": [ "string", "null" ], "description": "Optional semantic relationship kind (e.g. `depends_on`, `discharges`)." } } }, "ProveOps_ArtifactSummary": { "type": "object", "description": "Summary view of a kernel artifact, used in graph nodes and table rows.", "required": [ "id", "kind", "state" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Artifact identifier (UUIDv7)." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project." }, "kind": { "type": "string", "enum": [ "hypothesis", "prediction", "observation", "definition", "obligation", "discharge", "theorem", "lemma", "corollary", "proposition" ], "description": "Artifact kind." }, "state": { "type": "string", "enum": [ "draft", "submitted", "pending", "suggestive", "corroborated", "discharged", "accepted_unverified", "accepted_pending_promotion", "provisional", "promoted", "rejected", "refuted", "stale", "superseded" ], "description": "Current lifecycle state." }, "name": { "type": [ "string", "null" ], "description": "Artifact name or label." }, "source_path": { "type": [ "string", "null" ], "description": "Source file path." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last-update timestamp." } } }, "ProveOps_ArtifactGraph": { "type": "object", "description": "Directed acyclic graph of proof artifacts and their dependency edges.", "required": [ "nodes", "edges" ], "properties": { "nodes": { "type": "array", "description": "Artifact nodes.", "items": { "$ref": "#/components/schemas/ProveOps_ArtifactSummary" } }, "edges": { "type": "array", "description": "Dependency edges.", "items": { "$ref": "#/components/schemas/ProveOps_ArtifactEdge" } } } }, "ProveOps_ArtifactDetail": { "type": "object", "description": "Full artifact record with associated kernel run and source document.", "required": [ "artifact" ], "properties": { "artifact": { "$ref": "#/components/schemas/ProveOps_ArtifactSummary" }, "kernel_run": { "description": "The kernel run that produced this artifact, if available.", "oneOf": [ { "$ref": "#/components/schemas/ProveOps_KernelRunLog" }, { "type": "null" } ] }, "document": { "description": "Source document metadata, if available.", "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "version": { "type": "integer" } } }, { "type": "null" } ] } } }, "ProveOps_ArtifactTransition": { "type": "object", "description": "A single state-transition event in an artifact's history.", "required": [ "from_state", "to_state", "transitioned_at" ], "properties": { "from_state": { "type": [ "string", "null" ], "description": "Previous state (null for initial creation)." }, "to_state": { "type": "string", "description": "New state after the transition." }, "triggered_by": { "type": [ "string", "null" ], "description": "Who or what triggered the transition." }, "run_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Associated kernel run identifier, if any." }, "transitioned_at": { "type": "string", "format": "date-time", "description": "Transition timestamp." } } }, "ProveOps_SemanticSearchRequest": { "type": "object", "description": "Request body for hybrid semantic search over proof source documents.", "required": [ "q" ], "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Natural-language search query. Control characters (except `\\n`/`\\t`) are rejected." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum results to return (default 10)." }, "threshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum similarity score floor (default 0.3)." } } }, "ProveOps_SemanticSearchResult": { "type": "object", "description": "A single document result from hybrid semantic search.", "properties": { "document_id": { "type": "string", "format": "uuid", "description": "Matching document version identifier." }, "path": { "type": "string", "description": "Document path within the project." }, "score": { "type": "number", "description": "Similarity score (0–1)." }, "snippet": { "type": [ "string", "null" ], "description": "Relevant excerpt from the document source." } } }, "ProveOps_GraphLayoutNode": { "type": "object", "description": "A single node's persisted position in the graph layout.", "required": [ "id", "x", "y" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Artifact node identifier." }, "x": { "type": "number", "description": "X coordinate (finite)." }, "y": { "type": "number", "description": "Y coordinate (finite)." } } }, "ProveOps_GraphLayoutViewport": { "type": "object", "additionalProperties": false, "description": "Persisted viewport state for the graph layout.", "properties": { "zoom": { "type": "number", "minimum": 0.05, "maximum": 20, "description": "Camera zoom level (0.05–20)." }, "panX": { "type": "number", "description": "Horizontal pan offset." }, "panY": { "type": "number", "description": "Vertical pan offset." } } }, "ProveOps_GraphLayout": { "type": "object", "description": "A persisted proof artifact graph layout for a specific user and project.", "required": [ "nodes", "viewport", "updated_at" ], "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/ProveOps_GraphLayoutNode" }, "description": "Persisted node positions." }, "viewport": { "$ref": "#/components/schemas/ProveOps_GraphLayoutViewport" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the layout was last saved." } } }, "ProveOps_GraphLayoutPutRequest": { "type": "object", "description": "Request body for saving (or clearing) a graph layout.", "required": [ "nodes" ], "properties": { "nodes": { "type": "array", "maxItems": 5000, "items": { "$ref": "#/components/schemas/ProveOps_GraphLayoutNode" }, "description": "Node positions to persist (up to 5000). An empty array with no `viewport` clears the layout." }, "viewport": { "$ref": "#/components/schemas/ProveOps_GraphLayoutViewport" } } }, "ProveOps_KernelRunLog": { "type": "object", "description": "Metadata and AI-verdict record for a single kernel verification run.", "required": [ "run_id", "state", "triggered_by", "queued_at", "document_id", "document_version", "document_path" ], "properties": { "run_id": { "type": "string", "format": "uuid", "description": "Kernel run identifier (UUIDv7)." }, "state": { "type": "string", "description": "Current run state (e.g. `queued`, `running`, `done`, `failed`)." }, "verdict_summary": { "type": [ "string", "null" ], "description": "Human-readable verdict from the kernel or AI grader." }, "log_uri": { "type": [ "string", "null" ], "description": "URI to the full kernel log output." }, "exit_code": { "type": [ "integer", "null" ], "description": "Exit code of the kernel process (`0` = success)." }, "triggered_by": { "type": "string", "description": "Who or what initiated the run." }, "queued_at": { "type": "string", "format": "date-time", "description": "When the run was queued." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the kernel process started." }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the kernel process completed." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Wall-clock duration in milliseconds." }, "document_id": { "type": "string", "format": "uuid", "description": "Source document version identifier (UUIDv7)." }, "document_version": { "type": "integer", "description": "Document version number submitted." }, "document_path": { "type": "string", "description": "Document path within the project." }, "ai_check_result": { "type": [ "object", "null" ], "additionalProperties": true, "description": "AI grader result object when `enable_ai_check=true`. Shape is model-defined." } } }, "ProveOps_SubmissionCreateRequest": { "type": "object", "description": "Request body for submitting a document for kernel evaluation.", "required": [ "documentId" ], "properties": { "documentId": { "type": "string", "format": "uuid", "description": "Document version identifier (UUIDv7). The server resolves the current HEAD for the document chain." }, "enableAiCheck": { "type": "boolean", "description": "Optional override for the AI grader stage. When omitted, the server resolves through the per-document → per-user-per-project → per-project → platform-default fallback chain." } } }, "ProveOps_SubmissionCreateResult": { "type": "object", "description": "Result of a document submission.", "required": [ "run_id", "queued_at", "state", "document_id", "document_version", "document_path", "triggered_by" ], "properties": { "run_id": { "type": "string", "format": "uuid", "description": "Kernel run identifier (UUIDv7)." }, "queued_at": { "type": "string", "format": "date-time", "description": "When the run was queued." }, "state": { "type": "string", "description": "Initial run state (`queued`)." }, "document_id": { "type": "string", "format": "uuid", "description": "HEAD document version submitted." }, "document_version": { "type": "integer", "description": "HEAD document version number." }, "document_path": { "type": "string", "description": "Document path." }, "triggered_by": { "type": "string", "description": "Trigger source (`submission`)." }, "root_run_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Root run identifier if part of a multi-run chain." }, "queue_warning": { "type": [ "string", "null" ], "description": "Non-null if the background job queue was unavailable. The run row exists regardless." } } }, "ProveOps_WebhookDelivery": { "type": "object", "description": "A single webhook delivery audit record.", "required": [ "id", "webhook_id", "event_type", "attempted_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Delivery record identifier (UUIDv7)." }, "webhook_id": { "type": "string", "format": "uuid", "description": "Parent webhook identifier." }, "event_type": { "type": "string", "description": "Prove event type that triggered this delivery." }, "attempt_number": { "type": "integer", "description": "1-based retry attempt number." }, "http_status": { "type": [ "integer", "null" ], "description": "HTTP status code returned by the recipient, or null if the request failed before a response." }, "success": { "type": "boolean", "description": "Whether the delivery was considered successful (2xx response)." }, "error_message": { "type": [ "string", "null" ], "description": "Error description when `success=false`." }, "attempted_at": { "type": "string", "format": "date-time", "description": "When the delivery was attempted." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Request round-trip duration in milliseconds." } } }, "ProveDocs_DocumentVersion": { "type": "object", "description": "A single versioned snapshot of a Backbuild Prove document.", "required": [ "id", "org_id", "project_id", "path", "version", "format", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Version-row identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project." }, "path": { "type": "string", "description": "Project-relative canonical file path (e.g. `ch01/main.pf2`)." }, "version": { "type": "integer", "description": "Monotonically increasing version number within the (project, path) chain." }, "format": { "type": "string", "enum": [ "pf2", "amsthm" ], "description": "Document source format." }, "content": { "type": [ "string", "null" ], "description": "Full source content. May be omitted in list responses." }, "content_hash": { "type": [ "string", "null" ], "description": "SHA-256 hex digest of the stored content." }, "parent_version_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Id of the preceding version in the chain; null for the first version." }, "created_by": { "type": [ "string", "null" ], "format": "uuid", "description": "User who created this version." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this version was created." } } }, "ProveDocs_DocumentSaveRequest": { "type": "object", "additionalProperties": false, "description": "Save-document request body.", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Project-relative file path. Must be canonical: no leading slash, no `.` or `..` segments, no null bytes, no backslashes, not double-encoded, not an absolute Windows path, not starting with `//`." }, "content": { "type": "string", "maxLength": 10000000, "description": "Full document source content (≤ 10 MB)." }, "format": { "type": "string", "enum": [ "pf2", "amsthm" ], "description": "Source format. Defaults to `pf2` when omitted." }, "document_id": { "type": "string", "format": "uuid", "description": "Optional. When supplied, anchors the new version onto the existing document chain with this id. Omit to start a new chain." } } }, "ProveDocs_DocumentAiPref": { "type": "object", "description": "Per-user per-document AI-check preference.", "required": [ "enable_ai_check" ], "properties": { "enable_ai_check": { "type": [ "boolean", "null" ], "description": "Whether AI checking is enabled for this document for the calling user. `null` means no per-document override is set; the effective value is determined by the per-user-per-project preference then the project default." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the preference was last updated. `null` when no override exists." } } }, "ProveDocs_PdfBuildRequest": { "type": "object", "additionalProperties": false, "description": "Optional PDF build configuration.", "properties": { "theme": { "type": "string", "maxLength": 64, "description": "PDF theme identifier (e.g. `default`, `book`, `bw`). Falls back to project default when omitted." }, "primaryLanguage": { "type": "string", "maxLength": 32, "description": "BCP-47 language tag for the primary document language (e.g. `en`, `fr`, `zh-Hans`). Falls back to project default when omitted." }, "compress": { "type": "boolean", "description": "Whether to compress the output PDF. Defaults to `true`." }, "idempotent": { "type": "boolean", "description": "When `true` (default), an existing `done` build for the same inputs is returned without creating a new one." } } }, "ProveDocs_PdfBuildCreateResult": { "type": "object", "description": "PDF build row returned after a submit or reuse.", "required": [ "build_id", "org_id", "project_id", "document_id", "document_version", "status", "compress", "triggered_by", "queued_at", "reused" ], "properties": { "build_id": { "type": "string", "format": "uuid", "description": "Build identifier." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project." }, "document_id": { "type": "string", "format": "uuid", "description": "Document identifier." }, "document_version": { "type": "integer", "description": "Document version that was submitted." }, "document_path": { "type": "string", "description": "Document file path." }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ], "description": "Current build status." }, "r2_key": { "type": [ "string", "null" ], "description": "Storage key for the rendered PDF (present when `status` is `done`)." }, "byte_size": { "type": [ "integer", "null" ], "description": "PDF byte size (present when `status` is `done`)." }, "page_count": { "type": [ "integer", "null" ], "description": "Number of pages (present when `status` is `done`)." }, "theme": { "type": [ "string", "null" ], "description": "Theme used for this build." }, "primary_language": { "type": [ "string", "null" ], "description": "Language tag used for this build." }, "compress": { "type": "boolean", "description": "Whether compression was applied." }, "triggered_by": { "type": "string", "description": "How the build was triggered (e.g. `user`)." }, "queued_at": { "type": "string", "format": "date-time", "description": "When the build was enqueued." }, "reused": { "type": "boolean", "description": "True when an existing `done` build was returned unchanged." }, "queue_warning": { "type": [ "string", "null" ], "description": "Non-null when the internal build queue was unavailable. The build row was still created." } } }, "ProveDocs_PdfBuildRow": { "type": "object", "description": "A PDF build status record.", "required": [ "build_id", "org_id", "project_id", "document_id", "document_version", "status", "compress", "triggered_by", "created_by", "queued_at", "updated_at" ], "properties": { "build_id": { "type": "string", "format": "uuid", "description": "Build identifier." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project." }, "document_id": { "type": "string", "format": "uuid", "description": "Document identifier." }, "document_version": { "type": "integer", "description": "Document version that was submitted." }, "document_path": { "type": "string", "description": "Document file path." }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ], "description": "Build status." }, "r2_key": { "type": [ "string", "null" ], "description": "Storage key for the rendered PDF." }, "byte_size": { "type": [ "integer", "null" ], "description": "PDF byte size." }, "page_count": { "type": [ "integer", "null" ], "description": "Number of pages." }, "content_hash": { "type": [ "string", "null" ], "description": "SHA-256 digest of the rendered PDF." }, "theme": { "type": [ "string", "null" ], "description": "Theme." }, "primary_language": { "type": [ "string", "null" ], "description": "Language tag." }, "compress": { "type": "boolean", "description": "Whether compression was applied." }, "error_message": { "type": [ "string", "null" ], "description": "Error message when `status` is `failed`." }, "error_log_r2_key": { "type": [ "string", "null" ], "description": "Storage key for the captured builder log, present on failed builds that captured output." }, "triggered_by": { "type": "string", "description": "How the build was triggered." }, "created_by": { "type": "string", "format": "uuid", "description": "User who triggered the build." }, "queued_at": { "type": "string", "format": "date-time", "description": "When queued." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When processing began." }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When processing finished." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Total processing time in milliseconds." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last status update timestamp." } } }, "ProveDocs_PdfSettings": { "type": "object", "description": "Per-project PDF build default settings.", "required": [ "org_id", "project_id", "theme", "primary_language", "is_default" ], "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project." }, "theme": { "type": "string", "enum": [ "default", "book", "bw" ], "description": "Default PDF theme." }, "primary_language": { "type": "string", "description": "Default BCP-47 language tag." }, "is_default": { "type": "boolean", "description": "True when these are the platform defaults (no custom row saved yet)." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the settings row was created." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the settings row was last updated." }, "updated_by": { "type": [ "string", "null" ], "format": "uuid", "description": "User who last updated the settings." } } }, "ProveDocs_PdfSettingsRequest": { "type": "object", "additionalProperties": false, "description": "Update PDF settings request body. At least one field must be present.", "minProperties": 1, "properties": { "theme": { "type": "string", "enum": [ "default", "book", "bw" ], "description": "New default PDF theme." }, "primaryLanguage": { "type": "string", "minLength": 2, "maxLength": 35, "description": "New default BCP-47 language tag (e.g. `en`, `fr`, `zh-Hans`). Must match the pattern: 2–3 letter base language optionally followed by hyphen-separated subtags." } } }, "ProveDocs_AssetUploadResult": { "type": "object", "description": "Asset upload result. All metadata values (dimensions, size, frame count) are decoder-measured and authoritative — they are never client-asserted.", "required": [ "relPath", "sha256", "ext", "width", "height", "byte_size", "frame_count" ], "properties": { "relPath": { "type": "string", "description": "Project-relative path the editor writes into `\\includegraphics{...}` (e.g. `.bbassets//.`)." }, "sha256": { "type": "string", "description": "SHA-256 hex digest of the stored (sanitized) bytes. Also the content-address used to retrieve the asset." }, "asset_sha": { "type": "string", "description": "Alias for `sha256` (both fields are present for client compatibility)." }, "ext": { "type": "string", "enum": [ "png", "jpg", "gif", "webp", "svg" ], "description": "File extension derived from the sniffed MIME type." }, "width": { "type": "integer", "description": "Image width in pixels (decoder-measured)." }, "height": { "type": "integer", "description": "Image height in pixels (decoder-measured)." }, "width_px": { "type": "integer", "description": "Alias for `width`." }, "height_px": { "type": "integer", "description": "Alias for `height`." }, "byte_size": { "type": "integer", "description": "Stored byte size of the (sanitized) image." }, "frame_count": { "type": "integer", "description": "Number of animation frames (1 for static images)." } } }, "ProveDocs_DraftMeta": { "type": "object", "description": "Draft metadata returned after an upsert (content is not echoed).", "required": [ "org_id", "project_id", "path", "format", "created_at", "updated_at" ], "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project." }, "path": { "type": "string", "description": "Canonical file path." }, "base_version_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The document version the draft was based on, if supplied." }, "base_version": { "type": [ "integer", "null" ], "description": "The version number the draft was based on, if supplied." }, "content_hash": { "type": "string", "description": "SHA-256 hex digest of the stored draft content." }, "format": { "type": "string", "enum": [ "pf2", "amsthm" ], "description": "Source format." }, "created_at": { "type": "string", "format": "date-time", "description": "When the draft was first created." }, "created_by": { "type": "string", "format": "uuid", "description": "User who created the draft." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the draft was last saved." }, "updated_by": { "type": "string", "format": "uuid", "description": "User who last saved the draft." } } }, "ProveDocs_DraftFull": { "allOf": [ { "$ref": "#/components/schemas/ProveDocs_DraftMeta" }, { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "Full draft source content." } } } ], "description": "Full draft record including content, returned by the GET endpoint." }, "ProveDocs_DraftGetResult": { "type": "object", "description": "Stable draft-existence envelope. `exists` is always present.", "required": [ "exists" ], "properties": { "exists": { "type": "boolean", "description": "Whether a draft exists for `(project, path)`." }, "draft": { "$ref": "#/components/schemas/ProveDocs_DraftFull", "description": "Full draft record, present only when `exists` is `true`." } } }, "ProveDocs_DraftSaveRequest": { "type": "object", "additionalProperties": false, "description": "Draft upsert request body.", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Project-relative canonical file path. Subject to the same canonicalization rules as the document save endpoint." }, "content": { "type": "string", "maxLength": 10000000, "description": "Full draft content (≤ 10 MB)." }, "format": { "type": "string", "enum": [ "pf2", "amsthm" ], "description": "Source format. Defaults to `pf2` when omitted." }, "baseVersionId": { "type": "string", "format": "uuid", "description": "Optional. The document version id the draft was based on (for 3-way merge conflict detection at publish time)." }, "baseVersion": { "type": "integer", "minimum": 0, "description": "Optional. The version number the draft was based on." } } }, "ProveDocs_DraftPublishResult": { "type": "object", "description": "Result of a successful draft publish operation.", "required": [ "documentId", "version", "contentHash", "format", "createdAt", "createdBy" ], "properties": { "documentId": { "type": "string", "format": "uuid", "description": "The new document version id." }, "version": { "type": "integer", "description": "The newly created version number." }, "parentVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The version id this build was based on." }, "contentHash": { "type": "string", "description": "SHA-256 hex digest of the committed content." }, "format": { "type": "string", "enum": [ "pf2", "amsthm" ], "description": "Source format." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp of the new version." }, "createdBy": { "type": "string", "format": "uuid", "description": "User who published." } } }, "ProveDocs_DocumentAiPrefSetRequest": { "type": "object", "additionalProperties": false, "description": "Set AI-check preference request body.", "required": [ "enable_ai_check" ], "properties": { "enable_ai_check": { "type": "boolean", "description": "Whether AI checking should be enabled for this document for the calling user." } } }, "ProveDocs_PredictionSummary": { "type": "object", "description": "A prediction summary as returned in list responses.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Prediction identifier." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project." }, "label": { "type": "string", "description": "Short machine-readable label from the `\\prediction` macro." }, "name": { "type": "string", "description": "Human-readable prediction name." }, "parent_hypothesis_id": { "type": "string", "format": "uuid", "description": "Parent hypothesis identifier." }, "source_file_path": { "type": [ "string", "null" ], "description": "Source document path where the macro was defined." }, "source_line_start": { "type": [ "integer", "null" ], "description": "Starting source line." }, "source_line_end": { "type": [ "integer", "null" ], "description": "Ending source line." } } }, "ProveDocs_PredictionDetail": { "allOf": [ { "$ref": "#/components/schemas/ProveDocs_PredictionSummary" }, { "type": "object", "properties": { "prose": { "type": "string", "description": "Full prose statement of the prediction." }, "derivation_latex": { "type": "string", "description": "LaTeX derivation block." }, "observables": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Structured observable definitions linked to this prediction." }, "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Computational evidence records attached to this prediction." } } } ], "description": "Full prediction record with observables and evidence." }, "ProveDocs_Discovery": { "type": "object", "description": "A 5σ discovery artifact.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Discovery artifact identifier." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project." }, "parent_hypothesis_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Parent hypothesis, if applicable." }, "is_discovery": { "type": "boolean", "enum": [ true ], "description": "Always `true` for this feed." }, "first_discovered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the artifact first exceeded the 5σ threshold." }, "created_at": { "type": "string", "format": "date-time", "description": "Artifact creation timestamp." } } }, "ProveDocs_TheoremExportRequest": { "type": "object", "additionalProperties": false, "description": "Theorem export request body.", "required": [ "format" ], "properties": { "format": { "type": "string", "enum": [ "pdf", "json", "tex" ], "description": "Export format. `tex` and `json` complete synchronously with inline content. `pdf` is asynchronous — poll the `poll_url` for completion." } } }, "ProveDocs_TheoremExportCreateResult": { "type": "object", "description": "Theorem export create result.", "required": [ "export_id", "status", "format", "poll_url" ], "properties": { "export_id": { "type": "string", "format": "uuid", "description": "Export identifier." }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ], "description": "Export status. `tex`/`json` are immediately `done`." }, "format": { "type": "string", "enum": [ "pdf", "json", "tex" ], "description": "Export format." }, "signing_key_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Signing key used, if any." }, "signing_key_fingerprint_hex": { "type": [ "string", "null" ], "description": "Hex fingerprint of the signing key." }, "signed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when signed." }, "pdf_build_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Underlying PDF build id for `pdf` format exports." }, "content": { "type": [ "string", "null" ], "description": "Inline content for synchronous `tex`/`json` exports." }, "content_url": { "type": [ "string", "null" ], "description": "Download URL when content is available." }, "poll_url": { "type": "string", "description": "URL to poll for status on async exports (points to `/v1/bbprove/theorem-exports/{exportId}`)." }, "queue_warning": { "type": [ "string", "null" ], "description": "Non-null if the PDF build queue was unavailable at submission time." } } }, "ProveDocs_TheoremExportRow": { "type": "object", "description": "Theorem export status record.", "required": [ "export_id", "project_id", "artifact_id", "format", "status", "created_at" ], "properties": { "export_id": { "type": "string", "format": "uuid", "description": "Export identifier." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project." }, "artifact_id": { "type": "string", "format": "uuid", "description": "Source theorem artifact." }, "format": { "type": "string", "enum": [ "pdf", "json", "tex" ], "description": "Export format." }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ], "description": "Export status." }, "signing_key_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Signing key used." }, "signed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When signed." }, "content": { "type": [ "string", "null" ], "description": "Inline content for `tex`/`json` formats." }, "content_url": { "type": [ "string", "null" ], "description": "Download URL." }, "r2_key": { "type": [ "string", "null" ], "description": "Storage key for PDF exports." }, "byte_size": { "type": [ "integer", "null" ], "description": "Content byte size." }, "pdf_build_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Underlying PDF build id." }, "error_message": { "type": [ "string", "null" ], "description": "Error message for failed exports." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Completion timestamp." } } }, "ProveDocs_RealtimeTicket": { "type": "object", "description": "A single-use realtime WebSocket subscription ticket.", "required": [ "ticket", "expiresInSeconds", "room" ], "properties": { "ticket": { "type": "string", "description": "Opaque single-use ticket string. Pass as `?token=` on the WebSocket upgrade to `GET /v1/collaboration/ws`." }, "expiresInSeconds": { "type": "integer", "description": "Seconds until the ticket expires (currently 60)." }, "room": { "type": "string", "description": "Room name to join after the WebSocket connects. Send `{ type: 'join_room', roomId: room }` over the WebSocket." } } }, "ProveDocs_ProjectSettings": { "type": "object", "description": "Per-project Proofs browser settings.", "required": [ "default_visibility", "default_ai_check", "is_default" ], "properties": { "default_visibility": { "type": "string", "enum": [ "private", "org_shared", "public_published" ], "description": "Default visibility for new documents in this project." }, "default_ai_check": { "type": "boolean", "description": "Default AI-check enabled state for new documents." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When settings were last updated." }, "updated_by": { "type": [ "string", "null" ], "format": "uuid", "description": "User who last updated settings." }, "is_default": { "type": "boolean", "description": "True when no custom row has been saved and these are the platform defaults." } } }, "ProveDocs_ProjectSettingsRequest": { "type": "object", "additionalProperties": false, "description": "Update project settings request body. At least one of `default_visibility` or `default_ai_check` must be present.", "properties": { "default_visibility": { "type": "string", "enum": [ "private", "org_shared", "public_published" ], "description": "New default document visibility." }, "default_ai_check": { "type": "boolean", "description": "New default AI-check state." } } }, "ProveDocs_UserProjectPrefs": { "type": "object", "description": "Per-user per-project Prove preferences with effective AI-check value.", "required": [ "project_default_ai_check", "effective_ai_check" ], "properties": { "default_ai_check_user_override": { "type": [ "boolean", "null" ], "description": "User's AI-check override for this project. `null` means no override is set." }, "project_default_ai_check": { "type": "boolean", "description": "The project-level default AI-check value." }, "effective_ai_check": { "type": "boolean", "description": "The resolved AI-check value after applying override → project default fallback." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the user preference was last updated." } } }, "ProveDocs_UserProjectPrefsRequest": { "type": "object", "additionalProperties": false, "description": "Update user Prove preferences request body.", "required": [ "default_ai_check_user_override" ], "properties": { "default_ai_check_user_override": { "type": [ "boolean", "null" ], "description": "AI-check override for this project. `true`/`false` sets the override; `null` clears it so the project default applies. The key must be present (omitting it is rejected)." } } }, "ProveDocs_ShareCreateRequest": { "type": "object", "additionalProperties": false, "description": "Share grant request body.", "required": [ "target_kind", "target_id", "recipient_org_id", "can_edit" ], "properties": { "target_kind": { "type": "string", "enum": [ "document", "artifact" ], "description": "The kind of resource being shared." }, "target_id": { "type": "string", "format": "uuid", "description": "The resource identifier to share (UUIDv7)." }, "recipient_org_id": { "type": "string", "format": "uuid", "description": "The organization to share with (UUIDv7)." }, "can_edit": { "type": "boolean", "description": "Whether the recipient can edit the shared resource. When `true`, `granted_by_policy_id` is required." }, "granted_by_policy_id": { "type": "string", "format": "uuid", "description": "Required when `can_edit=true`. The policy that authorizes write-sharing." } } }, "ProveDocs_Share": { "type": "object", "description": "A cross-organization share record.", "properties": { "share_id": { "type": "string", "format": "uuid", "description": "Share identifier." }, "owner_org_id": { "type": "string", "format": "uuid", "description": "The organization that granted the share." }, "recipient_org_id": { "type": "string", "format": "uuid", "description": "The organization receiving the share." }, "target_kind": { "type": "string", "enum": [ "document", "artifact" ], "description": "The kind of shared resource." }, "target_id": { "type": "string", "format": "uuid", "description": "The shared resource identifier." }, "can_edit": { "type": "boolean", "description": "Whether the recipient has edit rights." }, "granted_by_policy_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Policy that authorized write-sharing, if applicable." }, "granted_by": { "type": [ "string", "null" ], "format": "uuid", "description": "User who granted the share." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the share was created." }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the share was revoked, if applicable." } } }, "ProveIndex_Entitlement": { "type": "object", "description": "Backbuild Prove subscription entitlement for an organization.", "required": [ "enabled", "tier", "status" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the organization has an active Backbuild Prove subscription." }, "tier": { "type": "string", "nullable": true, "enum": [ "pro", "team", "business", "enterprise", null ], "description": "Subscription tier, or `null` if not subscribed." }, "status": { "type": "string", "enum": [ "active", "trialing", "past_due", "cancelled", "none" ], "description": "Subscription lifecycle status." }, "subscription_id": { "type": "string", "description": "Billing subscription identifier (present when subscribed)." }, "pricing_plan_id": { "type": "string", "format": "uuid", "description": "Pricing plan identifier." }, "plan_slug": { "type": "string", "description": "URL slug of the active plan." }, "plan_name": { "type": "string", "description": "Human-readable plan name." }, "quantity": { "type": "integer", "description": "Seat count for per-seat plans." }, "is_per_seat": { "type": "boolean", "description": "Whether the plan charges per seat." }, "max_seats": { "type": "integer", "nullable": true, "description": "Maximum seats allowed, or `null` for unlimited." }, "trial_end": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 trial end date, or `null` when not in trial." }, "current_period_end": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 end of the current billing period." }, "included_languages": { "description": "Number of proof languages included in the plan.", "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "sql_addon": { "type": "boolean", "description": "Whether the SQL Verification add-on is active." }, "support_eligible": { "type": "boolean", "description": "Whether the subscription includes priority support." }, "extra_language_addon_eligible": { "type": "boolean", "description": "Whether the organization can purchase additional language add-ons." } } }, "ProveIndex_Lean4HealthResult": { "type": "object", "description": "Result of a Lean 4 verification service health probe.", "required": [ "status", "configured" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "ok", "error" ], "description": "`ok` if the Lean 4 service is reachable and healthy; `error` otherwise." }, "leanVersion": { "type": "string", "description": "Lean 4 version string reported by the service (present when `status` is `ok`)." }, "error": { "type": "string", "description": "Human-readable error description (present when `status` is `error`)." }, "configured": { "type": "boolean", "description": "Whether the Lean 4 verification service is configured in the platform. `false` means the service is not provisioned." } } }, "ProveIndex_Language": { "type": "object", "description": "A proof language activated for the organization.", "required": [ "language" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Language record identifier." }, "language": { "type": "string", "maxLength": 64, "description": "Proof language identifier (e.g. `lean4`, `coq`, `isabelle`, `agda`)." }, "activated": { "type": "boolean", "description": "Whether the language is currently active." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 activation timestamp." } } }, "ProveIndex_LanguageSetRequest": { "type": "object", "description": "Request to activate or deactivate a proof language.", "required": [ "language" ], "additionalProperties": false, "properties": { "language": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Proof language identifier." }, "mode": { "type": "string", "enum": [ "activate", "deactivate" ], "default": "activate", "description": "Whether to activate or deactivate the language. Defaults to `activate`." } } }, "ProveIndex_ProjectEnableResult": { "type": "object", "description": "Result of enabling Backbuild Prove for a project.", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Project identifier." }, "enabled": { "type": "boolean", "description": "Whether Prove is now enabled for the project." }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when Prove was first enabled." } } }, "ProveIndex_SourceTree": { "type": "object", "description": "Hierarchical tree of registered source files for a project.", "properties": { "project_id": { "type": "string", "format": "uuid" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_SourceFile" }, "description": "Flat list of registered source files." }, "total_files": { "type": "integer", "description": "Total number of registered source files." }, "total_theorems": { "type": "integer", "description": "Sum of theorem counts across all files." } } }, "ProveIndex_SourceFile": { "type": "object", "description": "A registered source file in the Prove catalog.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Source file record identifier." }, "project_id": { "type": "string", "format": "uuid" }, "file_path": { "type": "string", "description": "Relative path within the project." }, "sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hex digest of the file at registration time." }, "size_bytes": { "type": "integer", "minimum": 0, "description": "File size in bytes." }, "language": { "type": "string", "maxLength": 64, "description": "Proof language (e.g. `lean4`, `coq`)." }, "r2_key": { "type": "string", "description": "Storage key for retrieving the file content." }, "theorem_count": { "type": "integer", "minimum": 0 }, "proven_count": { "type": "integer", "minimum": 0 }, "failing_count": { "type": "integer", "minimum": 0 }, "partial_count": { "type": "integer", "minimum": 0 }, "symbols_function": { "type": "integer", "minimum": 0 }, "symbols_class": { "type": "integer", "minimum": 0 }, "symbols_struct": { "type": "integer", "minimum": 0 }, "symbols_enum": { "type": "integer", "minimum": 0 }, "symbols_type": { "type": "integer", "minimum": 0 }, "symbols_trait": { "type": "integer", "minimum": 0 }, "symbols_interface": { "type": "integer", "minimum": 0 }, "symbols_module": { "type": "integer", "minimum": 0 }, "symbols_annotated": { "type": "integer", "minimum": 0 }, "symbols_total": { "type": "integer", "minimum": 0 }, "warnings_count": { "type": "integer", "minimum": 0 }, "errors_count": { "type": "integer", "minimum": 0 }, "is_source": { "type": "boolean" }, "content": { "type": "string", "description": "File content text (only present when `include_content=true` was requested)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_SourceRegisterRequest": { "type": "object", "description": "Request to register or update a source file in the Prove catalog.", "required": [ "file_path", "sha256_hex", "size_bytes", "r2_key" ], "additionalProperties": false, "properties": { "file_path": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Relative path within the project." }, "sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hex digest (64 lowercase hex chars)." }, "size_bytes": { "type": "integer", "minimum": 0, "description": "File size in bytes." }, "language": { "type": "string", "maxLength": 64, "description": "Proof language (e.g. `lean4`, `coq`)." }, "r2_key": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Storage key for the file in the Prove source bucket." }, "theorem_count": { "type": "integer", "minimum": 0 }, "proven_count": { "type": "integer", "minimum": 0 }, "failing_count": { "type": "integer", "minimum": 0 }, "partial_count": { "type": "integer", "minimum": 0 }, "symbols_function": { "type": "integer", "minimum": 0 }, "symbols_class": { "type": "integer", "minimum": 0 }, "symbols_struct": { "type": "integer", "minimum": 0 }, "symbols_enum": { "type": "integer", "minimum": 0 }, "symbols_type": { "type": "integer", "minimum": 0 }, "symbols_trait": { "type": "integer", "minimum": 0 }, "symbols_interface": { "type": "integer", "minimum": 0 }, "symbols_module": { "type": "integer", "minimum": 0 }, "symbols_annotated": { "type": "integer", "minimum": 0 }, "symbols_total": { "type": "integer", "minimum": 0 }, "warnings_count": { "type": "integer", "minimum": 0 }, "errors_count": { "type": "integer", "minimum": 0 }, "is_source": { "type": "boolean" } } }, "ProveIndex_PairedDocumentSyncRequest": { "type": "object", "description": "Request to sync a paired-repository document manifest.", "required": [ "pairing_id", "files" ], "additionalProperties": false, "properties": { "pairing_id": { "type": "string", "format": "uuid", "description": "Identifier of the repository pairing configuration." }, "prune": { "type": "boolean", "description": "When `true`, removes catalog entries for files absent from the manifest." }, "files": { "type": "array", "maxItems": 5000, "description": "Document manifest entries. Maximum 5 000 items.", "items": { "type": "object", "required": [ "rel_path" ], "additionalProperties": false, "properties": { "rel_path": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Relative path within the repository." }, "size_bytes": { "type": "integer", "minimum": 0, "description": "File size in bytes." }, "sha256": { "type": "string", "pattern": "^(sha256:)?[0-9a-fA-F]{64}$", "description": "Optional SHA-256 digest (`sha256:` or bare 64-char hex)." }, "title": { "type": "string", "maxLength": 500, "description": "Optional document title." } } } } } }, "ProveIndex_PairedDocumentSyncResult": { "type": "object", "description": "Result of a paired-document manifest sync.", "properties": { "inserted": { "type": "integer", "description": "Number of new document entries added to the catalog." }, "updated": { "type": "integer", "description": "Number of existing document entries updated." }, "pruned": { "type": "integer", "description": "Number of entries removed (present when `prune: true` was requested)." } } }, "ProveIndex_Dashboard": { "type": "object", "description": "Aggregated proof coverage metrics for the project dashboard.", "properties": { "project_id": { "type": "string", "format": "uuid" }, "total_theorems": { "type": "integer" }, "proven_count": { "type": "integer" }, "failing_count": { "type": "integer" }, "partial_count": { "type": "integer" }, "coverage_pct": { "type": "number", "format": "float", "description": "Proof coverage percentage (0–100)." }, "last_run_at": { "type": "string", "format": "date-time", "nullable": true }, "last_run_status": { "type": "string", "enum": [ "passed", "failed", "partial", "running" ], "nullable": true } } }, "ProveIndex_Issue": { "type": "object", "description": "A proof issue (type error, failing theorem, or lint warning).", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "file_path": { "type": "string", "description": "Source file where the issue was detected." }, "language": { "type": "string" }, "domain": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string" }, "line": { "type": "integer", "nullable": true }, "column": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_Contract": { "type": "object", "description": "A formal proof contract (pre/post-condition, invariant) or third-party contract.", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "file_path": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Contract kind (e.g. `precondition`, `postcondition`, `invariant`)." }, "formal_term": { "type": "string" }, "verified": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_DependencyTree": { "type": "object", "description": "Directed dependency graph of theorems, lemmas, and axioms.", "properties": { "nodes": { "type": "array", "description": "Proof artifact nodes.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Artifact kind (`theorem`, `lemma`, `axiom`, `definition`)." }, "file_path": { "type": "string" } } } }, "edges": { "type": "array", "description": "Dependency edges between nodes.", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "uuid" }, "to": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "Edge kind (`requires`, `imports`)." } } } } } }, "ProveIndex_Certification": { "type": "object", "description": "A signed proof certification bundle.", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Bundle name." }, "version": { "type": "string", "description": "Bundle version string." }, "ed25519_pubkey_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Ed25519 public key hex used to produce this certification." }, "signature_hex": { "type": "string", "description": "Ed25519 signature hex over the certification payload." }, "r2_key": { "type": "string", "description": "Storage key for the bundle archive." }, "bundle_size_bytes": { "type": "integer", "minimum": 0 }, "bundle_sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "theorem_count": { "type": "integer", "minimum": 0 }, "lean4_verified": { "type": "boolean", "description": "Whether Lean 4 verification was performed on this bundle." }, "revoked": { "type": "boolean", "description": "Whether this certification has been revoked." }, "revocation_reason": { "type": "string", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_CertificationCreateRequest": { "type": "object", "description": "Request to publish a new proof certification.", "required": [ "name", "version", "ed25519_pubkey_hex", "signature_hex", "r2_key", "bundle_size_bytes", "bundle_sha256_hex", "theorem_count" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Bundle name." }, "version": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Bundle version string." }, "ed25519_pubkey_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Ed25519 public key hex (64 lowercase hex chars)." }, "signature_hex": { "type": "string", "pattern": "^[0-9a-f]+$", "description": "Ed25519 signature hex." }, "r2_key": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Storage key for the uploaded bundle." }, "r2_bucket": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Storage bucket name (optional; defaults to the configured Prove bundles bucket)." }, "bundle_size_bytes": { "type": "integer", "minimum": 0, "description": "Bundle size in bytes." }, "bundle_sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hex digest of the bundle." }, "file_hashes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Per-file SHA-256 hashes keyed by relative path.", "default": {} }, "binary_hashes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Per-binary SHA-256 hashes keyed by name.", "default": {} }, "theorem_count": { "type": "integer", "minimum": 0, "description": "Number of theorems in this bundle." }, "lean4_verified": { "type": "boolean", "default": false, "description": "Whether Lean 4 verification was performed." } } }, "ProveIndex_HandoffContractReport": { "type": "object", "description": "Structured handoff contract report for external audit or release gating.", "properties": { "project_id": { "type": "string", "format": "uuid" }, "generated_at": { "type": "string", "format": "date-time" }, "include_unaudited": { "type": "boolean" }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_Contract" } }, "total_proven": { "type": "integer" }, "total_audited": { "type": "integer" } } }, "ProveIndex_GovernanceTheorem": { "type": "object", "description": "A governance theorem from the platform catalog.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "language": { "type": "string" }, "compliance_frameworks": { "type": "array", "items": { "type": "string" }, "description": "Compliance frameworks this theorem maps to (e.g. `pci_dss`, `soc2`)." }, "formal_statement": { "type": "string" }, "severity": { "type": "string", "enum": [ "warning", "error" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_GovernanceAttachment": { "type": "object", "description": "A governance theorem attached to a project.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Attachment identifier." }, "project_id": { "type": "string", "format": "uuid" }, "governance_theorem_id": { "type": "string", "format": "uuid" }, "severity_override": { "type": "string", "nullable": true, "enum": [ "warning", "error", "ignored", null ], "description": "Per-attachment severity override; `null` means the catalog default applies." }, "theorem": { "$ref": "#/components/schemas/ProveIndex_GovernanceTheorem" }, "created_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_GovernanceAttachRequest": { "type": "object", "description": "Request to attach a governance theorem to a project.", "required": [ "governance_theorem_id" ], "additionalProperties": false, "properties": { "governance_theorem_id": { "type": "string", "format": "uuid", "description": "Governance theorem catalog identifier." }, "severity_override": { "type": "string", "enum": [ "warning", "error", "ignored" ], "description": "Override the default severity for violations from this theorem. Omit to use the catalog default." } } }, "ProveIndex_GovernanceViolation": { "type": "object", "description": "A governance violation instance.", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "attachment_id": { "type": "string", "format": "uuid" }, "file_path": { "type": "string", "nullable": true }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "warning", "error" ] }, "resolved": { "type": "boolean" }, "suppressed": { "type": "boolean" }, "suppression_reason": { "type": "string", "nullable": true }, "detected_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_SetProofClassRequest": { "type": "object", "description": "Request to bulk-update the proof class of theorems.", "required": [ "proof_class" ], "additionalProperties": false, "properties": { "proof_class": { "type": "string", "enum": [ "unaudited", "audited", "public_api" ], "description": "New proof class to assign." }, "theorem_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "UUIDs of theorems to update. Exactly one of `theorem_ids` or `theorem_names` must be supplied." }, "theorem_names": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "Names of theorems to update. Exactly one of `theorem_ids` or `theorem_names` must be supplied." } } }, "ProveIndex_SetProofClassResult": { "type": "object", "description": "Result of a proof class bulk update.", "properties": { "updated_count": { "type": "integer", "description": "Number of theorems updated." } } }, "ProveIndex_VerificationRun": { "type": "object", "description": "A record of a single kernel verification run.", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "passed", "failed", "partial", "running", "queued" ] }, "theorems_checked": { "type": "integer" }, "theorems_proven": { "type": "integer" }, "theorems_failing": { "type": "integer" }, "duration_ms": { "type": "integer", "nullable": true }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ProveIndex_ProjectSettings": { "type": "object", "description": "Prove-specific settings for a project.", "properties": { "project_id": { "type": "string", "format": "uuid" }, "settings": { "type": "object", "additionalProperties": true, "description": "Arbitrary key-value settings for the project's Prove configuration." }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_SigningKey": { "type": "object", "description": "An Ed25519 signing key for an organization. Private key material is never stored or returned.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "public_key_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Ed25519 public key (64 lowercase hex chars)." }, "label": { "type": "string", "nullable": true, "description": "Optional human-readable label." }, "status": { "type": "string", "enum": [ "active", "retired", "revoked" ], "description": "Key lifecycle status." }, "revocation_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "retired_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ProveIndex_SigningKeyCreateRequest": { "type": "object", "description": "Request to register a new Ed25519 signing key.", "required": [ "public_key_hex" ], "additionalProperties": false, "properties": { "public_key_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Ed25519 public key (64 lowercase hex chars). The corresponding private key is never transmitted to or stored by the platform." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Optional human-readable label for the key." } } }, "ProveIndex_SigningKeyRevokeRequest": { "type": "object", "description": "Request to revoke a signing key in response to a compromise.", "required": [ "revocation_reason" ], "additionalProperties": false, "properties": { "revocation_reason": { "type": "string", "minLength": 10, "maxLength": 2000, "description": "Description of the actual compromise event. Must be at least 10 characters." } } }, "ProveIndex_Lean4Report": { "type": "object", "description": "A Lean 4 verifier report entry.", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "file_path": { "type": "string", "nullable": true }, "kind": { "type": "string", "description": "Report kind (e.g. `error`, `warning`, `info`)." }, "message": { "type": "string" }, "line": { "type": "integer", "nullable": true }, "column": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_CoverageTimeSeries": { "type": "object", "description": "Time-series data for a proof coverage or run-frequency report.", "properties": { "project_id": { "type": "string", "format": "uuid" }, "days": { "type": "integer", "description": "Lookback window used." }, "data_points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "ISO 8601 date (YYYY-MM-DD)." }, "value": { "type": "number", "description": "Metric value for this date (coverage % or run count)." } } } } } }, "ProveIndex_DomainBreakdownItem": { "type": "object", "description": "Per-domain proof coverage breakdown entry.", "properties": { "domain": { "type": "string", "description": "Proof domain name." }, "total": { "type": "integer" }, "proven": { "type": "integer" }, "coverage_pct": { "type": "number", "format": "float" } } }, "ProveIndex_LanguageBreakdownItem": { "type": "object", "description": "Per-language proof coverage breakdown entry.", "properties": { "language": { "type": "string", "description": "Proof language identifier." }, "total": { "type": "integer" }, "proven": { "type": "integer" }, "coverage_pct": { "type": "number", "format": "float" } } }, "ProveIndex_ComplianceDashboard": { "type": "object", "description": "Project compliance posture summary across attached governance frameworks.", "properties": { "project_id": { "type": "string", "format": "uuid" }, "overall_score": { "type": "number", "format": "float", "description": "Overall compliance score (0–100)." }, "frameworks": { "type": "array", "items": { "type": "object", "properties": { "framework": { "type": "string" }, "score": { "type": "number", "format": "float" }, "controls_passing": { "type": "integer" }, "controls_failing": { "type": "integer" } } } }, "top_violations": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_GovernanceViolation" } } } }, "ProveIndex_SearchRequest": { "type": "object", "description": "Request to search theorems.", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 500, "description": "Search query (2–500 chars)." }, "scope": { "type": "string", "enum": [ "all", "project", "system", "governance" ], "default": "all", "description": "`all` searches across all accessible theorems. `project` requires `project_id`. `system` searches platform-provided theorems. `governance` searches the governance catalog." }, "project_id": { "type": "string", "format": "uuid", "description": "Required when `scope` is `project`." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Maximum results to return." }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Results to skip for pagination." } } }, "ProveIndex_SearchResult": { "type": "object", "description": "A single theorem search result.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Artifact kind (`theorem`, `lemma`, `axiom`, `definition`)." }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "language": { "type": "string" }, "score": { "type": "number", "description": "Relevance score." }, "snippet": { "type": "string", "description": "Text snippet from the matched content." } } }, "ProveIndex_ProofPrintout": { "type": "object", "description": "Canonical proof printout for attestation.", "properties": { "project_id": { "type": "string", "format": "uuid" }, "filter": { "type": "string", "enum": [ "all", "verified", "audited" ] }, "generated_at": { "type": "string", "format": "date-time" }, "theorems": { "type": "array", "description": "Theorems in the printout.", "items": { "type": "object", "additionalProperties": true } }, "content_sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hex digest of the canonical printout payload, used as the input to attestation signing." } } }, "ProveIndex_ProofPrintoutSignature": { "type": "object", "description": "An Ed25519 attestation signature over a proof printout.", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "content_sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "ed25519_pubkey_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "signature_hex": { "type": "string", "pattern": "^[0-9a-f]{128}$" }, "filter": { "type": "string", "enum": [ "all", "verified", "audited" ] }, "label": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_ProofPrintoutSignRequest": { "type": "object", "description": "Request to store an Ed25519 attestation signature over a proof printout.", "required": [ "content_sha256_hex", "ed25519_pubkey_hex", "signature_hex" ], "additionalProperties": false, "properties": { "content_sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hex digest of the printout payload that was signed." }, "ed25519_pubkey_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Ed25519 public key (64 lowercase hex chars). Must match the organization's registered active signing key." }, "signature_hex": { "type": "string", "pattern": "^[0-9a-f]{128}$", "description": "Ed25519 signature over the printout payload (128 lowercase hex chars = 64 bytes)." }, "filter": { "type": "string", "enum": [ "all", "verified", "audited" ], "default": "all", "description": "Proof class filter used when generating the printout." }, "label": { "type": "string", "maxLength": 120, "description": "Optional human-readable label for this signature." } } }, "ProveIndex_NotificationSettings": { "type": "object", "description": "Notification channel configuration and event filters for a project.", "properties": { "project_id": { "type": "string", "format": "uuid" }, "channels": { "type": "object", "properties": { "in_app": { "type": "boolean" }, "email": { "type": "boolean" }, "webhook": { "type": "boolean" } } }, "event_filters": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Per-event-type enable/disable flags." }, "recipient_user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "min_severity": { "type": "string", "enum": [ "info", "warning", "error" ] }, "cooldown_minutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_NotificationSettingsUpdateRequest": { "type": "object", "description": "Request to update notification settings for a project.", "additionalProperties": false, "properties": { "channels": { "type": "object", "additionalProperties": false, "properties": { "in_app": { "type": "boolean" }, "email": { "type": "boolean" }, "webhook": { "type": "boolean" } } }, "event_filters": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Per-event-type overrides." }, "recipient_user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "min_severity": { "type": "string", "enum": [ "info", "warning", "error" ] }, "cooldown_minutes": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Minimum gap in minutes between repeated notifications for the same event type." } } }, "ProveIndex_Webhook": { "type": "object", "description": "A Prove outbound webhook registration. The signing secret is never returned.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Project scope (null = org-level)." }, "url": { "type": "string", "format": "uri", "description": "HTTPS delivery URL." }, "event_types": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Subscribed event types, or null for all events." }, "created_at": { "type": "string", "format": "date-time" } } }, "ProveIndex_WebhookCreateRequest": { "type": "object", "description": "Request to register a new Prove webhook.", "required": [ "url", "secret" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS delivery endpoint URL. Must start with `https://`." }, "secret": { "type": "string", "minLength": 16, "maxLength": 256, "description": "Signing secret used to compute the delivery HMAC signature. Store this immediately — it is not returned after creation." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Event types to subscribe to. Omit to receive all Prove events." }, "project_id": { "type": "string", "format": "uuid", "description": "Scope to a specific project. Omit for org-level delivery." } } }, "ProveIndex_WebhookRotateRequest": { "type": "object", "description": "Request to rotate a webhook signing secret.", "additionalProperties": false, "properties": { "secret": { "type": "string", "minLength": 16, "maxLength": 256, "description": "New secret. When omitted, the server generates a fresh 64-character base64url secret." }, "grace_days": { "type": "integer", "minimum": 1, "maximum": 30, "description": "Grace overlap window in days during which the old secret continues to verify deliveries (default 7)." } } }, "ProveIndex_DischargedByEntry": { "type": "object", "description": "A `\\dischargedby` declaration referencing either an existing label or a forward reference.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "label", "forward_reference" ], "description": "`label` for an existing proof artifact; `forward_reference` for an artifact not yet registered." }, "label": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Proof artifact label. Required when `kind` is `label`." }, "forward_kind": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Kind of the forward-referenced artifact. Required when `kind` is `forward_reference`." }, "forward_name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Name of the forward-referenced artifact. Required when `kind` is `forward_reference`." }, "where_conditions": { "type": "string", "maxLength": 8192, "description": "Optional additional formal conditions constraining the forward reference." } } }, "ProveIndex_HypothesisObligation": { "type": "object", "description": "A discharge obligation attached to a hypothesis.", "required": [ "label", "prose", "formal_condition" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 500 }, "prose": { "type": "string", "maxLength": 65536, "description": "Human-readable description of the obligation." }, "formal_condition": { "type": "string", "maxLength": 65536, "description": "Formal logical condition that must be satisfied." } } }, "ProveIndex_HypothesisRegisterRequest": { "type": "object", "description": "Request to register a hypothesis with its obligations and links.", "required": [ "label", "name", "constant_name", "formal_term", "source_file_path" ], "additionalProperties": false, "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Unique label for this hypothesis within the project." }, "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Human-readable name." }, "constant_name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Formal constant name in the proof language." }, "formal_term": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "Formal logical term being hypothesized." }, "prose": { "type": "string", "maxLength": 65536, "description": "Human-readable description of the hypothesis." }, "source_file_path": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Source file path (canonicalized server-side; traversal sequences are rejected)." }, "obligations": { "type": "array", "maxItems": 1024, "items": { "$ref": "#/components/schemas/ProveIndex_HypothesisObligation" } }, "implied_from": { "type": "array", "maxItems": 1024, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Labels of other hypotheses that imply this one." }, "dischargedby": { "type": "array", "maxItems": 1024, "items": { "$ref": "#/components/schemas/ProveIndex_DischargedByEntry" }, "description": "`\\dischargedby` declarations." } } }, "ProveIndex_HypothesisRegisterResult": { "type": "object", "description": "Result of registering a hypothesis.", "properties": { "hypothesis_id": { "type": "string", "format": "uuid" }, "obligations_inserted": { "type": "integer" }, "implied_from_inserted": { "type": "integer" }, "dischargedby_inserted": { "type": "integer" } } }, "ProveIndex_TheoremWithDischargedByRequest": { "type": "object", "description": "Request to record `\\dischargedby` declarations on a theorem.", "required": [ "theorem_id", "conclusion_term", "dischargedby" ], "additionalProperties": false, "properties": { "theorem_id": { "type": "string", "format": "uuid", "description": "Identifier of the theorem being registered." }, "conclusion_term": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "The theorem's conclusion formal term." }, "dischargedby": { "type": "array", "maxItems": 1024, "items": { "$ref": "#/components/schemas/ProveIndex_DischargedByEntry" }, "description": "`\\dischargedby` declarations for this theorem." } } }, "ProveIndex_TheoremWithDischargedByResult": { "type": "object", "description": "Result of recording `\\dischargedby` declarations on a theorem.", "properties": { "obligations_auto_discharged": { "type": "array", "items": { "type": "string" }, "description": "Obligation labels that were automatically discharged by this theorem." }, "obligations_explicit_discharged": { "type": "array", "items": { "type": "string" }, "description": "Obligation labels that were explicitly discharged via the `dischargedby` declarations." } } }, "ProveIndex_CheckPromotionsResult": { "type": "object", "description": "Result of running the hypothesis-to-theorem promotion engine.", "properties": { "promoted_hypothesis_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of hypotheses promoted to theorems in this run." }, "promotion_count": { "type": "integer", "description": "Total number of hypotheses promoted." } } }, "ProveIndex_HypothesisStatusGraph": { "type": "object", "description": "Full hypothesis/obligation/implication/promotion graph for a project.", "properties": { "project_id": { "type": "string", "format": "uuid" }, "hypotheses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "discharged", "promoted" ] }, "obligations": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_HypothesisObligation" } }, "implied_from": { "type": "array", "items": { "type": "string" } }, "dischargedby": { "type": "array", "items": { "$ref": "#/components/schemas/ProveIndex_DischargedByEntry" } } } } } } }, "ProveProjects_UpstreamRef": { "type": "object", "description": "Reference to an upstream (dependency) theorem. The `scope` field uses the wire string form (`\"system\"` or `\"sameProject\"`); the API layer maps it to the §3.4 hash discriminant byte before forwarding to the project-serializer Durable Object. The upstream `node_hash` is NOT supplied by the caller — it is resolved and frozen by the DO at admission time.", "required": [ "name", "scope" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[a-zA-Z0-9/_:.\\-]+$", "description": "Name of the upstream theorem. Must match the §3.1 byte set (`a-zA-Z0-9/_:.-`), be at most 256 UTF-8 bytes, and must not contain `.` or `..` path segments." }, "scope": { "type": "string", "enum": [ "system", "sameProject" ], "description": "`system` — the upstream is in the platform-wide system theorem registry. `sameProject` — the upstream is in the same project DAG." } } }, "ProveProjects_ProofClass": { "type": "string", "enum": [ "unaudited", "pending", "genuine", "cross_validated", "invalid", "unproven", "promoted" ], "description": "Canonical proof-class label. The allowed set is unified across the API schema, the `api.prove_project_theorem_upsert` stored-procedure allowlist, and the `chk_prove_project_theorems_proof_class` database CHECK constraint." }, "ProveProjects_RegisterNodeRequest": { "type": "object", "description": "Body for `POST /v1/prove/projects/{projectId}/dag/register`. Mirrors `bbprove-serializer::NodeRequest` (§3.1 of the DAG state-cache spec). Fields the Durable Object injects at admission time (`org_id`, `project_id`, `node_hash`, `body_hash`, `admitted_at`, `admitted_by`, `admitted_org_id`) are never accepted from the client. Unknown top-level keys are rejected with `VALIDATION_ERROR` (strict schema).", "required": [ "name", "latex", "domain" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[a-zA-Z0-9/_:.\\-]+$", "description": "Theorem name. Must match the §3.1 byte set (`a-zA-Z0-9/_:.-`), be at most 256 UTF-8 bytes, and must not contain `.` or `..` path segments." }, "latex": { "type": "string", "minLength": 1, "maxLength": 10485760, "description": "LaTeX source for the theorem (1 byte – 10 MiB)." }, "domain": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Domain identifier (1–100 characters)." }, "category": { "type": "string", "maxLength": 100, "description": "Optional category label (≤ 100 characters)." }, "statement": { "type": "string", "maxLength": 100000, "description": "Optional plain-text statement of the theorem (≤ 100 000 characters)." }, "depOrder": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Optional dependency-order hint (0–100 000). Used by the kernel for topological ordering." }, "upstream": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/ProveProjects_UpstreamRef" }, "description": "Upstream dependency references (≤ 10 000 items). The DO canonicalises ordering before §3.4 BLAKE3 hashing; clients may submit in any order." }, "lean4Equiv": { "type": "string", "maxLength": 500, "description": "Optional Lean 4 equivalence reference identifier (≤ 500 characters)." }, "notes": { "type": "string", "maxLength": 10000, "description": "Optional free-form notes (≤ 10 000 characters)." }, "proofClass": { "$ref": "#/components/schemas/ProveProjects_ProofClass" }, "conclusionTerm": { "type": "string", "maxLength": 1048576, "description": "Optional Rust-aligned hash-input field for the conclusion term (≤ 1 MiB). Used by `lib.rs` for `body_hash` computation. Required once the bbprove CLI is updated to forward it." }, "ledgerSteps": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "Optional proof ledger step count (0–2³²−1)." }, "rulesUsed": { "type": "array", "maxItems": 8192, "items": { "type": "string", "maxLength": 256 }, "description": "Optional list of rule identifiers used in the proof (≤ 8 192 entries, each ≤ 256 characters)." }, "lean4Typechecks": { "type": "boolean", "description": "Whether the Lean 4 equivalence (`lean4Equiv`) successfully typechecks." } } }, "ProveProjects_DagNode": { "type": "object", "description": "A single admitted DAG node as returned by the project-serializer Durable Object. All hash and audit fields are DO-injected and immutable post-admission.", "required": [ "name", "domain", "orgId", "projectId", "nodeHash", "bodyHash", "admittedAt", "admittedBy", "proofClass" ], "properties": { "name": { "type": "string", "description": "Theorem name (§3.1 byte set)." }, "domain": { "type": "string", "description": "Domain identifier." }, "category": { "type": [ "string", "null" ], "description": "Category label; null when not set." }, "statement": { "type": [ "string", "null" ], "description": "Plain-text theorem statement; null when not set." }, "orgId": { "type": "string", "format": "uuid", "description": "Owning organization identifier (UUIDv7), injected by the DO." }, "projectId": { "type": "string", "format": "uuid", "description": "Owning project identifier (UUIDv7), injected by the DO." }, "nodeHash": { "type": "string", "description": "BLAKE3-derived node hash (hex), produced by the DO per §3.4." }, "bodyHash": { "type": "string", "description": "BLAKE3-derived body hash (hex), produced by the DO per §3.4." }, "admittedAt": { "type": "string", "format": "date-time", "description": "Timestamp at which the DO admitted this node." }, "admittedBy": { "type": "string", "format": "uuid", "description": "User ID of the caller who admitted the node (from the JWT, injected by the DO)." }, "admittedOrgId": { "type": "string", "format": "uuid", "description": "Organization of the admitting user (from the JWT, injected by the DO)." }, "depOrder": { "type": [ "integer", "null" ], "description": "Dependency-order hint; null when not supplied." }, "upstream": { "type": "array", "items": { "$ref": "#/components/schemas/ProveProjects_UpstreamRef" }, "description": "Upstream dependency references (canonical order per §3.4 sort criterion)." }, "lean4Equiv": { "type": [ "string", "null" ], "description": "Lean 4 equivalence reference; null when not set." }, "notes": { "type": [ "string", "null" ], "description": "Free-form notes; null when not set." }, "proofClass": { "$ref": "#/components/schemas/ProveProjects_ProofClass" } } }, "ProveProjects_RegisterNodeResponse": { "type": "object", "description": "Response payload for `POST /v1/prove/projects/{projectId}/dag/register`.", "required": [ "node" ], "properties": { "node": { "$ref": "#/components/schemas/ProveProjects_DagNode", "description": "The admitted DAG node as stored by the project-serializer Durable Object." } } }, "ProveProjects_DagManifest": { "type": "object", "description": "Project DAG manifest returned by `GET /v1/prove/projects/{projectId}/dag/manifest`.", "required": [ "headHash", "nodeCount" ], "properties": { "headHash": { "type": [ "string", "null" ], "description": "Current DAG head hash. `null` when the DAG is empty (no nodes admitted yet)." }, "nodeCount": { "type": "integer", "minimum": 0, "description": "Total number of nodes admitted to the project DAG." }, "lastFlushAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent durable-storage flush. `null` if no flush has occurred yet." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/ProveProjects_DagNode" }, "description": "When `since` is omitted the full node list is returned; when `since` is supplied only nodes admitted after that head hash are included." } } }, "ProveProjects_SyncResponse": { "type": "object", "description": "Response payload for `POST /v1/prove/projects/{projectId}/dag/sync`.", "required": [ "flushed" ], "properties": { "flushed": { "type": "boolean", "description": "`true` when a flush was performed; `false` when the state was already clean and no flush was needed." }, "headHash": { "type": [ "string", "null" ], "description": "DAG head hash after the flush. `null` when the DAG is empty." }, "flushedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the flush. `null` when `flushed` is `false`." } } }, "ProveProjects_DeverifyAllRequest": { "type": "object", "description": "Optional body for `POST /v1/prove/projects/{projectId}/dag/deverify-all`. An absent `Content-Type` or empty body is treated as `{}`. Unknown keys are rejected (strict schema).", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 2000, "description": "Optional free-text reason for the deverification. Appended to the audit row in the stored procedure (≤ 2 000 characters)." } } }, "ProveProjects_DeverifyAllResponse": { "type": "object", "description": "Response payload for `POST /v1/prove/projects/{projectId}/dag/deverify-all`.", "required": [ "affected" ], "properties": { "affected": { "type": "integer", "minimum": 0, "description": "Number of theorem nodes reset to provisional status." }, "reason": { "type": [ "string", "null" ], "description": "The `reason` value that was recorded in the audit row; `null` when no reason was supplied." } } }, "ProveProjects_ProveSimpleError": { "type": "object", "description": "Non-standard error envelope emitted by the `/prove/*` endpoints (outside the main v1 router). These endpoints were registered before the canonical `ErrorEnvelope` pattern was adopted; the shape carries `success: false` and a plain string `error` field rather than a structured `error.code`/`error.message` pair.", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "Human-readable error description." }, "message": { "type": "string", "description": "Optional supplementary message." } } }, "ProveProjects_HealthResponse": { "type": "object", "description": "Response for `GET /prove/health`.", "required": [ "success", "status", "service", "timestamp" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "status": { "type": "string", "enum": [ "healthy" ], "description": "Always `healthy` when the Worker is running." }, "service": { "type": "string", "enum": [ "bbprove" ], "description": "Service name." }, "timestamp": { "type": "string", "format": "date-time", "description": "Server-side ISO 8601 timestamp." } } }, "ProveProjects_InfoResponse": { "type": "object", "description": "Response for `GET /prove/info`. Static capability metadata.", "required": [ "success", "service" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "service": { "type": "object", "description": "Service capability descriptor.", "properties": { "name": { "type": "string", "description": "Service display name." }, "version": { "type": "string", "description": "Service version string." }, "description": { "type": "string", "description": "One-sentence service description." }, "endpoints": { "type": "object", "description": "Map of logical name → canonical path for this service.", "additionalProperties": { "type": "string" } }, "protocols": { "type": "object", "description": "Protocol metadata.", "properties": { "websocket": { "type": "object", "properties": { "version": { "type": "string" }, "subprotocols": { "type": "array", "items": { "type": "string" } } } }, "compression": { "type": "array", "items": { "type": "string" } }, "authentication": { "type": "string" } } }, "features": { "type": "array", "items": { "type": "string" }, "description": "Human-readable list of supported features." }, "kernel": { "type": "object", "description": "Kernel capability summary.", "properties": { "primitiveRules": { "type": "integer", "description": "Number of LCF-style primitive inference rules." }, "axioms": { "type": "integer", "description": "Number of base axioms." }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "description": "Programming languages for which proof annotations are supported." } } }, "limits": { "type": "object", "description": "Connection and message limits.", "properties": { "maxMessageSize": { "type": "integer", "description": "Maximum WebSocket message size in bytes." }, "heartbeatInterval": { "type": "integer", "description": "Heartbeat interval in milliseconds." }, "connectionTimeout": { "type": "integer", "description": "Connection timeout in milliseconds." } } } } } } }, "ProveProjects_InternalGenericResult": { "type": "object", "description": "Generic result envelope returned by internal service-to-service endpoints. The `data` payload is endpoint-specific and not part of the public consumer contract.", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "`true` on success." }, "data": { "description": "Endpoint-specific result payload (implementation-defined)." } } }, "ProveProjects_InternalProjectRef": { "type": "object", "description": "Project reference body for internal project load/unload endpoints.", "properties": { "orgId": { "type": "string", "format": "uuid", "description": "Organization identifier (UUIDv7). Required for `/project/load`; optional for `/project/unload`." }, "projectId": { "type": "string", "format": "uuid", "description": "Project identifier (UUIDv7). Required for `/project/load`; optional for `/project/unload`." } }, "additionalProperties": true }, "ProveProjects_InternalProveRequest": { "type": "object", "description": "Request body for `POST /internal/prove/prove`. Fields mirror `ProveProofRequest` from the kernel service type definitions.", "required": [ "orgId", "projectId", "name", "latex" ], "properties": { "orgId": { "type": "string", "format": "uuid", "description": "Organization identifier (UUIDv7)." }, "projectId": { "type": "string", "format": "uuid", "description": "Project identifier (UUIDv7)." }, "name": { "type": "string", "description": "Theorem name (§3.1 byte set)." }, "latex": { "type": "string", "description": "LaTeX source to prove." } }, "additionalProperties": true }, "ProveProjects_InternalExtractRequest": { "type": "object", "description": "Request body for `POST /internal/prove/extract`. Fields mirror `ProveExtractRequest` from the kernel service type definitions.", "required": [ "source", "filePath" ], "properties": { "source": { "type": "string", "description": "Source file content to parse for proof annotations." }, "filePath": { "type": "string", "description": "Logical file path — used for annotation scope and error reporting." } }, "additionalProperties": true }, "ProveProjects_InternalCacheCheckRequest": { "type": "object", "description": "Request body for `POST /internal/prove/cache-check`.", "required": [ "orgId", "projectId", "annotations" ], "properties": { "orgId": { "type": "string", "format": "uuid", "description": "Organization identifier (UUIDv7)." }, "projectId": { "type": "string", "format": "uuid", "description": "Project identifier (UUIDv7)." }, "annotations": { "type": "array", "description": "Batch of annotation hashes to check against the cache.", "items": { "type": "object", "required": [ "name", "annotationHash" ], "properties": { "name": { "type": "string", "description": "Theorem name." }, "annotationHash": { "type": "string", "description": "Hash of the annotation content to check." } } } } } }, "ProveProjects_InternalLean4CrosscheckRequest": { "type": "object", "description": "Request body for `POST /internal/prove/lean4-crosscheck`.", "required": [ "lean4Source" ], "properties": { "lean4Source": { "type": "string", "description": "Lean 4 source fragment to send to the verification service." } }, "additionalProperties": true }, "ProveProjects_InternalStateResponse": { "type": "object", "description": "Response for `GET /internal/prove/state`.", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "Kernel state metadata.", "properties": { "kernelVersion": { "type": "string", "description": "Running kernel version string." }, "wasmState": { "type": "object", "additionalProperties": true, "description": "WASM module version and state (implementation-defined)." } } } } }, "ProveProjects_InternalSettingsResponse": { "type": "object", "description": "Response for `GET /internal/prove/settings` and `PUT /internal/prove/settings`.", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "Settings payload.", "properties": { "settings": { "type": "object", "additionalProperties": true, "description": "Per-project kernel settings (warning/error severity modes, verification flags — implementation-defined)." } } } } }, "ProveProjects_InternalUpdateSettingsRequest": { "type": "object", "description": "Request body for `PUT /internal/prove/settings`.", "required": [ "orgId", "projectId", "settings" ], "properties": { "orgId": { "type": "string", "format": "uuid", "description": "Organization identifier (UUIDv7)." }, "projectId": { "type": "string", "format": "uuid", "description": "Project identifier (UUIDv7)." }, "settings": { "type": "object", "additionalProperties": true, "description": "Replacement settings object for the project kernel configuration." } } }, "ProveSystem_RegisterRequest": { "type": "object", "additionalProperties": false, "description": "Request body for registering a system theorem through the gated cross-validation pipeline.", "required": [ "name", "latex", "domain" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Unique name for the system theorem (e.g. `modus_ponens`, `cantor_diagonal`). Must be unique within the system theorem catalog." }, "latex": { "type": "string", "minLength": 1, "maxLength": 10485760, "description": "Full LaTeX proof source. Maximum 10 MB. Submitted to the WASM kernel for machine verification." }, "domain": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Logical domain for the theorem (e.g. `logic`, `algebra`, `analysis`, `topology`)." }, "category": { "type": "string", "maxLength": 100, "description": "Optional sub-category within the domain." }, "statement": { "type": "string", "maxLength": 10000, "description": "Optional human-readable statement of the theorem. When omitted, the kernel-derived conclusion is used." }, "depOrder": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Optional dependency order for keyset pagination and dependency-chain resolution. Lower values are loaded first during kernel bootstrap." }, "lean4Equiv": { "type": "string", "maxLength": 500, "description": "Optional reference to an equivalent Lean 4 declaration name in Mathlib or another trusted library." }, "notes": { "type": "string", "maxLength": 10000, "description": "Optional human-readable notes about the theorem." }, "aiGradingNotes": { "type": "string", "maxLength": 10000, "description": "Optional AI-assisted grading and audit notes, recorded alongside the theorem for auditor review." } } }, "ProveSystem_RegisterSyncResult": { "type": "object", "description": "Synchronous registration result returned at HTTP 200 (already_defined path) or as the terminal result of a polled job.", "properties": { "success": { "type": "boolean", "description": "Whether the theorem was admitted into the catalog." }, "name": { "type": "string", "description": "Theorem name." }, "conclusion": { "type": "string", "description": "Kernel-derived conclusion string." }, "steps": { "type": "integer", "description": "Number of proof-ledger steps the kernel recorded." }, "rules": { "type": "array", "items": { "type": "string" }, "description": "Inference rules used in the proof." }, "pgSyncWarning": { "type": [ "string", "null" ], "description": "Non-null when the metadata write to the persistent store encountered a transient error. The theorem IS proven in the kernel but the catalog record may be temporarily stale." } } }, "ProveSystem_KernelStateResult": { "type": "object", "description": "Exported WASM kernel state.", "required": [ "success", "kernelVersion", "blobBase64", "blobSize", "source" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "kernelVersion": { "type": "string", "description": "Semantic version string of the WASM kernel that produced this state blob (e.g. `v0.1.0`)." }, "blobBase64": { "type": "string", "description": "Base64-encoded WASM kernel state blob. Load this into a local kernel instance to pre-populate system theorems from previous sessions." }, "blobSize": { "type": "integer", "description": "Byte-length of the base64 string." }, "source": { "type": "string", "enum": [ "kv", "do" ], "description": "`kv` — served from the edge cache (fast path); `do` — served directly from the proof controller service (cold cache fallback)." } } }, "ProveSystem_ImportRequest": { "type": "object", "additionalProperties": false, "description": "Request body for a metadata-only system theorem import (no kernel or Lean 4 pipeline execution).", "required": [ "name", "domain" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Unique theorem name." }, "domain": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Logical domain." }, "category": { "type": "string", "maxLength": 100, "description": "Optional sub-category." }, "statement": { "type": "string", "maxLength": 100000, "description": "Optional human-readable statement." }, "proofLatex": { "type": "string", "maxLength": 10485760, "description": "Optional LaTeX proof source. Not executed — stored for reference." }, "conclusion": { "type": "string", "maxLength": 100000, "description": "Optional kernel-derived or manually-supplied conclusion string." }, "depOrder": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Optional dependency order." }, "proofClass": { "type": "string", "enum": [ "unaudited", "invalid", "pending", "genuine", "cross_validated", "unproven" ], "description": "Classification of the proof record. Defaults to `unaudited`." }, "kernelVerified": { "type": "boolean", "description": "Whether this theorem has been machine-verified by the WASM kernel. Defaults to `false` for metadata-only imports." }, "ledgerSteps": { "type": "integer", "minimum": 0, "description": "Number of proof-ledger steps (from an external source), if known." }, "rulesUsed": { "type": "array", "items": { "type": "string" }, "description": "Inference rules used (from an external source), if known." }, "lean4Exported": { "type": "boolean", "description": "Whether a Lean 4 export was produced for this theorem." }, "lean4Typechecks": { "type": "boolean", "description": "Whether the Lean 4 export type-checks without errors." }, "lean4Errors": { "type": "integer", "minimum": 0, "description": "Number of Lean 4 type errors, if a type-check was attempted." }, "auditNotes": { "type": "string", "maxLength": 10000, "description": "Optional audit notes." } } }, "ProveSystem_ImportResult": { "type": "object", "description": "Result of a metadata-only theorem import.", "required": [ "theoremId", "name" ], "properties": { "theoremId": { "type": "string", "format": "uuid", "description": "Platform-assigned identifier for the newly imported theorem record." }, "name": { "type": "string", "description": "The theorem name as stored." } } }, "ProveSystem_TheoremRecord": { "type": "object", "description": "A system theorem record from the catalog.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Platform-assigned theorem identifier." }, "name": { "type": "string", "description": "Unique theorem name." }, "domain": { "type": "string", "description": "Logical domain." }, "category": { "type": [ "string", "null" ], "description": "Sub-category, or null." }, "statement": { "type": [ "string", "null" ], "description": "Human-readable statement." }, "conclusion": { "type": [ "string", "null" ], "description": "Kernel-derived conclusion." }, "proof_latex": { "type": [ "string", "null" ], "description": "LaTeX proof source. Only included when `include_latex=true` was set on the listing endpoint or when fetching a single theorem." }, "dep_order": { "type": [ "integer", "null" ], "description": "Dependency order." }, "proof_class": { "type": "string", "enum": [ "unaudited", "invalid", "pending", "genuine", "cross_validated", "unproven" ], "description": "Current proof classification." }, "kernel_verified": { "type": "boolean", "description": "Whether the WASM kernel has verified this theorem." }, "ledger_steps": { "type": [ "integer", "null" ], "description": "Proof-ledger step count." }, "rules_used": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Inference rules used." }, "lean4_exported": { "type": [ "boolean", "null" ], "description": "Whether a Lean 4 export was produced." }, "lean4_typechecks": { "type": [ "boolean", "null" ], "description": "Whether the Lean 4 export type-checks." }, "lean4_errors": { "type": [ "integer", "null" ], "description": "Number of Lean 4 type errors." }, "audit_notes": { "type": [ "string", "null" ], "description": "Audit notes." }, "created_at": { "type": "string", "format": "date-time", "description": "Record creation timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Record last-update timestamp." } } }, "ProveSystem_TheoremListResult": { "type": "object", "description": "Paginated list of system theorems with keyset cursor for the next page.", "required": [ "theorems", "has_more", "total" ], "properties": { "theorems": { "type": "array", "items": { "$ref": "#/components/schemas/ProveSystem_TheoremRecord" }, "description": "Theorem records for this page." }, "next_cursor": { "type": [ "object", "null" ], "description": "Keyset cursor for the next page. Null when there are no more records. Pass `cursor_dep_order` and `cursor_name` from this object to retrieve the next page.", "properties": { "dep_order": { "type": "integer", "description": "Dependency-order value of the last item on this page." }, "name": { "type": "string", "description": "Name of the last item on this page." } } }, "has_more": { "type": "boolean", "description": "Whether additional pages exist beyond this one." }, "total": { "type": "integer", "description": "Total number of theorems matching the filter (before pagination)." } } }, "ProveSystem_DeverifyRequest": { "type": "object", "additionalProperties": false, "description": "Optional body for de-verifying a single system theorem.", "properties": { "reason": { "type": "string", "maxLength": 1000, "description": "Optional human-readable reason for the de-verification (e.g. `kernel audit`, `proof error discovered`). Recorded in the audit log." } } }, "ProveSystem_WipeSummary": { "type": "object", "description": "Per-layer outcome of the WASM kernel state cache wipe triggered by a de-verify operation.", "properties": { "r2_blob_deleted": { "type": "boolean", "description": "Whether the persistent object-store cache blob was deleted." }, "kv_blob_deleted": { "type": "boolean", "description": "Whether the edge KV blob was deleted." }, "do_reset": { "type": "boolean", "description": "Whether the proof controller service's in-memory bootstrap flag was reset." } } }, "ProveSystem_DeverifyResult": { "type": "object", "description": "Result of de-verifying a single system theorem.", "required": [ "id", "name", "wipe" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Theorem identifier." }, "name": { "type": "string", "description": "Theorem name." }, "wipe": { "$ref": "#/components/schemas/ProveSystem_WipeSummary" } } }, "ProveSystem_DeverifyAllRequest": { "type": "object", "additionalProperties": false, "description": "Optional body for the bulk de-verify operation.", "properties": { "domain": { "type": "string", "maxLength": 100, "description": "When provided, restrict the de-verify to theorems in this domain. When omitted, ALL system theorems are reverted." }, "reason": { "type": "string", "maxLength": 1000, "description": "Optional human-readable reason recorded in the audit log." } } }, "ProveSystem_DeverifyAllResult": { "type": "object", "description": "Result of the bulk de-verify operation.", "required": [ "deverified_count", "kernel_state_cache_wiped", "wipe" ], "properties": { "deverified_count": { "type": "integer", "description": "Number of theorem records reverted to provisional status." }, "kernel_state_cache_wiped": { "type": "integer", "description": "Number of kernel-state cache rows cleared in the persistent store." }, "wipe": { "$ref": "#/components/schemas/ProveSystem_WipeSummary" } } }, "ProveSystem_Lean4ResultCallback": { "type": "object", "additionalProperties": true, "description": "Internal signed service-to-service call — not part of the public consumer API. Body forwarded verbatim to the proof controller service. At minimum, a `job_id` field must be present.", "required": [ "job_id" ], "properties": { "job_id": { "type": "string", "description": "Identifier of the registration job this result applies to." } } }, "ProveSystem_PublicBundleRecord": { "type": "object", "description": "Public-facing proof certificate bundle record.", "required": [ "id", "name", "version", "pubkey_hex", "signature_hex", "bundle_sha256_hex", "bundle_size_bytes", "theorem_count", "lean4_verified", "published_at", "revoked" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Bundle identifier." }, "name": { "type": "string", "description": "Human-readable bundle name." }, "version": { "type": "string", "description": "Bundle version string." }, "pubkey_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hex-encoded Ed25519 public key of the bundle publisher (64 hex characters)." }, "signature_hex": { "type": "string", "description": "Lowercase hex-encoded Ed25519 signature over the canonical manifest (128 hex characters)." }, "bundle_sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 digest of the bundle binary (64 hex characters)." }, "bundle_size_bytes": { "type": "integer", "description": "Bundle binary size in bytes." }, "theorem_count": { "type": "integer", "description": "Number of theorems included in the bundle." }, "lean4_verified": { "type": "boolean", "description": "Whether all theorems in the bundle have been Lean 4 type-checked." }, "file_hashes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Map of file name to SHA-256 hex digest for individual files within the bundle." }, "binary_hashes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Map of binary artifact name to SHA-256 hex digest." }, "published_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the bundle was published." }, "revoked": { "type": "boolean", "description": "Whether the bundle has been revoked by the publisher. A revoked bundle is always `verified: false`." } } }, "ProveSystem_VerificationResult": { "type": "object", "description": "Cryptographic verification verdict for a proof certificate bundle.", "required": [ "verified", "reason", "reason_detail", "service", "verified_at" ], "properties": { "verified": { "type": "boolean", "description": "`true` only when the Ed25519 signature is valid, the signing key is in the trusted-issuer registry, and the bundle has not been revoked. `false` in all other cases — check `reason` for specifics." }, "reason": { "type": "string", "enum": [ "signature_valid", "bundle_revoked", "untrusted_issuer", "invalid", "malformed" ], "description": "Machine-readable reason code. `signature_valid` — all checks passed. `bundle_revoked` — the publisher has revoked this bundle. `untrusted_issuer` — the bundle signing key is not in the operator-managed trusted-issuer registry. `invalid` — signature failed Ed25519 verification. `malformed` — signature or public-key bytes could not be parsed." }, "reason_detail": { "type": "string", "description": "Human-readable explanation of the verification outcome." }, "service": { "type": "string", "description": "Name of the verification service that produced this verdict." }, "verified_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the verification was performed." } } }, "ProveSystem_BundleVerifyResult": { "type": "object", "description": "Response payload for `GET /v1/verify/{id}`.", "required": [ "bundle", "verification" ], "properties": { "bundle": { "$ref": "#/components/schemas/ProveSystem_PublicBundleRecord" }, "verification": { "$ref": "#/components/schemas/ProveSystem_VerificationResult" } } }, "ProveSystem_BinaryVerifyJsonRequest": { "type": "object", "additionalProperties": false, "description": "JSON body for `POST /v1/verify/binary` — preferred mode when the caller already has the SHA-256 digest and does not need to upload the binary.", "required": [ "sha256_hex" ], "properties": { "sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase SHA-256 hex digest of the binary to match (64 hex characters)." } } }, "ProveSystem_BinaryMatchSummary": { "type": "object", "description": "Summary of a bundle whose `bundle_sha256_hex` matches the supplied digest.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Bundle identifier." }, "name": { "type": "string", "description": "Bundle name." }, "version": { "type": "string", "description": "Bundle version." }, "published_at": { "type": "string", "format": "date-time", "description": "Publish timestamp." }, "revoked": { "type": "boolean", "description": "Whether the bundle has been revoked." } } }, "ProveSystem_BinaryVerifyResult": { "type": "object", "description": "Response payload for `POST /v1/verify/binary`.", "required": [ "binary_sha256_hex", "matches", "matched", "verified_at" ], "properties": { "binary_sha256_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The SHA-256 digest that was looked up (either supplied or computed from the uploaded binary)." }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/ProveSystem_BinaryMatchSummary" }, "description": "Bundle records whose `bundle_sha256_hex` equals the supplied digest. An empty array means no published bundle records this binary." }, "matched": { "type": "boolean", "description": "`true` when at least one bundle record contains this binary's hash." }, "verified_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the lookup was performed." } } }, "Billing_Overview": { "type": "object", "description": "Consolidated billing overview for an organization.", "properties": { "subscription": { "$ref": "#/components/schemas/Billing_Subscription", "description": "Active subscription (null if none)." }, "payment_methods": { "type": "array", "items": { "$ref": "#/components/schemas/Billing_PaymentMethod" }, "description": "Saved payment methods." }, "credits": { "$ref": "#/components/schemas/Billing_CreditBalance", "description": "Current credit balance." } } }, "Billing_SubscriptionStatus": { "type": "object", "description": "Subscription activation polling result.", "properties": { "active": { "type": "boolean", "description": "True once the Stripe webhook has confirmed activation." }, "status": { "type": [ "string", "null" ], "description": "Current subscription status string." } } }, "Billing_ClientConfig": { "type": "object", "description": "Stripe client configuration for the frontend.", "required": [ "publishable_key" ], "additionalProperties": false, "properties": { "publishable_key": { "type": "string", "description": "Stripe publishable key (pk_live_* or pk_test_*) used to initialize Stripe.js." } } }, "Billing_PaymentMethod": { "type": "object", "description": "A saved Stripe payment method.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Platform-assigned record id." }, "stripe_payment_method_id": { "type": "string", "description": "Stripe `pm_*` identifier." }, "type": { "type": "string", "description": "Payment method type (e.g. `card`)." }, "is_default": { "type": "boolean", "description": "Whether this is the default payment method." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created." } } }, "Billing_PaymentMethodUpsertRequest": { "type": "object", "description": "Upsert a Stripe payment method for the organization.", "required": [ "payment_method_id" ], "additionalProperties": false, "properties": { "payment_method_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe `pm_*` identifier. Must belong to this organization's Stripe customer." }, "set_as_default": { "type": "boolean", "description": "Whether to set this as the default payment method (default true when omitted)." }, "billing_details": { "type": "object", "additionalProperties": false, "description": "Optional billing detail overrides.", "properties": { "name": { "type": "string", "maxLength": 256, "description": "Cardholder name." }, "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Billing email." }, "address": { "type": "object", "additionalProperties": false, "description": "Billing address.", "properties": { "line1": { "type": "string", "maxLength": 500 }, "line2": { "type": "string", "maxLength": 500 }, "city": { "type": "string", "maxLength": 200 }, "state": { "type": "string", "maxLength": 200 }, "postal_code": { "type": "string", "maxLength": 32 }, "country": { "type": "string", "maxLength": 64 } } } } } } }, "Billing_CreditBalance": { "type": "object", "description": "AI credit balance for an organization.", "properties": { "balance": { "type": "number", "description": "Current available credit balance." }, "currency": { "type": "string", "description": "Currency code (e.g. `usd`)." } } }, "Billing_UsageSummary": { "type": "object", "description": "Billable usage rollup for an organization, optionally scoped to an environment.", "properties": { "window": { "type": "string", "description": "Requested aggregation window." }, "env_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Environment the rollup is scoped to (null for global aggregate)." }, "total_credits_used": { "type": "number", "description": "Total AI credits consumed in the window." }, "by_env": { "type": "array", "items": { "type": "object", "properties": { "env_id": { "type": "string", "format": "uuid" }, "credits_used": { "type": "number" } } }, "description": "Per-environment breakdown (only present in global-aggregate responses)." } } }, "Billing_Subscription": { "type": "object", "description": "An organization subscription record.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Platform-assigned subscription id." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "plan_id": { "type": "string", "description": "Pricing plan key." }, "interval": { "type": "string", "enum": [ "month", "year" ], "description": "Billing interval." }, "status": { "type": "string", "enum": [ "active", "trialing", "past_due", "canceled", "incomplete", "paused" ], "description": "Subscription lifecycle status." }, "seats": { "type": "integer", "description": "Number of seats." }, "cancel_at_period_end": { "type": "boolean", "description": "Whether the subscription is scheduled to cancel at period end." }, "current_period_end": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the current billing period." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Billing_SubscriptionCreateRequest": { "type": "object", "description": "Request body for creating a subscription.", "required": [ "plan_id", "interval", "payment_method_id", "billing_details" ], "additionalProperties": false, "properties": { "plan_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Pricing plan key or ID." }, "interval": { "type": "string", "enum": [ "month", "year" ], "description": "Billing interval." }, "payment_method_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe `pm_*` identifier." }, "billing_details": { "type": "object", "required": [ "name", "email" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "address": { "type": "object", "additionalProperties": false, "required": [ "line1", "city", "state", "postal_code", "country" ], "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 500 }, "line2": { "type": "string", "maxLength": 500 }, "city": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "minLength": 1, "maxLength": 200 }, "postal_code": { "type": "string", "minLength": 1, "maxLength": 32 }, "country": { "type": "string", "minLength": 1, "maxLength": 64 } } } } }, "seats": { "type": "integer", "minimum": 1, "description": "Number of seats (default 1)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata JSONB." } } }, "Billing_SubscriptionUpdateRequest": { "type": "object", "description": "Request body for updating a subscription. At least one field must be present.", "minProperties": 1, "additionalProperties": false, "properties": { "plan_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "New pricing plan key." }, "seats": { "type": "integer", "minimum": 1, "description": "New seat count." }, "cancel_at_period_end": { "type": "boolean", "description": "Schedule cancellation at the current period end." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata JSONB." } } }, "Billing_Invoice": { "type": "object", "description": "An invoice record.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Platform invoice id." }, "stripe_invoice_id": { "type": [ "string", "null" ], "description": "Stripe invoice id." }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "uncollectible", "void" ] }, "amount_due": { "type": "integer", "description": "Amount due in the smallest currency unit (e.g. cents)." }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "created_at": { "type": "string", "format": "date-time" } } }, "Billing_CheckoutSessionCreateRequest": { "type": "object", "description": "Request body for creating a hosted Stripe Checkout session.", "required": [ "price_id", "package_id" ], "additionalProperties": false, "properties": { "price_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe price id for the plan." }, "package_id": { "type": "string", "format": "uuid", "description": "SaaS package id (UUIDv7)." }, "success_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS URL to redirect to after successful checkout. Must target an allowlisted application domain." }, "cancel_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS URL to redirect to after checkout cancellation. Must target an allowlisted application domain." }, "trial_period_days": { "type": "integer", "minimum": 0, "maximum": 90, "description": "Client-suggested free trial length in days. Server-clamped to the plan's configured maximum; the effective value may be lower than requested." } } }, "Billing_CheckoutSessionResult": { "type": "object", "description": "Hosted Stripe Checkout session result.", "required": [ "checkout_url" ], "properties": { "checkout_url": { "type": [ "string", "null" ], "format": "uri", "description": "Stripe-hosted Checkout URL. Redirect the user here." } } }, "Billing_EmbeddedCheckoutSessionCreateRequest": { "type": "object", "description": "Request body for creating an embedded Stripe Checkout session.", "required": [ "package_id" ], "additionalProperties": false, "properties": { "price_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stripe price id. Required for `mode=subscription`; ignored for `mode=setup`." }, "package_id": { "type": "string", "format": "uuid", "description": "SaaS package id (UUIDv7)." }, "return_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS URL the embedded checkout redirects to on completion. Must target an allowlisted application domain." }, "trial_period_days": { "type": "integer", "minimum": 0, "maximum": 90, "description": "Client-suggested trial length in days. Server-clamped to the plan's maximum." }, "mode": { "type": "string", "enum": [ "subscription", "setup" ], "description": "Checkout mode. `subscription` (default) charges immediately; `setup` collects a card for later use." } } }, "Billing_EmbeddedCheckoutSessionResult": { "type": "object", "description": "Embedded Stripe Checkout session result.", "required": [ "client_secret" ], "properties": { "client_secret": { "type": "string", "description": "Stripe Checkout client secret for initializing Stripe.js Embedded Checkout." }, "mode": { "type": "string", "enum": [ "subscription", "setup" ], "description": "Mode of the session (`setup` only present when mode=setup was requested)." } } }, "Billing_CreditPackPurchaseRequest": { "type": "object", "description": "Optional body for a credit pack purchase. All fields are optional.", "additionalProperties": false, "properties": { "return_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS URL to redirect to after successful purchase. Must target an allowlisted application domain." }, "cancel_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS URL to redirect to on cancellation. Must target an allowlisted application domain." } } }, "Billing_CreditPackPurchaseResult": { "type": "object", "description": "Credit pack purchase initiation result.", "required": [ "order_id", "checkout_url" ], "properties": { "order_id": { "type": "string", "format": "uuid", "description": "Platform order id for status polling." }, "checkout_url": { "type": [ "string", "null" ], "format": "uri", "description": "Stripe Checkout URL to redirect the user to." }, "checkout_session_id": { "type": "string", "description": "Stripe Checkout session id." }, "credit_amount": { "type": "integer", "description": "Number of AI credits in the pack." }, "price_cents": { "type": "integer", "description": "Price in the smallest currency unit (e.g. cents)." }, "currency": { "type": "string", "description": "ISO 4217 currency code." } } }, "Billing_CreditPackOrder": { "type": "object", "description": "A one-time credit pack order.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "plan_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "Order status (e.g. `pending`, `completed`, `failed`)." }, "credit_amount": { "type": "integer" }, "price_cents": { "type": "integer" }, "currency": { "type": "string" }, "credits_applied": { "type": "boolean", "description": "Whether credits have been applied to the organization balance." }, "credits_applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "stripe_checkout_session_id": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Billing_PricingPlan": { "type": "object", "additionalProperties": true, "description": "A public pricing plan returned by the pricing endpoint.", "required": [ "id", "name", "currency", "interval" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Platform pricing plan identifier." }, "name": { "type": "string", "description": "Human-readable plan name." }, "description": { "type": [ "string", "null" ], "description": "Plan description." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code." }, "interval": { "type": "string", "enum": [ "month", "year", "one_time" ], "description": "Billing interval." }, "unit_amount": { "type": "integer", "minimum": 0, "description": "Price in minor currency units." }, "trial_period_days": { "type": [ "integer", "null" ], "minimum": 0, "description": "Trial period length in days." }, "stripe_price_id": { "type": [ "string", "null" ], "description": "Stripe Price id." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Marketing feature list." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Additional platform metadata." } } }, "Billing_InvalidatePricingCacheRequest": { "type": "object", "additionalProperties": false, "description": "Optional filters for pricing cache invalidation.", "properties": { "package_id": { "type": "string", "format": "uuid", "description": "Limit invalidation to a specific SaaS package." }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ], "description": "Limit invalidation to a specific environment." } } }, "Billing_SignupCheckoutIntentCreateRequest": { "type": "object", "additionalProperties": false, "description": "Request body for creating a pre-auth signup checkout intent. Exactly one of `org_id`/`org_slug_or_id`/`domain`, one of `package_id`/`package_slug`, and one of `pricing_plan_price_id`/`billing_interval` must be supplied.", "required": [ "anonymous_session_id" ], "properties": { "anonymous_session_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable anonymous session identifier to link the pre-auth intent to a post-auth session." }, "org_id": { "type": "string", "format": "uuid" }, "org_slug_or_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "domain": { "type": "string", "minLength": 1, "maxLength": 253 }, "package_id": { "type": "string", "format": "uuid" }, "package_slug": { "type": "string", "minLength": 1, "maxLength": 128 }, "pricing_plan_price_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "billing_interval": { "type": "string", "enum": [ "month", "year" ] }, "trial_period_days": { "type": "integer", "minimum": 0, "description": "Requested trial length (server-clamped to plan maximum)." }, "metadata": { "type": "object", "additionalProperties": true } } }, "Billing_SignupCheckoutIntentResumeRequest": { "type": "object", "additionalProperties": false, "description": "Optional overrides when resuming a signup checkout intent.", "properties": { "pricing_plan_price_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "billing_interval": { "type": "string", "enum": [ "month", "year" ] } } }, "Billing_SignupCheckoutIntent": { "type": "object", "additionalProperties": true, "description": "A pre-auth signup checkout intent.", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "expired", "cancelled" ] }, "checkout_url": { "type": [ "string", "null" ], "format": "uri", "description": "Hosted checkout redirect URL." }, "client_secret": { "type": [ "string", "null" ], "description": "Stripe embedded checkout client_secret." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Billing_StripeConnect": { "type": "object", "additionalProperties": false, "description": "Legacy Stripe Connect configuration for a (SaaS package, environment) combination.", "required": [ "id", "saas_package_id", "environment", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "stripe_account_id": { "type": [ "string", "null" ] }, "charges_enabled": { "type": "boolean", "default": false }, "payouts_enabled": { "type": "boolean", "default": false }, "details_submitted": { "type": "boolean", "default": false }, "platform_fee_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "client_fee_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Billing_StripeConnectCreateRequest": { "type": "object", "additionalProperties": false, "description": "Request body for creating a legacy Stripe Connect configuration.", "required": [ "saas_package_id", "stripe_account_id" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "stripe_account_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Stripe account id (`acct_...`). Required for the legacy endpoint." }, "account_type": { "type": "string", "enum": [ "standard", "express", "custom" ], "description": "Stripe Connect account type (default `express`)." }, "publishable_key": { "type": "string", "minLength": 1, "maxLength": 512 }, "business_profile": { "type": "object", "additionalProperties": true }, "webhook_secret_ref": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Reference name for the stored webhook secret." } } }, "Billing_StripeConnectUpdateRequest": { "type": "object", "additionalProperties": false, "description": "Request body for updating a legacy Stripe Connect configuration. `saas_package_id` and `environment` identify the record; at least one other field must be supplied.", "required": [ "saas_package_id" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "stripe_account_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "account_type": { "type": "string", "enum": [ "standard", "express", "custom" ] }, "publishable_key": { "type": "string", "minLength": 1, "maxLength": 512 }, "business_profile": { "type": "object", "additionalProperties": true }, "webhook_secret_ref": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "Billing_StripeConnectOnboardRequest": { "type": "object", "additionalProperties": false, "description": "Request body for the deprecated POST /v1/stripe-connect/onboard endpoint.", "required": [ "saas_package_id", "stripe_account_id" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "stripe_account_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "refresh_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "return_url": { "type": "string", "format": "uri", "maxLength": 2048 } } }, "Billing_StripeConnectOnboardCompleteRequest": { "type": "object", "additionalProperties": false, "description": "Request body for completing legacy Stripe Connect onboarding.", "required": [ "saas_package_id" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "charges_enabled": { "type": "boolean" }, "payouts_enabled": { "type": "boolean" }, "details_submitted": { "type": "boolean" } } }, "Billing_StripeConnectUpdateFeesRequest": { "type": "object", "additionalProperties": false, "description": "Request body for updating legacy Stripe Connect fee percentages. At least one of `platform_fee_percent`/`client_fee_percent` must be supplied.", "required": [ "saas_package_id" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "platform_fee_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "client_fee_percent": { "type": "number", "minimum": 0, "maximum": 100 } } }, "Billing_StripeConnectSyncRequest": { "type": "object", "additionalProperties": false, "description": "Request body for syncing legacy Stripe Connect status.", "required": [ "saas_package_id" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] } } }, "Billing_StripeProfile": { "type": "object", "additionalProperties": false, "description": "A Stripe Connect profile (Wave-3a model).", "required": [ "id", "org_id", "name", "status", "version", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": [ "string", "null" ], "maxLength": 512 }, "stripe_account_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "onboarding", "restricted", "active", "disabled" ] }, "country": { "type": [ "string", "null" ] }, "default_currency": { "type": [ "string", "null" ] }, "charges_enabled": { "type": "boolean" }, "payouts_enabled": { "type": "boolean" }, "details_submitted": { "type": "boolean" }, "platform_fee_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "client_fee_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "version": { "type": "integer", "minimum": 1, "description": "Optimistic concurrency version." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Billing_StripeProfileCreateRequest": { "type": "object", "additionalProperties": false, "description": "Request body for creating a Stripe Connect profile.", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": "string", "maxLength": 512 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "default_currency": { "type": "string", "minLength": 3, "maxLength": 3 } } }, "Billing_StripeProfileUpdateRequest": { "type": "object", "additionalProperties": false, "description": "Request body for updating a Stripe Connect profile. `expected_version` required; at least one mutable field beyond it.", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": "string", "maxLength": 512 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "default_currency": { "type": "string", "minLength": 3, "maxLength": 3 } } }, "Billing_StripeProfileDeleteRequest": { "type": "object", "additionalProperties": false, "description": "Request body for soft-deleting a Stripe Connect profile.", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "minimum": 1 } } }, "Billing_StripeProfileUpdateFeesRequest": { "type": "object", "additionalProperties": false, "description": "Request body for updating a profile's fee percentages. At least one of `platform_fee_percent`/`client_fee_percent` must be supplied.", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "minimum": 1 }, "platform_fee_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 50, "description": "Platform application fee percentage (0–50). Nullable to clear." }, "client_fee_percent": { "type": "number", "minimum": 0, "maximum": 50, "description": "Client-side fee percentage (0–50)." } } }, "Billing_StripeProfileRotateWebhookSecretRequest": { "type": "object", "additionalProperties": false, "description": "Request body for rotating a profile's webhook secret.", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "minimum": 1 } } }, "Billing_StripeProfileOnboardStartRequest": { "type": "object", "additionalProperties": false, "description": "Optional redirect URL overrides for the Stripe AccountLink.", "properties": { "refresh_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "return_url": { "type": "string", "format": "uri", "maxLength": 2048 } } }, "Billing_StripeProfileOnboardStartResult": { "type": "object", "additionalProperties": false, "description": "Result from starting Stripe Connect profile onboarding.", "required": [ "onboarding_url", "expires_at" ], "properties": { "onboarding_url": { "type": "string", "format": "uri", "description": "Stripe AccountLink URL for the operator." }, "expires_at": { "type": "string", "format": "date-time" } } }, "Billing_StripeProfileOnboardCompleteRequest": { "type": "object", "additionalProperties": false, "description": "Request body for completing Stripe Connect onboarding.", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "minimum": 1 } } }, "Billing_StripeProfileSyncRequest": { "type": "object", "additionalProperties": false, "description": "Optional body for queueing a sync.", "properties": { "environments": { "type": "array", "items": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "minItems": 1 } } }, "Billing_StripeProfileLink": { "type": "object", "additionalProperties": false, "description": "A link between a Stripe Connect profile and a (SaaS package, environment) combination.", "required": [ "profile_id", "saas_package_id", "environment", "created_at" ], "properties": { "profile_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Billing_StripeProfileLinkPackageRequest": { "type": "object", "additionalProperties": false, "description": "Request body for linking a package to a Stripe Connect profile.", "required": [ "saas_package_id", "environment" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] } } }, "Billing_ApiKeyListItem": { "type": "object", "additionalProperties": false, "description": "Public metadata for an organization API key.", "required": [ "id", "org_id", "name", "prefix", "scopes", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "prefix": { "type": "string", "minLength": 8, "maxLength": 8, "description": "First 8 hex chars of the raw key, for display identification." }, "scopes": { "type": "array", "items": { "type": "string" } }, "pinned_env_id": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000 }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Billing_ApiKeyCreateRequest": { "type": "object", "additionalProperties": false, "description": "Request body for creating an organization API key.", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Expiry in days from now (omit for non-expiring)." }, "rate_limit_rpm": { "type": "integer", "minimum": 1, "maximum": 10000 }, "pinned_env_id": { "type": "string", "format": "uuid" } } }, "Billing_ApiKeyCreated": { "type": "object", "additionalProperties": false, "description": "API key creation result. `key` is the raw key shown exactly once.", "required": [ "id", "key", "prefix", "name", "scopes", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "pattern": "^bb_live_[a-f0-9]{8}_[a-f0-9]{64}$", "description": "Full raw API key in format `bb_live_{8hexchars}_{64hexchars}`. Store it now — it will not be shown again." }, "prefix": { "type": "string", "minLength": 8, "maxLength": 8 }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Billing_ApiKeyRotateRequest": { "type": "object", "additionalProperties": false, "description": "Optional body for rotating an API key.", "properties": { "grace_period_minutes": { "type": "integer", "minimum": 0, "maximum": 60, "default": 5, "description": "How long the old key remains valid after rotation (0–60 min)." } } }, "Billing_ApiKeyRotated": { "type": "object", "additionalProperties": false, "description": "API key rotation result. `key` is the new raw key shown exactly once.", "required": [ "id", "key", "prefix", "name", "scopes", "old_key_id", "old_key_expires_at", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "New key identifier." }, "key": { "type": "string", "pattern": "^bb_live_[a-f0-9]{8}_[a-f0-9]{64}$", "description": "New raw API key. Store it now." }, "prefix": { "type": "string", "minLength": 8, "maxLength": 8 }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "old_key_id": { "type": "string", "format": "uuid" }, "old_key_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Grace period expiry for the old key (null = revoked immediately)." }, "created_at": { "type": "string", "format": "date-time" } } }, "Billing_AcademicVerification": { "type": "object", "additionalProperties": false, "description": "An academic verification record.", "required": [ "id", "user_id", "status", "provider", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "saas_package_id": { "type": [ "string", "null" ], "format": "uuid" }, "provider": { "type": "string", "enum": [ "manual_review", "sheerid", "verifyle" ] }, "status": { "type": "string", "enum": [ "pending", "submitted", "approved", "rejected", "expired" ] }, "institution_name": { "type": [ "string", "null" ], "maxLength": 256 }, "academic_role": { "type": [ "string", "null" ], "maxLength": 128 }, "rejection_reason": { "type": [ "string", "null" ], "maxLength": 1024 }, "reviewed_by": { "type": [ "string", "null" ], "format": "uuid" }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Billing_AcademicVerificationStartRequest": { "type": "object", "additionalProperties": false, "description": "Request body for starting an academic verification.", "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "manual_review", "sheerid", "verifyle" ] } } }, "Billing_AcademicVerificationSubmitRequest": { "type": "object", "additionalProperties": false, "description": "Request body for submitting evidence to an academic verification.", "required": [ "institution_name", "academic_role" ], "properties": { "institution_name": { "type": "string", "minLength": 1, "maxLength": 256 }, "academic_role": { "type": "string", "minLength": 1, "maxLength": 128 }, "evidence_url": { "type": "string", "format": "uri", "maxLength": 2048 } } }, "Billing_AcademicVerificationReviewRequest": { "type": "object", "additionalProperties": false, "description": "Request body for reviewing an academic verification.", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "rejection_reason": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Required when `decision=rejected`." } } }, "Billing_AcademicWebhookPayload": { "type": "object", "additionalProperties": true, "description": "Provider-controlled webhook payload. Exact shape varies by provider. The platform normalizes it internally. Must contain a provider event identifier (`event_id` or `id`) and a verification reference (`verification_id`, `session_id`, or `data.verification_id`).", "properties": { "event_id": { "type": "string", "description": "Provider event id (used for idempotency). Some providers use `id`." }, "verification_id": { "type": "string", "description": "Platform verification id." }, "org_id": { "type": "string", "description": "Organization id." }, "status": { "type": "string", "description": "Provider verification outcome status." } } }, "CommsMail_MailboxPlanTier": { "type": "string", "enum": [ "free", "paid" ], "description": "Service tier for the mailbox (`free` or `paid`)." }, "CommsMail_Mailbox": { "type": "object", "description": "A mailbox record.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Mailbox identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization identifier." }, "domain_id": { "type": "string", "format": "uuid", "description": "Associated domain identifier." }, "local_part": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Local part of the email address (the part before `@`)." }, "display_name": { "type": "string", "maxLength": 128, "nullable": true, "description": "Optional display name." }, "plan_tier": { "$ref": "#/components/schemas/CommsMail_MailboxPlanTier" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "org_id", "domain_id", "local_part", "plan_tier", "created_at", "updated_at" ] }, "CommsMail_MailboxCreateRequest": { "type": "object", "description": "Request body to create a mailbox.", "additionalProperties": false, "required": [ "domainId", "localPart" ], "properties": { "domainId": { "type": "string", "format": "uuid", "description": "Domain identifier." }, "localPart": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Local part (before `@`)." }, "displayName": { "type": "string", "maxLength": 255, "description": "Optional display name." }, "planTier": { "$ref": "#/components/schemas/CommsMail_MailboxPlanTier" } } }, "CommsMail_Settings": { "type": "object", "description": "Organization-level bbmail settings.", "properties": { "org_id": { "type": "string", "format": "uuid" }, "default_plan_tier": { "$ref": "#/components/schemas/CommsMail_MailboxPlanTier" }, "max_mailboxes": { "type": "integer", "minimum": 0 }, "updated_at": { "type": "string", "format": "date-time" } } }, "CommsMail_SettingsPatchRequest": { "type": "object", "description": "Update the caller's per-mailbox preferences. All fields are optional except `mailboxId`.", "additionalProperties": false, "required": [ "mailboxId" ], "properties": { "mailboxId": { "type": "string", "format": "uuid", "description": "Mailbox whose settings to update." }, "reading_pane": { "type": "string", "enum": [ "below", "right", "off" ], "description": "Reading pane layout." }, "density": { "type": "string", "enum": [ "comfortable", "cozy", "compact" ], "description": "Message list density." }, "conversation_view": { "type": "boolean", "description": "Group messages by conversation thread." }, "custom_signature_html": { "type": "string", "maxLength": 65536, "nullable": true, "description": "HTML signature appended to outbound messages. Pass `null` to clear." }, "undo_send_seconds": { "type": "integer", "enum": [ 0, 5, 10, 20, 30 ], "description": "Undo-send delay in seconds." }, "mark_read_mode": { "type": "string", "enum": [ "immediate", "after_seconds", "manual" ], "description": "When messages are automatically marked read." }, "mark_read_delay_ms": { "type": "integer", "minimum": 0, "description": "Delay before marking read (applies when `mark_read_mode` is `after_seconds`)." } } }, "CommsMail_AttachmentRef": { "type": "object", "description": "Attachment reference for a message send.", "additionalProperties": false, "required": [ "sha256", "filename", "contentType" ], "properties": { "sha256": { "type": "string", "minLength": 64, "maxLength": 64, "description": "Hex SHA-256 of the attachment content." }, "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Original filename." }, "contentType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "MIME content-type." }, "inline": { "type": "boolean", "description": "If `true`, the part is sent as `Content-Disposition: inline`." }, "cid": { "type": "string", "maxLength": 255, "description": "Optional Content-ID for inline images." } } }, "CommsMail_MessageSendRequest": { "type": "object", "description": "Send an outbound email message.", "additionalProperties": false, "required": [ "mailboxId", "to", "subject" ], "properties": { "mailboxId": { "type": "string", "format": "uuid", "description": "Sending mailbox identifier." }, "to": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 50, "description": "Primary recipients (max 50)." }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50, "description": "CC recipients (max 50)." }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50, "description": "BCC recipients (max 50)." }, "subject": { "type": "string", "minLength": 1, "maxLength": 998, "description": "Message subject (RFC 5322 limit: 998 chars)." }, "html": { "type": "string", "maxLength": 2097152, "description": "HTML body (max 2 MiB)." }, "text": { "type": "string", "maxLength": 2097152, "description": "Plain-text body (max 2 MiB)." }, "replyTo": { "type": "string", "format": "email", "description": "Optional `Reply-To` address." }, "inReplyTo": { "type": "string", "maxLength": 998, "description": "Message-ID of the message being replied to." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/CommsMail_AttachmentRef" }, "maxItems": 32, "description": "Attached files (max 32). Each file must be pre-uploaded via POST /v1/bbmail/attachments." } } }, "CommsMail_MessageListQuery": { "type": "object", "description": "Query parameters for listing messages." }, "CommsMail_Message": { "type": "object", "description": "An email message record.", "properties": { "id": { "type": "string", "format": "uuid" }, "mailbox_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "subject": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "CommsMail_AttachmentUploadResponse": { "type": "object", "description": "Result of uploading an attachment.", "properties": { "sha256": { "type": "string", "minLength": 64, "maxLength": 64, "description": "Hex SHA-256 of the stored file. Use this value in `MessageSendRequest.attachments[].sha256`." }, "size": { "type": "integer", "description": "Stored byte length." }, "contentType": { "type": "string", "description": "Detected or declared MIME type." } }, "required": [ "sha256", "size", "contentType" ] }, "CommsMail_Label": { "type": "object", "description": "A mailbox label.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "mailbox_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "color": { "type": "string", "maxLength": 32, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "CommsMail_LabelCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "mailboxId", "name" ], "properties": { "mailboxId": { "type": "string", "format": "uuid", "description": "Mailbox to create the label in." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Label display name." }, "parentId": { "type": "string", "format": "uuid", "nullable": true, "description": "Parent label for nesting." }, "color": { "type": "string", "maxLength": 32, "description": "Optional color token." }, "ordinal": { "type": "integer", "description": "Sort order within the label list." } } }, "CommsMail_LabelPatchRequest": { "type": "object", "description": "All fields optional except `mailboxId`.", "additionalProperties": false, "required": [ "mailboxId" ], "properties": { "mailboxId": { "type": "string", "format": "uuid", "description": "Mailbox that owns the label." }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "color": { "type": "string", "maxLength": 32, "nullable": true }, "ordinal": { "type": "integer" }, "parentId": { "type": "string", "format": "uuid", "nullable": true } } }, "CommsMail_FilterAction": { "type": "object", "description": "A single filter action.", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "label", "archive", "delete", "mark_read", "forward", "star" ], "description": "Action type." }, "label_id": { "type": "string", "format": "uuid", "description": "Required when `type` is `label`." }, "forward_to": { "type": "string", "format": "email", "description": "Required when `type` is `forward`." } } }, "CommsMail_Filter": { "type": "object", "description": "A mailbox filter rule.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "mailbox_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "criteria": { "type": "object", "additionalProperties": true, "description": "Filter criteria (from/to/subject/body/has_attachment)." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/CommsMail_FilterAction" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "CommsMail_FilterCreateRequest": { "type": "object", "description": "Create a mailbox filter. `criteria` and `actions` are free-form JSON objects validated server-side by the stored procedure.", "additionalProperties": false, "required": [ "mailboxId", "criteria", "actions" ], "properties": { "mailboxId": { "type": "string", "format": "uuid", "description": "Mailbox to add the filter to." }, "criteria": { "type": "object", "additionalProperties": true, "description": "Filter matching criteria (from, to, subject, body, has_attachment). Schema enforced server-side." }, "actions": { "type": "object", "additionalProperties": true, "description": "Filter actions to apply on match (label, archive, delete, mark_read, forward, star). Schema enforced server-side." }, "ordinal": { "type": "integer", "description": "Sort order for filter evaluation (default 0)." }, "enabled": { "type": "boolean", "description": "Whether the filter is active (default true)." } } }, "CommsMail_FilterPatchRequest": { "type": "object", "description": "Update a mailbox filter. `mailboxId` is required; all other fields are optional.", "additionalProperties": false, "required": [ "mailboxId" ], "properties": { "mailboxId": { "type": "string", "format": "uuid", "description": "Mailbox that owns the filter." }, "criteria": { "type": "object", "additionalProperties": true }, "actions": { "type": "object", "additionalProperties": true }, "ordinal": { "type": "integer" }, "enabled": { "type": "boolean" } } }, "CommsMail_Domain": { "type": "object", "description": "A verified sending/receiving domain.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "domain": { "type": "string", "format": "hostname" }, "verified": { "type": "boolean" }, "dns_verified": { "type": "boolean" }, "ses_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "CommsMail_DomainCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "domain" ], "properties": { "domain": { "type": "string", "format": "hostname", "minLength": 1, "maxLength": 253, "description": "The domain name to add (e.g. `mail.example.com`)." } } }, "CommsMail_InboundSmtpRequest": { "type": "object", "description": "Inbound SMTP webhook body delivered by the MTA. Internal fields are stripped by the server; only the public fields are shown.", "additionalProperties": true, "properties": { "context": { "type": "object", "description": "MTA connection context.", "properties": { "client": { "type": "object", "properties": { "ip": { "type": "string", "description": "Client IP address." }, "ptr": { "type": "string", "description": "Reverse-DNS PTR name." } } } } }, "envelope": { "type": "object", "description": "SMTP envelope.", "properties": { "from": { "type": "string", "description": "MAIL FROM address." }, "to": { "type": "string", "description": "RCPT TO address." } } }, "message": { "type": "object", "description": "Raw message reference.", "properties": { "contents": { "type": "string", "description": "URL or reference to raw RFC 2822 message." } } }, "spf_pass": { "type": "boolean", "description": "SPF check outcome." }, "dkim_pass": { "type": "boolean", "description": "DKIM check outcome." }, "dmarc_pass": { "type": "boolean", "description": "DMARC check outcome." } } }, "CommsMail_InboundSmtpResponse": { "type": "object", "description": "Response from the inbound SMTP webhook.", "properties": { "action": { "type": "string", "enum": [ "discard", "defer" ], "description": "`discard` = success (MTA should not retry). `defer` signals a temporary failure; the MTA should retry." } }, "required": [ "action" ] }, "CommsMail_MailInternalAuditRequest": { "type": "object", "description": "Internal audit event batch from the mailbox Durable Object.", "additionalProperties": false, "required": [ "op", "affected" ], "properties": { "op": { "type": "string", "enum": [ "flag_set", "label_apply", "label_remove", "move", "delete", "body_hydrate", "draft_save", "report_spam", "report_phishing", "not_spam", "snooze" ], "description": "Mailbox WebSocket operation type being audited." }, "affected": { "type": "object", "additionalProperties": true, "description": "Map of affected item identifiers and metadata." }, "edit_count": { "type": "integer", "minimum": 0 } } }, "CommsMail_MailCheckpointRequest": { "type": "object", "description": "Mailbox Durable Object SQLite snapshot checkpoint request.", "additionalProperties": false, "required": [ "new_etag", "sqlite_sha256" ], "properties": { "prior_etag": { "type": "string", "maxLength": 512, "nullable": true, "description": "Expected current catalog etag (compare-and-swap precondition). Pass `null` for the first checkpoint commit (no prior snapshot)." }, "new_etag": { "type": "string", "minLength": 1, "maxLength": 512, "description": "New etag after the snapshot write." }, "sqlite_sha256": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Hex SHA-256 of the uploaded snapshot file." }, "schema_version": { "type": "integer", "minimum": 0, "description": "SQLite schema version of the snapshot (optional)." }, "byte_length": { "type": "integer", "minimum": 0, "description": "Snapshot file byte length (optional)." } } }, "CommsMail_CheckpointResult": { "type": "object", "description": "Result of a successful mailbox checkpoint commit.", "properties": { "committed": { "type": "boolean" }, "new_etag": { "type": "string" } } }, "CommsMail_UnsubscribeResponse": { "type": "object", "description": "Successful unsubscribe response.", "required": [ "unsubscribed", "email" ], "properties": { "unsubscribed": { "type": "boolean", "enum": [ true ] }, "email": { "type": "string", "format": "email", "description": "The email address that was unsubscribed." } } }, "CommsCalendar_AuditRequest": { "type": "object", "description": "Calendar Durable Object audit event payload. Internal signed service-to-service call — not part of the public consumer API.", "additionalProperties": false, "required": [ "op", "_audit" ], "properties": { "op": { "type": "string", "enum": [ "event_create", "event_update", "event_delete", "event_rsvp", "event_reminder_set" ], "description": "Calendar event operation type." }, "affected": { "type": "object", "additionalProperties": true, "description": "Operation-specific context (event IDs, change summary, etc.)." }, "edit_count": { "type": "integer", "minimum": 0 }, "_audit": { "type": "object", "description": "Persisting user identity (captured by the DO from the session's JWT-authenticated socket attachment).", "required": [ "persisted_by_user_id", "persisted_by_org_id" ], "properties": { "persisted_by_user_id": { "type": "string", "format": "uuid" }, "persisted_by_org_id": { "type": "string", "format": "uuid" } } } } }, "CommsCalendar_CheckpointRequest": { "type": "object", "description": "Calendar Durable Object SQLite snapshot checkpoint request. Internal signed service-to-service call — not part of the public consumer API. `prior_etag` is nullable for the first-ever commit.", "additionalProperties": false, "required": [ "new_etag", "sqlite_sha256", "_audit" ], "properties": { "prior_etag": { "type": "string", "maxLength": 512, "nullable": true, "description": "Previously stored etag. `null` or absent for the first commit." }, "new_etag": { "type": "string", "minLength": 1, "maxLength": 512 }, "sqlite_sha256": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Hex-encoded SHA-256 of the persisted SQLite snapshot." }, "byte_length": { "type": "integer", "minimum": 0 }, "_audit": { "type": "object", "required": [ "persisted_by_user_id", "persisted_by_org_id" ], "properties": { "persisted_by_user_id": { "type": "string", "format": "uuid", "nullable": true }, "persisted_by_org_id": { "type": "string", "format": "uuid", "nullable": true } } } } }, "CommsCalendar_CheckpointResult": { "type": "object", "properties": { "committed": { "type": "boolean" }, "new_etag": { "type": "string" } } }, "CommsCalendar_Calendar": { "type": "object", "description": "A calendar record.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "maxLength": 255, "nullable": true }, "color": { "type": "string", "maxLength": 32, "nullable": true }, "timezone": { "type": "string", "maxLength": 64 }, "hidden": { "type": "boolean" }, "default": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CommsCalendar_CalendarCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "kind": { "type": "string", "enum": [ "primary", "secondary", "resource", "subscribed_url", "interest", "birthday" ] }, "timezone": { "type": "string", "maxLength": 100 }, "default_color": { "type": "integer", "minimum": 0, "maximum": 11, "description": "Color slot (0–11)." }, "description": { "type": "string", "maxLength": 2000 }, "public_visibility": { "type": "string", "enum": [ "none", "freebusy", "details" ] } } }, "CommsCalendar_CalendarUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200, "nullable": true }, "description": { "type": "string", "maxLength": 2000, "nullable": true }, "timezone": { "type": "string", "maxLength": 100 }, "default_color": { "type": "integer", "minimum": 0, "maximum": 11 }, "public_visibility": { "type": "string", "enum": [ "none", "freebusy", "details" ] }, "status": { "type": "string", "enum": [ "active", "hidden", "archived" ] } } }, "CommsCalendar_ShareSetRequest": { "type": "object", "description": "Grant or revoke a calendar share. `action` defaults to `grant`. `scope` and `target_id` identify the grantee. `capability` sets the access level.", "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "grant", "revoke" ] }, "share_id": { "type": "string", "format": "uuid", "description": "Share record to update (optional; omit to create)." }, "scope": { "type": "string", "enum": [ "user", "group", "department", "project", "org", "public" ] }, "target_id": { "type": "string", "maxLength": 255, "nullable": true, "description": "Target identifier (user id, group id, etc.). Null for org/public scope." }, "is_public": { "type": "boolean" }, "recipient_org_id": { "type": "string", "format": "uuid", "nullable": true }, "recipient_user_id": { "type": "string", "format": "uuid", "nullable": true }, "capability": { "type": "string", "enum": [ "freebusy", "details", "write", "admin" ], "description": "Access level to grant." } } }, "CommsCalendar_AccessRequestRequest": { "type": "object", "description": "Request access to a calendar. Provide `calendar_id` or `owner_email` (or both).", "additionalProperties": false, "properties": { "calendar_id": { "type": "string", "format": "uuid", "description": "Target calendar id." }, "owner_email": { "type": "string", "maxLength": 320, "description": "Owner email to look up the calendar by." }, "capability": { "type": "string", "enum": [ "freebusy", "details", "write" ], "description": "Requested access level." }, "message": { "type": "string", "maxLength": 2000, "description": "Optional message to the calendar owner." }, "send_email": { "type": "boolean", "description": "Send an email notification to the calendar owner." } } }, "CommsCalendar_EventCreateRequest": { "type": "object", "description": "Create a calendar event. All timing fields are optional at the route level; the stored procedure validates required combinations. Unknown top-level keys are rejected (mass-assignment guard).", "additionalProperties": false, "required": [ "calendar_id" ], "properties": { "calendar_id": { "type": "string", "format": "uuid" }, "recurrence_role": { "type": "string", "enum": [ "single", "master", "override" ] }, "series_master_id": { "type": "string", "format": "uuid", "nullable": true }, "recurrence_id": { "type": "string", "maxLength": 64, "nullable": true }, "title": { "type": "string", "maxLength": 1024, "nullable": true }, "description_html": { "type": "string", "maxLength": 262144, "nullable": true }, "location": { "type": "string", "maxLength": 2048, "nullable": true }, "starts_at": { "type": "string", "maxLength": 64, "nullable": true, "description": "ISO-8601 timestamp or RFC 3339 date-time string." }, "ends_at": { "type": "string", "maxLength": 64, "nullable": true }, "start_date": { "type": "string", "maxLength": 32, "nullable": true, "description": "All-day start date (YYYY-MM-DD)." }, "end_date": { "type": "string", "maxLength": 32, "nullable": true }, "start_tz": { "type": "string", "maxLength": 100, "nullable": true }, "end_tz": { "type": "string", "maxLength": 100, "nullable": true }, "is_all_day": { "type": "boolean" }, "event_type": { "type": "string", "maxLength": 32 }, "color_id": { "type": "integer", "minimum": 0, "maximum": 24, "nullable": true }, "visibility": { "type": "string", "enum": [ "default", "public", "private", "confidential" ] }, "transparency": { "type": "string", "enum": [ "opaque", "transparent" ] }, "status": { "type": "string", "enum": [ "confirmed", "tentative", "cancelled" ] }, "rrule": { "type": "string", "maxLength": 4096, "nullable": true, "description": "RFC 5545 RRULE." }, "rdate": { "type": "string", "maxLength": 8192, "nullable": true }, "exdate": { "type": "string", "maxLength": 8192, "nullable": true }, "guests_can_invite": { "type": "boolean" }, "guests_can_modify": { "type": "boolean" }, "guests_can_see_others": { "type": "boolean" }, "conferencing": { "type": "object", "additionalProperties": true, "nullable": true }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 25, "nullable": true }, "reminders_use_default": { "type": "boolean" }, "reminders": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 5 }, "attendees": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "event_type_props": { "type": "object", "additionalProperties": true, "nullable": true }, "extended_props": { "type": "object", "additionalProperties": true, "nullable": true } } }, "CommsCalendar_EventUpdateRequest": { "type": "object", "description": "Update a calendar event. All fields are optional; the stored procedure validates combinations.", "additionalProperties": false, "properties": { "calendar_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 1024, "nullable": true }, "description_html": { "type": "string", "maxLength": 262144, "nullable": true }, "location": { "type": "string", "maxLength": 2048, "nullable": true }, "starts_at": { "type": "string", "maxLength": 64, "nullable": true }, "ends_at": { "type": "string", "maxLength": 64, "nullable": true }, "start_date": { "type": "string", "maxLength": 32, "nullable": true }, "end_date": { "type": "string", "maxLength": 32, "nullable": true }, "start_tz": { "type": "string", "maxLength": 100, "nullable": true }, "end_tz": { "type": "string", "maxLength": 100, "nullable": true }, "is_all_day": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "default", "public", "private", "confidential" ] }, "transparency": { "type": "string", "enum": [ "opaque", "transparent" ] }, "status": { "type": "string", "enum": [ "confirmed", "tentative", "cancelled" ] }, "rrule": { "type": "string", "maxLength": 4096, "nullable": true }, "rdate": { "type": "string", "maxLength": 8192, "nullable": true }, "exdate": { "type": "string", "maxLength": 8192, "nullable": true }, "conferencing": { "type": "object", "additionalProperties": true, "nullable": true }, "reminders_use_default": { "type": "boolean" }, "reminders": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 5 }, "attendees": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "CommsCalendar_EventMoveRequest": { "type": "object", "additionalProperties": false, "required": [ "source_calendar_id", "dest_calendar_id" ], "properties": { "source_calendar_id": { "type": "string", "format": "uuid", "description": "Calendar to move the event from." }, "dest_calendar_id": { "type": "string", "format": "uuid", "description": "Calendar to move the event to." } } }, "CommsCalendar_RsvpRequest": { "type": "object", "additionalProperties": false, "properties": { "response_status": { "type": "string", "enum": [ "accepted", "declined", "tentative", "needsAction" ], "description": "RSVP response." }, "comment": { "type": "string", "maxLength": 2000, "description": "Optional message to the organizer." }, "proposed_start": { "type": "string", "maxLength": 64, "description": "Counter-proposed start (ISO-8601 timestamp)." }, "proposed_end": { "type": "string", "maxLength": 64, "description": "Counter-proposed end (ISO-8601 timestamp)." }, "proposed_message": { "type": "string", "maxLength": 2000 }, "additional_guests": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 50 } } }, "CommsCalendar_ReminderSetRequest": { "type": "object", "additionalProperties": false, "description": "Replace the caller's reminder settings for an event. All fields are optional; passing an empty object clears custom reminders if `reminders_use_default` is not set.", "properties": { "calendar_id": { "type": "string", "format": "uuid", "description": "Owning calendar (optional; resolved from event when omitted)." }, "reminders_use_default": { "type": "boolean", "description": "When `true`, apply the calendar's default reminder rules instead of the explicit `reminders` list." }, "reminders": { "type": "array", "description": "Explicit reminder definitions. Each item is a JsonObject validated by the stored procedure.", "maxItems": 5, "items": { "type": "object", "additionalProperties": true } } } }, "CommsCalendar_EventPublishRequest": { "type": "object", "additionalProperties": false, "description": "Publish or unpublish an event. `calendar_id` in the request body is optional (the `calendar_id` query parameter is the authoritative source).", "properties": { "calendar_id": { "type": "string", "format": "uuid", "description": "Owning calendar. Overridden by the query parameter." }, "action": { "type": "string", "enum": [ "publish", "unpublish" ], "description": "`publish` issues a public render token; `unpublish` revokes it." }, "show_fields": { "type": "array", "description": "Allowlist of event fields to expose in the public render.", "maxItems": 40, "items": { "type": "string", "maxLength": 64 } } } }, "CommsCalendar_TaskListSetRequest": { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "create", "rename", "delete" ] }, "list_id": { "type": "string", "format": "uuid", "description": "Required for `rename` and `delete`." }, "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required for `create` and `rename`." } } }, "CommsCalendar_TaskCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "list_id", "title" ], "properties": { "list_id": { "type": "string", "format": "uuid", "description": "Task list to add the task to." }, "title": { "type": "string", "minLength": 1, "maxLength": 1024 }, "notes": { "type": "string", "maxLength": 8192, "nullable": true }, "due_at": { "type": "string", "maxLength": 64, "nullable": true, "description": "Due date/time (ISO-8601 or RFC 3339)." }, "ordinal": { "type": "integer", "description": "Ordinal position within the list." } } }, "CommsCalendar_TaskUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 1024 }, "notes": { "type": "string", "maxLength": 8192, "nullable": true }, "due_at": { "type": "string", "maxLength": 64, "nullable": true }, "status": { "type": "string", "enum": [ "needsAction", "completed" ] } } }, "CommsCalendar_TaskMoveRequest": { "type": "object", "additionalProperties": false, "properties": { "list_id": { "type": "string", "format": "uuid", "description": "Destination task list (optional; omit to reorder within the current list)." }, "ordinal": { "type": "integer", "description": "Ordinal position in the destination list." } } }, "CommsCalendar_SyncConnectRequest": { "type": "object", "additionalProperties": false, "required": [ "provider", "provider_account_email", "secret_kind" ], "description": "Register an external calendar sync connection. CalDAV passwords are transmitted over HTTPS and encrypted server-side before storage — never returned in any response.", "properties": { "provider": { "type": "string", "enum": [ "google", "microsoft", "caldav" ], "description": "External calendar provider." }, "provider_account_email": { "type": "string", "maxLength": 320, "description": "Email address for the provider account." }, "secret_kind": { "type": "string", "maxLength": 64, "description": "Type of credential being stored (e.g. `oauth2_refresh`, `app_password`)." }, "encrypted_refresh_token": { "type": "string", "maxLength": 8192, "nullable": true }, "encrypted_access_token": { "type": "string", "maxLength": 8192, "nullable": true }, "token_expires_at": { "type": "string", "maxLength": 64, "nullable": true }, "scopes": { "type": "array", "items": { "type": "string", "maxLength": 512 }, "maxItems": 64 }, "caldav_base_url": { "type": "string", "maxLength": 2048, "nullable": true, "description": "CalDAV principal URL. Required when `provider` is `caldav`." }, "caldav_password": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "CalDAV / app-specific password. Sent in plaintext over HTTPS; encrypted server-side. Required when `provider` is `caldav` and `secret_kind` is `app_password`." }, "create_integration_state": { "type": "boolean" } } }, "CommsCalendar_SyncLinkCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "calendar_id", "connection_id", "external_calendar_id" ], "properties": { "calendar_id": { "type": "string", "format": "uuid", "description": "Backbuild calendar to pair." }, "connection_id": { "type": "string", "format": "uuid", "description": "Sync connection to use." }, "external_calendar_id": { "type": "string", "maxLength": 1024, "description": "Provider-side calendar identifier (opaque string from the provider)." }, "provider": { "type": "string", "enum": [ "google", "microsoft", "caldav" ] }, "sync_direction": { "type": "string", "enum": [ "bidirectional", "pull_only", "push_only" ], "description": "Sync direction (default `bidirectional`)." }, "window_start": { "type": "string", "maxLength": 64, "nullable": true, "description": "Earliest date for back-fill (ISO-8601)." }, "window_end": { "type": "string", "maxLength": 64, "nullable": true } } }, "CommsCalendar_OauthStartResponse": { "type": "object", "description": "Authorization URL for the OAuth flow.", "properties": { "url": { "type": "string", "format": "uri", "description": "Provider authorization URL. Redirect the user here to start the consent flow." }, "state": { "type": "string", "description": "CSRF state token. Pass this back in the callback `state` parameter." } }, "required": [ "url", "state" ] }, "CommsCalendar_AppointmentScheduleSetRequest": { "type": "object", "additionalProperties": false, "required": [ "calendar_id", "title" ], "description": "Create or update an appointment schedule. Omit `id` to create; supply `id` to update. All availability and booking_form details are passed through as JSON objects and validated by the stored procedure.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Omit to create; supply to update in-place." }, "calendar_id": { "type": "string", "format": "uuid", "description": "Calendar that owns the schedule." }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "maxLength": 255, "description": "URL-safe booking page slug (auto-generated from title when omitted)." }, "slot_minutes": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "Duration of each bookable slot in minutes." }, "buffer_minutes": { "type": "integer", "minimum": 0, "maximum": 1440, "description": "Buffer time between appointments." }, "max_per_day": { "type": "integer", "minimum": 1, "maximum": 1000, "nullable": true, "description": "Maximum bookings per day (null = unlimited)." }, "availability": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 50, "description": "Weekly availability windows. Each item specifies a weekday/start/end window." }, "booking_form": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Custom fields to collect from bookers. Validated by the stored procedure." }, "window_start": { "type": "string", "maxLength": 64, "nullable": true, "description": "Earliest bookable date (ISO-8601)." }, "window_end": { "type": "string", "maxLength": 64, "nullable": true, "description": "Latest bookable date (ISO-8601)." }, "conflict_calendar_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Calendars to check for conflicts when determining availability." } } }, "CommsCalendar_BookRequest": { "type": "object", "additionalProperties": false, "required": [ "booker_email", "starts_at" ], "description": "Create a booking. Requires a valid Cloudflare Turnstile token in `cf-turnstile-response` (consumed server-side; never stored or echoed). The server validates slot availability and conflicts before confirming.", "properties": { "booker_email": { "type": "string", "format": "email", "maxLength": 320 }, "starts_at": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Requested slot start (ISO-8601 or RFC 3339)." }, "booker_name": { "type": "string", "maxLength": 255 }, "answers": { "type": "object", "additionalProperties": true, "description": "Answers to custom booking-form fields defined on the schedule." }, "cf-turnstile-response": { "type": "string", "maxLength": 2048, "description": "Cloudflare Turnstile challenge response token. Consumed server-side to prevent abuse; stripped before storage." } } }, "CommsCalendar_BookManageRequest": { "type": "object", "additionalProperties": false, "required": [ "action" ], "description": "Cancel or reschedule an existing booking. Requires a valid Cloudflare Turnstile token in `cf-turnstile-response`. `starts_at` is required when `action` is `reschedule`.", "properties": { "action": { "type": "string", "enum": [ "cancel", "reschedule" ] }, "starts_at": { "type": "string", "maxLength": 64, "description": "New slot start (ISO-8601). Required when `action` is `reschedule`." }, "reason": { "type": "string", "maxLength": 2000, "description": "Optional cancellation or reschedule reason." }, "cf-turnstile-response": { "type": "string", "maxLength": 2048, "description": "Cloudflare Turnstile challenge response token." } } }, "CommsMail_IngestRequest": { "type": "object", "description": "Internal message ingest envelope. Contains server-resolved origin identifiers; no end-user JWT is present on inbound paths.", "additionalProperties": true, "properties": { "direction": { "type": "string", "enum": [ "in", "out", "draft" ] }, "rfc822_message_id": { "type": "string", "maxLength": 998, "nullable": true }, "r2_raw_key": { "type": "string", "minLength": 1, "maxLength": 1024 }, "spam_verdict": { "type": "string", "maxLength": 64, "nullable": true }, "dkim_pass": { "type": "boolean", "nullable": true }, "spf_pass": { "type": "boolean", "nullable": true }, "dmarc_pass": { "type": "boolean", "nullable": true } } }, "CommsMail_IngestResult": { "type": "object", "description": "Result of a successful message ingest.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Catalog message identifier." }, "thread_key": { "type": "string", "nullable": true }, "deduped": { "type": "boolean", "description": "`true` when the message was a duplicate and the existing catalog row was returned." } } }, "CommsMail_CheckpointRequest": { "$ref": "#/components/schemas/CommsMail_MailCheckpointRequest" }, "CommsMail_AuditRequest": { "$ref": "#/components/schemas/CommsMail_MailInternalAuditRequest" }, "CommsMail_MailboxSettings": { "type": "object", "description": "Per-mailbox user settings record.", "properties": { "mailbox_id": { "type": "string", "format": "uuid" }, "reading_pane": { "type": "string", "enum": [ "below", "right", "off" ] }, "density": { "type": "string", "enum": [ "comfortable", "cozy", "compact" ] }, "conversation_view": { "type": "boolean" }, "custom_signature_html": { "type": "string", "nullable": true }, "undo_send_seconds": { "type": "integer", "enum": [ 0, 5, 10, 20, 30 ] }, "mark_read_mode": { "type": "string", "enum": [ "immediate", "after_seconds", "manual" ] }, "mark_read_delay_ms": { "type": "integer", "minimum": 0 }, "updated_at": { "type": "string", "format": "date-time" } } }, "CommsMail_MailboxSettingsUpdateRequest": { "$ref": "#/components/schemas/CommsMail_SettingsPatchRequest" }, "CommsMail_MessageSummary": { "type": "object", "description": "Message header record as returned by the catalog list and get endpoints.", "properties": { "id": { "type": "string", "format": "uuid" }, "mailbox_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "in", "out", "draft" ] }, "subject": { "type": "string", "nullable": true }, "from_addr": { "type": "string", "nullable": true }, "snippet": { "type": "string", "nullable": true }, "thread_key": { "type": "string", "nullable": true }, "size_bytes": { "type": "integer" }, "has_attachments": { "type": "boolean" }, "spam_verdict": { "type": "string", "nullable": true }, "r2_raw_key": { "type": "string", "nullable": true, "description": "Never echoed to the client. Present only in the internal ingest body; omitted from responses." }, "body_raw": { "type": "string", "nullable": true, "description": "Raw RFC 2822 message body (present only in the `GET /messages/{messageId}` response when the object is available in storage)." }, "created_at": { "type": "string", "format": "date-time" } } }, "CommsMail_SendResult": { "type": "object", "description": "Result of a successful send operation.", "required": [ "sent" ], "properties": { "sent": { "type": "boolean", "enum": [ true ] }, "provider": { "type": "string", "nullable": true, "description": "Provider that accepted the message (e.g. `ses`)." }, "messageId": { "type": "string", "nullable": true, "description": "Provider-assigned message identifier." }, "suppressed": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Recipients that were silently suppressed (on the global suppression list)." } } }, "CommsMail_DomainLinkRequest": { "type": "object", "description": "Request body to add a domain to the organization.", "additionalProperties": false, "required": [ "domain" ], "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The domain name to add (e.g. `mail.example.com`)." } } }, "CommsCalendar_BookingManageResponse": { "type": "object", "description": "Booker-safe booking details (internal fields redacted).", "properties": { "id": { "type": "string", "format": "uuid" }, "schedule_title": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "attendee_name": { "type": "string" }, "attendee_email": { "type": "string", "format": "email" }, "status": { "type": "string", "enum": [ "confirmed", "cancelled", "rescheduled" ] }, "notes": { "type": "string", "nullable": true } } }, "CommsOther_OAuthAuthorizeResponse": { "type": "object", "description": "OAuth authorization URL response.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The provider authorization URL to redirect the user to." } } } } }, "CommsOther_GitHubConnectBody": { "type": "object", "description": "GitHub OAuth connect body.", "required": [ "code", "state" ], "properties": { "code": { "type": "string", "description": "OAuth authorization code from GitHub." }, "state": { "type": "string", "description": "CSRF state value from the authorize redirect." } }, "additionalProperties": false }, "CommsOther_OAuthCodeBody": { "type": "object", "description": "Generic OAuth authorization code exchange body.", "required": [ "code", "state" ], "properties": { "code": { "type": "string", "description": "OAuth authorization code from the provider." }, "state": { "type": "string", "description": "CSRF state value from the authorize redirect." } }, "additionalProperties": false }, "CommsOther_GitHubConnectionResponse": { "type": "object", "description": "GitHub connection record.", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Connection record ID." }, "org_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "Connection status (e.g., `active`)." }, "created_at": { "type": "string", "format": "date-time" } } } } }, "CommsOther_GitHubRepoListResponse": { "type": "object", "description": "List of GitHub repositories.", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "repos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "full_name": { "type": "string" }, "private": { "type": "boolean" }, "default_branch": { "type": "string" } } } } } } } }, "CommsOther_RepoAttachBody": { "type": "object", "description": "Attach a GitHub repository.", "required": [ "repoOwner", "repoName", "repoFullName" ], "properties": { "repoOwner": { "type": "string", "minLength": 1, "maxLength": 100, "description": "GitHub owner login." }, "repoName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "GitHub repository name." }, "repoFullName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Full repository name (owner/repo)." }, "defaultBranch": { "type": "string", "maxLength": 100, "default": "main", "description": "Default branch name." }, "isPrivate": { "type": "boolean", "default": false, "description": "Whether the repository is private." }, "githubRepoId": { "type": "integer", "description": "Numeric GitHub repository ID (optional)." } }, "additionalProperties": false }, "CommsOther_NotificationCreateBody": { "type": "object", "description": "Create notification body.", "required": [ "title", "notification_type" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Notification title." }, "body": { "type": "string", "maxLength": 5000, "description": "Optional notification body text." }, "notification_type": { "type": "string", "enum": [ "info", "success", "warning", "error", "action_required" ], "description": "Semantic type of the notification." }, "channel": { "type": "string", "enum": [ "in_app", "email", "push", "slack" ], "description": "Delivery channel." }, "target_user_id": { "type": "string", "format": "uuid", "description": "Target user; defaults to the caller. Creating for another user requires `notification.create` permission." }, "resource_type": { "type": "string", "maxLength": 100, "description": "Type of the linked resource (e.g., `ticket`, `project`)." }, "resource_id": { "type": "string", "format": "uuid", "description": "ID of the linked resource." }, "action_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Call-to-action URL; must be a Backbuild platform domain." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "description": "Delivery priority." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry timestamp; notification auto-hides after this." }, "metadata": { "type": "object", "description": "Bounded JSON metadata (max 32 KB)." } }, "additionalProperties": false }, "CommsOther_NotificationListResponse": { "type": "object", "description": "Notification list response.", "properties": { "data": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/CommsOther_Notification" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "CommsOther_NotificationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CommsOther_Notification" } } }, "CommsOther_Notification": { "type": "object", "description": "A notification record.", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "notification_type": { "type": "string", "enum": [ "info", "success", "warning", "error", "action_required" ] }, "channel": { "type": [ "string", "null" ] }, "is_read": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "action_url": { "type": [ "string", "null" ] } } }, "CommsOther_TicketCreateBody": { "type": "object", "description": "Create ticket body. Request body is capped at 768 KB.", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Ticket title." }, "body": { "type": "string", "maxLength": 100000, "description": "Initial ticket description (up to 100,000 characters)." }, "saas_package_id": { "type": "string", "description": "SaaS package ID (hex UUID format) to scope the ticket." }, "category": { "type": "string", "maxLength": 120, "description": "Category key." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "description": "Ticket priority." }, "source": { "type": "string", "enum": [ "web", "chat", "api" ], "description": "Origin channel." }, "context": { "type": "object", "description": "Arbitrary JSON context object (max 32 KB)." }, "repro": { "type": "object", "description": "Optional structured issue-reproduction recording." } }, "additionalProperties": false }, "CommsOther_TicketUpdateBody": { "type": "object", "description": "Update ticket mutable fields.", "properties": { "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "category": { "type": "string", "maxLength": 120 } }, "additionalProperties": false }, "CommsOther_TicketMessageBody": { "type": "object", "description": "Add a message to a ticket.", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Message body." }, "visibility": { "type": "string", "enum": [ "public", "internal" ], "description": "Message visibility; `internal` is only visible to agents." }, "body_format": { "type": "string", "enum": [ "text", "latex" ], "description": "Formatting hint for the message body." }, "attachments": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "kind", "id", "name" ], "properties": { "kind": { "type": "string", "enum": [ "doc", "sheet" ], "description": "Attachment type." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Attachment ID." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name." }, "project_id": { "type": "string", "format": "uuid", "description": "Optional project scope." } }, "additionalProperties": false } } }, "additionalProperties": false }, "CommsOther_TicketResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "triage", "in_progress", "waiting_customer", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "category": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "CommsOther_TicketListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/CommsOther_TicketResponse" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "CommsOther_RoutingRuleBody": { "type": "object", "description": "Ticket routing rule.", "required": [ "category_key", "assignee_kind" ], "properties": { "category_key": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Category to match." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_kind": { "type": "string", "enum": [ "human", "agent", "virtual_worker" ] }, "assignee_id": { "type": "string", "format": "uuid" }, "is_enabled": { "type": "boolean", "default": true } }, "additionalProperties": false }, "CommsOther_TicketCategoryBody": { "type": "object", "description": "Ticket category.", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 }, "parent_key": { "type": "string", "maxLength": 120 } }, "additionalProperties": false }, "CommsOther_CannedResponseBody": { "type": "object", "description": "Canned response.", "required": [ "name", "body" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "body": { "type": "string", "minLength": 1, "maxLength": 100000 }, "category_key": { "type": "string", "maxLength": 120 } }, "additionalProperties": false }, "CommsOther_HelpdeskCategorySetBody": { "type": "object", "description": "Helpdesk category upsert body.", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Category key." }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Category display label." }, "saas_package_id": { "type": "string", "description": "SaaS package scope (hex UUID)." }, "project_id": { "type": "string", "format": "uuid", "description": "Project scope." }, "sort_order": { "type": "integer", "minimum": 0, "description": "Sort order." }, "is_active": { "type": "boolean" }, "overrides_key": { "type": "string", "maxLength": 64, "description": "Parent category key this entry overrides." }, "is_shadow_disabled": { "type": "boolean" }, "auto_dispatch": { "type": "boolean" }, "dispatch_policy": { "type": "object", "description": "Dispatch policy configuration." } }, "additionalProperties": false }, "CommsOther_HelpdeskWorkerAssignBody": { "type": "object", "description": "Assign virtual worker to a helpdesk category.", "required": [ "category_key", "virtual_worker_id" ], "properties": { "category_key": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Category to assign the worker to." }, "virtual_worker_id": { "type": "string", "format": "uuid", "description": "Virtual worker ID." }, "saas_package_id": { "type": "string", "description": "Optional SaaS package scope (hex UUID)." }, "project_id": { "type": "string", "format": "uuid", "description": "Optional project scope." }, "priority": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Assignment priority (lower = higher priority)." }, "is_enabled": { "type": "boolean", "default": true } }, "additionalProperties": false }, "CommsOther_HelpdeskAutoDispatchBody": { "type": "object", "description": "Set auto-dispatch for a helpdesk category.", "required": [ "category_key", "auto_dispatch" ], "properties": { "category_key": { "type": "string", "minLength": 1, "maxLength": 64 }, "auto_dispatch": { "type": "boolean" }, "saas_package_id": { "type": "string", "description": "Optional SaaS package scope (hex UUID)." }, "project_id": { "type": "string", "format": "uuid" }, "dispatch_policy": { "type": "object" } }, "additionalProperties": false }, "CommsOther_HelpdeskPoolPolicyBody": { "type": "object", "description": "Container pool policy.", "properties": { "max_slots_per_container": { "type": "integer", "minimum": 1, "maximum": 16 }, "max_containers_per_worker": { "type": "integer", "minimum": 1, "maximum": 64 }, "max_worker_containers_per_org": { "type": "integer", "minimum": 1 }, "idle_container_grace_seconds": { "type": "integer", "minimum": 0 }, "pool_floor_per_worker": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "CommsOther_ThemeMutationBody": { "type": "object", "description": "Create or update a theme. Must include either `theme_data` or all three of `colors`, `typography`, and `layout`.", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Theme display name." }, "description": { "type": "string", "maxLength": 2000 }, "is_dark": { "type": "boolean", "default": false }, "is_default": { "type": "boolean", "default": false }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] }, "colors": { "type": "object", "description": "Color token map." }, "typography": { "type": "object", "description": "Typography token map." }, "layout": { "type": "object", "description": "Layout token map." }, "theme_data": { "type": "object", "description": "Complete theme data object (alternative to colors+typography+layout).", "additionalProperties": false } }, "additionalProperties": false }, "CommsOther_ThemeResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] }, "is_dark": { "type": "boolean" }, "is_default": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "CommsOther_ThemeListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "themes": { "type": "array", "items": { "$ref": "#/components/schemas/CommsOther_ThemeResponse" } } } } } }, "CommsOther_SecretsKdfParams": { "type": "object", "description": "Argon2 KDF parameters. Must meet the platform floor: `mem_kib` ≥ 19456, `iters` ≥ 2.", "required": [ "mem_kib", "iters" ], "properties": { "mem_kib": { "type": "integer", "minimum": 19456, "description": "Memory cost in KiB." }, "iters": { "type": "integer", "minimum": 2, "description": "Number of iterations." }, "parallelism": { "type": "integer", "description": "Parallelism factor." } } }, "CommsOther_SecretsInitBody": { "type": "object", "description": "Initialize secrets vault identity.", "required": [ "sealedPrivBlob", "saltUser", "kdf", "pubKey" ], "properties": { "sealedPrivBlob": { "type": "string", "description": "Encrypted private-key blob." }, "saltUser": { "type": "string", "description": "User-specific KDF salt." }, "kdf": { "$ref": "#/components/schemas/CommsOther_SecretsKdfParams" }, "pubKey": { "type": "string", "description": "Public key for vault key wrapping." } }, "additionalProperties": false }, "CommsOther_SecretsUnlockBody": { "type": "object", "description": "Unlock the secrets vault.", "required": [ "sealedPrivBlob", "saltUser", "kdf" ], "properties": { "sealedPrivBlob": { "type": "string", "description": "Encrypted private-key blob." }, "saltUser": { "type": "string", "description": "User-specific KDF salt." }, "kdf": { "$ref": "#/components/schemas/CommsOther_SecretsKdfParams" } }, "additionalProperties": false }, "CommsOther_SecretsUnlockResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sessionToken": { "type": "string", "description": "Encrypted secrets session token." }, "expiresAt": { "type": "string", "format": "date-time" } } } } }, "CommsOther_SecretsIdentityResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sealedPrivBlob": { "type": "string" }, "saltUser": { "type": "string" }, "kdf": { "$ref": "#/components/schemas/CommsOther_SecretsKdfParams" }, "pubKey": { "type": "string" } } } } }, "CommsOther_SecretsMasterPasswordBody": { "type": "object", "description": "Change master password (re-wraps sealed private key).", "required": [ "sealedPrivBlob", "saltUser", "kdf" ], "properties": { "sealedPrivBlob": { "type": "string" }, "saltUser": { "type": "string" }, "kdf": { "$ref": "#/components/schemas/CommsOther_SecretsKdfParams" } }, "additionalProperties": false }, "CommsOther_VaultCreateBody": { "type": "object", "description": "Create a secrets vault.", "required": [ "name", "type", "sealedVaultKey" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "maxLength": 2000 }, "type": { "type": "string", "enum": [ "personal", "team", "virtual_worker" ], "description": "Vault type. `virtual_worker` vaults carry a server-escrow key wrap." }, "sealedVaultKey": { "type": "string", "description": "Vault key sealed to the creator's public key." }, "serverEscrowWrap": { "type": "string", "description": "Vault key wrapped to the server escrow KEM public key (required for `virtual_worker` type)." } }, "additionalProperties": false }, "CommsOther_VaultResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "role": { "type": "string", "description": "Caller's role in this vault." } } } } }, "CommsOther_VaultListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "vaults": { "type": "array", "items": { "$ref": "#/components/schemas/CommsOther_VaultResponse" } } } } } }, "CommsOther_VaultItemCreateBody": { "type": "object", "description": "Create or update a vault item.", "required": [ "name", "type", "encContent", "itemSalt" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Item display name." }, "type": { "type": "string", "description": "Item type (e.g., `login`, `note`, `api_key`)." }, "encContent": { "type": "string", "description": "Encrypted item content blob (opaque to server)." }, "itemSalt": { "type": "string", "description": "Per-item salt for AAD derivation." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional searchable tags." } }, "additionalProperties": false }, "CommsOther_SecretsAdminResetBody": { "type": "object", "description": "Admin recovery reset body.", "required": [ "sealedPrivBlob", "saltUser", "kdf" ], "properties": { "sealedPrivBlob": { "type": "string" }, "saltUser": { "type": "string" }, "kdf": { "$ref": "#/components/schemas/CommsOther_SecretsKdfParams" } }, "additionalProperties": false }, "CommsOther_SyncBindingUpsertBody": { "type": "object", "description": "Create or update a secret sync binding.", "required": [ "vaultId", "itemId", "fieldPath", "provider", "connectionId", "locator", "destSecretName" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Existing binding ID for update; omit to create." }, "vaultId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "fieldPath": { "type": "string", "minLength": 1, "description": "Field path within the vault item." }, "provider": { "type": "string", "description": "Provider key (e.g., `cloudflare`)." }, "connectionId": { "type": "string", "format": "uuid", "description": "Must be the caller's own active connection for this provider." }, "locator": { "type": "object", "description": "Provider-specific destination locator (e.g., Worker script name)." }, "destSecretName": { "type": "string", "minLength": 1, "description": "Destination secret name at the provider." }, "generatable": { "type": "boolean" }, "overlapEnabled": { "type": "boolean" }, "rotateEverySeconds": { "type": "integer" } }, "additionalProperties": false }, "CommsOther_SyncPushBody": { "type": "object", "description": "Push client-decrypted secret values to provider destinations.", "required": [ "vaultId", "itemId", "syncs" ], "properties": { "vaultId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "syncs": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "bindingId", "value" ], "properties": { "bindingId": { "type": "string", "format": "uuid" }, "value": { "type": "string", "maxLength": 100000, "description": "Client-decrypted field value (write-only; never logged or returned)." } }, "additionalProperties": false } } }, "additionalProperties": false }, "CommsOther_RdpRegisterDeviceBody": { "type": "object", "description": "Register an RDP device with a post-quantum identity bundle.", "required": [ "device_identifier", "device_name", "os_family", "os_version", "app_version", "pq_kem_alg_id", "pq_sig_alg_id", "pq_identity_bundle" ], "properties": { "device_identifier": { "type": "string", "minLength": 1, "maxLength": 256 }, "device_name": { "type": "string", "minLength": 1, "maxLength": 256 }, "os_family": { "type": "string", "enum": [ "windows", "macos", "linux", "ios", "android", "web", "other" ] }, "os_version": { "type": "string", "minLength": 1, "maxLength": 64 }, "app_version": { "type": "string", "minLength": 1, "maxLength": 64 }, "capabilities": { "type": "object", "description": "Optional device capabilities (max 8 KB)." }, "pq_kem_alg_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Post-quantum KEM algorithm identifier." }, "pq_sig_alg_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Post-quantum signature algorithm identifier." }, "pq_identity_bundle": { "type": "object", "description": "Post-quantum identity bundle (max 32 KB)." } }, "additionalProperties": false }, "CommsOther_RdpTrustDeviceBody": { "type": "object", "description": "Grant viewer trust to a host device.", "required": [ "viewer_device_id", "expected_pubkey_hash", "permissions" ], "properties": { "viewer_device_id": { "type": "string", "format": "uuid" }, "expected_pubkey_hash": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Hash of the viewer's expected public key." }, "permissions": { "type": "object", "description": "Permission set granted to the viewer (max 4 KB)." } }, "additionalProperties": false }, "CommsOther_RdpSessionAuthorizeBody": { "type": "object", "description": "Authorize an RDP session.", "required": [ "host_device_id", "viewer_device_id", "viewer_user_id", "viewer_pubkey_hash", "signaling_session_id", "kem_alg_negotiated", "sig_alg_negotiated", "aead_alg_negotiated" ], "properties": { "host_device_id": { "type": "string", "format": "uuid" }, "viewer_device_id": { "type": "string", "format": "uuid" }, "viewer_user_id": { "type": "string", "format": "uuid" }, "viewer_pubkey_hash": { "type": "string", "minLength": 1, "maxLength": 256 }, "signaling_session_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "kem_alg_negotiated": { "type": "string", "minLength": 1, "maxLength": 64 }, "sig_alg_negotiated": { "type": "string", "minLength": 1, "maxLength": 64 }, "aead_alg_negotiated": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "CommsOther_RdpSessionEndBody": { "type": "object", "description": "End an RDP session.", "required": [ "end_reason" ], "properties": { "end_reason": { "type": "string", "minLength": 1, "maxLength": 128 }, "ice_connection_type": { "type": "string", "maxLength": 32 }, "total_bytes_in": { "type": "integer", "minimum": 0 }, "total_bytes_out": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "CommsOther_RdpAuditExportBody": { "type": "object", "description": "Audit log export filter.", "properties": { "max_rows": { "type": "integer", "minimum": 1, "maximum": 5000, "description": "Maximum rows to export (default 5000)." }, "action": { "type": "string", "maxLength": 128 }, "device_id": { "type": "string", "format": "uuid" }, "actor_user_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "CommsOther_RdpRetentionSweepBody": { "type": "object", "description": "Manual RDP retention sweep parameters.", "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Scope sweep to a single organization." }, "session_days": { "type": "integer", "minimum": 1, "maximum": 3650 }, "audit_days": { "type": "integer", "minimum": 1, "maximum": 3650 }, "crypto_audit_days": { "type": "integer", "minimum": 1, "maximum": 3650 }, "dry_run": { "type": "boolean", "description": "If true, report what would be deleted without deleting." } }, "additionalProperties": false }, "Containers_Jwks": { "type": "object", "description": "JSON Web Key Set containing the Ed25519 public key used to verify container tokens.", "required": [ "keys" ], "properties": { "keys": { "type": "array", "description": "Array of JWK entries. Zero or one entry (EdDSA, kty=OKP, crv=Ed25519).", "items": { "type": "object", "description": "An Ed25519 JWK (public key only — `d` is never present).", "properties": { "kty": { "type": "string", "enum": [ "OKP" ], "description": "Key type." }, "crv": { "type": "string", "enum": [ "Ed25519" ], "description": "Curve." }, "x": { "type": "string", "description": "Base64url-encoded public key." }, "kid": { "type": "string", "description": "Key identifier." }, "alg": { "type": "string", "enum": [ "EdDSA" ], "description": "Algorithm." }, "use": { "type": "string", "description": "Key use (e.g. `sig`)." } } } } } }, "Containers_Backend": { "type": "string", "enum": [ "cloudflare", "contabo", "aws", "gcp", "azure", "oracle" ], "description": "Supported container backend providers." }, "Containers_ExecutionPolicy": { "type": "object", "description": "Organization-wide container execution policy.", "properties": { "containers_enabled": { "type": [ "boolean", "null" ], "description": "Master on/off toggle. When false, container provisioning is blocked for every member of the org and environment." }, "allowed_backends": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Containers_Backend" }, "maxItems": 6, "description": "Backends members may use. null = all configured backends." }, "allowed_sizes": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 50, "description": "Size keys members may request. null = all available sizes." }, "default_backend": { "$ref": "#/components/schemas/Containers_Backend", "description": "Backend used when the caller does not specify one." }, "default_size": { "type": [ "string", "null" ], "maxLength": 64, "description": "Size key used when the caller does not specify one." }, "user_selectable": { "type": [ "boolean", "null" ], "description": "Whether members may choose a backend/size other than the defaults." }, "idle_grace_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 86400, "description": "How long an idle container waits before the reap timer starts." }, "idle_reap_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 86400, "description": "How long after idle grace expires before the container is stopped." }, "idle_billing_mode": { "type": [ "string", "null" ], "enum": [ "stop_at_idle", "bill_until_reap" ], "description": "Whether billing stops at idle or at reap." }, "max_concurrent": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000, "description": "Maximum simultaneous sessions across the org. 0 = unlimited." }, "data_residency_regions": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 50, "description": "Allowed data-residency region identifiers. null = no restriction." } } }, "Containers_SetPolicyRequest": { "type": "object", "additionalProperties": false, "description": "Update request for the org-wide execution policy. All fields optional; absent fields are unchanged.", "properties": { "containers_enabled": { "type": "boolean", "description": "Master on/off toggle." }, "allowed_backends": { "type": "array", "items": { "$ref": "#/components/schemas/Containers_Backend" }, "maxItems": 6 }, "allowed_sizes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50 }, "default_backend": { "$ref": "#/components/schemas/Containers_Backend" }, "default_size": { "type": "string", "minLength": 1, "maxLength": 64 }, "user_selectable": { "type": "boolean" }, "idle_grace_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "idle_reap_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "idle_billing_mode": { "type": "string", "enum": [ "stop_at_idle", "bill_until_reap" ] }, "max_concurrent": { "type": "integer", "minimum": 0, "maximum": 1000 }, "data_residency_regions": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50 } } }, "Containers_ProjectPolicy": { "type": "object", "description": "Per-project container execution policy override. Null fields mean the project inherits the org policy.", "properties": { "containers_enabled": { "type": [ "boolean", "null" ], "description": "null = inherit org toggle." }, "allowed_backends": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Containers_Backend" }, "maxItems": 6, "description": "null = inherit org allow-set." }, "allowed_sizes": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 50, "description": "null = inherit org allow-set." } } }, "Containers_SetProjectPolicyRequest": { "type": "object", "additionalProperties": false, "description": "Update request for a per-project policy override.", "properties": { "clear": { "type": "boolean", "description": "When true, deletes the override so the project falls back to the org policy." }, "containers_enabled": { "type": [ "boolean", "null" ], "description": "null = inherit org toggle." }, "allowed_backends": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Containers_Backend" }, "maxItems": 6 }, "allowed_sizes": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50 } } }, "Containers_SizeCatalogEntry": { "type": "object", "description": "A container size/backend catalog entry.", "properties": { "size_key": { "type": "string", "description": "Canonical size identifier (e.g. `standard-1`)." }, "backend": { "$ref": "#/components/schemas/Containers_Backend" }, "display_name": { "type": "string", "description": "Human-readable display name." }, "vcpus": { "type": "number", "description": "Virtual CPU count." }, "memory_gb": { "type": "number", "description": "RAM in gigabytes." }, "credit_cost_per_hour": { "type": "integer", "description": "Platform credit cost per hour." }, "available": { "type": "boolean", "description": "Whether this combination is currently available in the org's policy." } } }, "Containers_Session": { "type": "object", "description": "A container session record.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Session identifier." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "env_id": { "type": "string", "format": "uuid", "description": "Active environment." }, "user_id": { "type": "string", "format": "uuid", "description": "User who owns this session." }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project binding, if any." }, "backend": { "$ref": "#/components/schemas/Containers_Backend" }, "size_key": { "type": "string", "description": "Size key used." }, "kind": { "type": "string", "enum": [ "ai_assistant", "virtual_worker" ], "description": "Session kind." }, "status": { "type": "string", "enum": [ "provisioning", "running", "idle", "stopped", "teardown", "error" ], "description": "Current lifecycle status." }, "endpoint": { "type": [ "string", "null" ], "description": "Public gateway URL when the ingress domain is configured. null otherwise." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Containers_SpinUpRequest": { "type": "object", "additionalProperties": false, "description": "Request body for spinning up a new container session. All fields are optional.", "properties": { "backend": { "$ref": "#/components/schemas/Containers_Backend", "description": "Backend to provision on. Defaults to the org/project policy default." }, "size_key": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Size to provision. Defaults to the org/project policy default." }, "region": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Preferred region (backend-specific, advisory)." }, "kind": { "type": "string", "enum": [ "ai_assistant", "virtual_worker" ], "description": "Session kind. Defaults to `ai_assistant`." }, "project_id": { "type": "string", "format": "uuid", "description": "Optional project to bind this session to. Applies per-project policy overrides and binds the session for audit and billing attribution." } } }, "Containers_ConnectResponse": { "type": "object", "description": "Connect ticket, UI token, and gateway endpoint.", "required": [ "ticket", "connect_token", "connect_token_ttl_seconds", "session_id" ], "properties": { "ticket": { "type": "string", "description": "Single-use, short-TTL opaque ticket redeemed by the in-container gateway on the WebSocket upgrade." }, "connect_token": { "type": "string", "description": "Short-TTL Ed25519 UI connect token (JWT) presented to the in-container gateway to authorize the UI connection." }, "connect_token_ttl_seconds": { "type": "integer", "description": "Remaining TTL of the connect token in seconds." }, "session_id": { "type": "string", "format": "uuid", "description": "The session this connect pair was issued for." }, "endpoint": { "type": [ "string", "null" ], "description": "Public gateway URL (e.g. `https://containers.example.com/s//`). Null when the ingress domain is not configured." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Ticket expiry timestamp." } } }, "Containers_SaasConfig": { "type": "object", "description": "Container configuration for a SaaS package.", "properties": { "containers_enabled": { "type": "boolean", "description": "Whether containers are enabled for this package's subscribers." }, "allowed_backends": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Containers_Backend" }, "maxItems": 6 }, "allowed_sizes": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 50 } } }, "Containers_SetSaasConfigRequest": { "type": "object", "additionalProperties": false, "description": "Update request for a SaaS package's container configuration.", "required": [ "containers_enabled" ], "properties": { "containers_enabled": { "type": "boolean" }, "allowed_backends": { "type": "array", "items": { "$ref": "#/components/schemas/Containers_Backend" }, "maxItems": 6 }, "allowed_sizes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50 } } }, "Containers_SetResalePriceRequest": { "type": "object", "additionalProperties": false, "description": "Set the per-hour resale credit cost for a backend + size combination.", "required": [ "backend", "size_key", "resale_credit_cost_per_hour" ], "properties": { "backend": { "$ref": "#/components/schemas/Containers_Backend" }, "size_key": { "type": "string", "minLength": 1, "maxLength": 64 }, "resale_credit_cost_per_hour": { "type": "integer", "minimum": 0, "description": "Per-hour credit cost charged to the package's subscribers for this backend + size." } } }, "Containers_CodeApiConfig": { "type": "object", "description": "Code-API configuration returned to a CF sandbox container. Contains only the bridge URL and a short-TTL bridge token.", "required": [ "bridge_url", "token" ], "properties": { "bridge_url": { "type": "string", "description": "URL the sandbox agent uses to reach the tool-bridge." }, "token": { "type": "string", "description": "Short-TTL bridge token. Never the secret reference or refresh credential." } } }, "Containers_SecretExchangeResponse": { "type": "object", "description": "Session credentials returned by the one-time secret-exchange endpoint.", "required": [ "session_id", "data_token" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Session identifier." }, "data_token": { "type": "string", "description": "Short-TTL Ed25519 data token (JWT) for authenticating data-plane calls." }, "connect_token": { "type": "string", "description": "Short-TTL Ed25519 connect token (JWT) for authorizing UI connections." }, "refresh_cred": { "type": [ "string", "null" ], "description": "Refresh credential held by the gateway to renew the data token. Absent for sessions that do not support refresh." }, "r2_home_creds": { "type": [ "object", "null" ], "description": "R2 temporary credentials for the session's home bucket. Absent when not provisioned.", "additionalProperties": true }, "bridge_token": { "type": [ "string", "null" ], "description": "Short-TTL bridge token for the code-API tool-bridge. Present only when the session enables the code-API." } } }, "Containers_TicketRedeemRequest": { "type": "object", "description": "One-time UI connect ticket to redeem.", "required": [ "ticket" ], "properties": { "ticket": { "type": "string", "description": "Opaque single-use ticket previously issued by `POST /v1/containers/{sessionId}/connect`." } } }, "Containers_TicketRedeemResponse": { "type": "object", "description": "Bound session and user identity returned after a successful ticket redeem.", "required": [ "session_id", "user_id" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "The container session this ticket was bound to." }, "user_id": { "type": "string", "format": "uuid", "description": "The user the ticket was issued for." } } }, "Containers_TokenRefreshResponse": { "type": "object", "description": "A fresh short-TTL data token.", "required": [ "data_token", "expires_in" ], "properties": { "data_token": { "type": "string", "description": "Freshly minted Ed25519 data token (JWT). Bound to the same user/session/org/env/scope as the original." }, "expires_in": { "type": "integer", "description": "Token TTL in seconds." } } }, "Containers_ContainerIdentity": { "type": "object", "description": "Resolved identity of an in-container agent derived from its verified data token.", "required": [ "user_id", "org_id", "env_id", "session_id", "scope" ], "properties": { "user_id": { "type": "string", "format": "uuid", "description": "User the session was provisioned for." }, "org_id": { "type": "string", "format": "uuid", "description": "Organization." }, "env_id": { "type": "string", "format": "uuid", "description": "Active environment." }, "session_id": { "type": "string", "format": "uuid", "description": "Container session." }, "scope": { "type": "array", "items": { "type": "string" }, "description": "Least-privilege delegated scope set minted at provisioning time." } } }, "Containers_SessionLogAppendResponse": { "type": "object", "description": "Result of a successful session-log chunk append.", "required": [ "chunk_key", "event_count", "bytes_written" ], "properties": { "chunk_key": { "type": "string", "description": "The R2 object key the chunk was stored under." }, "event_count": { "type": "integer", "description": "Number of events in this chunk." }, "bytes_written": { "type": "integer", "description": "Bytes persisted to R2." }, "decoded_request_bytes": { "type": "integer", "description": "Original body size in bytes." } } }, "Containers_SessionLogReadResponse": { "type": "object", "description": "Session log chunks concatenated from R2.", "required": [ "session_id", "chunk_count", "chunk_keys", "ndjson", "truncated" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "The session whose log was read." }, "chunk_count": { "type": "integer", "description": "Number of chunks concatenated." }, "chunk_keys": { "type": "array", "items": { "type": "string" }, "description": "R2 keys of the concatenated chunks in order." }, "ndjson": { "type": "string", "description": "Concatenated NDJSON content of all returned chunks." }, "truncated": { "type": "boolean", "description": "True when more chunks remain beyond the page/byte cap; re-read from the last chunk key." } } }, "Containers_TerminalActivityBatch": { "type": "object", "description": "A bounded batch of already-redacted terminal activity events.", "required": [ "containerSessionId", "terminalId", "seqFrom", "seqTo", "events" ], "properties": { "containerSessionId": { "type": "string", "format": "uuid", "description": "Must match the principal's own session id." }, "terminalId": { "type": "string", "description": "Terminal identifier within the session." }, "seqFrom": { "type": "integer", "minimum": 0, "description": "First event sequence number in this batch." }, "seqTo": { "type": "integer", "minimum": 0, "description": "Last event sequence number in this batch." }, "events": { "type": "array", "description": "Array of already-redacted `ActivityEvent` objects.", "items": { "type": "object", "additionalProperties": true } }, "redactionClasses": { "type": "array", "items": { "type": "string" }, "description": "Redaction classes applied to this batch." }, "cols": { "type": "integer", "description": "Terminal column count." }, "rows": { "type": "integer", "description": "Terminal row count." }, "emulation": { "type": "string", "description": "Terminal emulation (e.g. `xterm-256color`)." } } }, "Containers_AgentTask": { "type": "object", "description": "The next pending agent task dispatched to this Virtual Worker session.", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Task identifier." }, "virtual_worker_id": { "type": "string", "format": "uuid", "description": "The Virtual Worker this task belongs to." }, "source": { "type": "string", "description": "Task source (e.g. `ticket`, `chat`, `scheduled`)." }, "ref_kind": { "type": [ "string", "null" ], "description": "Kind of the linked entity (if any)." }, "ref_id": { "type": [ "string", "null" ], "description": "ID of the linked entity (if any)." }, "payload": { "description": "Task-specific payload." }, "created_at": { "type": "string", "format": "date-time" } } }, "Containers_AgentTaskCompleteRequest": { "type": "object", "description": "Task completion report from the in-pod runner.", "required": [ "virtual_worker_id", "worker_task_id" ], "properties": { "virtual_worker_id": { "type": "string", "format": "uuid", "description": "The Virtual Worker the completed task belongs to. Must match the session's bound worker." }, "worker_task_id": { "type": "string", "format": "uuid", "description": "The task identifier returned by the task pull. Server re-validates ownership." }, "task_status": { "type": "string", "description": "Final task status to record (e.g. `completed`, `failed`)." }, "last_error": { "type": [ "string", "null" ], "description": "Error message when `task_status` is `failed`." }, "result": { "description": "Structured task result payload." }, "messages": { "type": "array", "description": "Conversation messages to record with the turn.", "items": { "type": "object", "additionalProperties": true } } } }, "Containers_Tool": { "type": "object", "description": "A registered callable tool.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tool ID." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "name": { "type": "string", "description": "Unique tool name within the org." }, "description": { "type": "string", "description": "Human-readable description of what this tool does." }, "tool_type": { "type": "string", "description": "Tool runtime type (e.g. `http`, `mcp`, `builtin`)." }, "schema_def": { "type": "object", "additionalProperties": true, "description": "JSON Schema for the tool's argument payload." }, "endpoint_url": { "type": [ "string", "null" ], "description": "HTTP endpoint URL (for `http` type tools). Validated to prevent SSRF — private IP ranges are rejected." }, "auth_config": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Auth configuration for the endpoint (structure is tool-type-specific)." }, "status": { "type": "string", "enum": [ "active", "inactive", "draft" ], "description": "Tool availability status." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Containers_ToolCreateRequest": { "type": "object", "description": "Request body to create a new tool.", "required": [ "name", "description", "tool_type", "schema_def" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique tool name within the org." }, "description": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Human-readable description." }, "tool_type": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Tool runtime type." }, "schema_def": { "type": "object", "additionalProperties": true, "description": "JSON Schema for the argument payload." }, "endpoint_url": { "type": "string", "format": "uri", "description": "HTTP endpoint URL (for `http` type). Validated to prevent SSRF." }, "auth_config": { "type": "object", "additionalProperties": true, "description": "Endpoint auth configuration." }, "status": { "type": "string", "enum": [ "active", "inactive", "draft" ], "description": "Initial status. Defaults to `draft`." } } }, "Containers_ToolUpdateRequest": { "type": "object", "description": "Request body to update an existing tool. At least one field must be provided.", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": "string", "minLength": 1, "maxLength": 2048 }, "tool_type": { "type": "string", "minLength": 1, "maxLength": 64 }, "schema_def": { "type": "object", "additionalProperties": true }, "endpoint_url": { "type": [ "string", "null" ], "format": "uri", "description": "Updated endpoint URL. Validated to prevent SSRF." }, "auth_config": { "type": [ "object", "null" ], "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "inactive", "draft" ] } } }, "Containers_VirtualWorker": { "type": "object", "description": "A Virtual Worker — an autonomous AI agent permanently bound to an org and optionally linked to a Claude Max account.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Worker ID." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "display_name": { "type": "string", "description": "Human-readable worker name." }, "job_role": { "type": [ "string", "null" ], "description": "Semantic role label (e.g. `Support Agent`, `Code Reviewer`)." }, "role_key": { "type": [ "string", "null" ], "maxLength": 64, "description": "Machine-readable role key." }, "container_size": { "type": [ "string", "null" ], "maxLength": 64, "description": "Preferred container size for this worker's sessions." }, "execution_mode": { "type": [ "string", "null" ], "description": "Execution mode (`synchronous` or `async`)." }, "manager_kind": { "type": [ "string", "null" ], "description": "Manager type (e.g. `user`, `worker`)." }, "manager_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Manager ID when `manager_kind` is set." }, "timezone": { "type": [ "string", "null" ], "maxLength": 64, "description": "IANA timezone identifier for shift scheduling." }, "system_prompt": { "type": [ "string", "null" ], "description": "Worker-level system prompt prepended to every conversation." }, "status": { "type": "string", "enum": [ "active", "paused", "retired" ], "description": "Current worker status." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Containers_VirtualWorkerCreateRequest": { "type": "object", "description": "Request body to create a new Virtual Worker.", "required": [ "display_name" ], "additionalProperties": false, "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable worker name." }, "job_role": { "type": "string", "maxLength": 128, "description": "Semantic role label." }, "role_key": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Machine-readable role key." }, "container_size": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Preferred container size." }, "execution_mode": { "type": "string", "enum": [ "synchronous", "async" ], "description": "Execution mode." }, "manager_kind": { "type": "string", "maxLength": 64, "description": "Manager type." }, "manager_id": { "type": "string", "format": "uuid", "description": "Manager ID." }, "timezone": { "type": "string", "maxLength": 64, "description": "IANA timezone identifier." }, "system_prompt": { "type": "string", "maxLength": 65536, "description": "Worker-level system prompt." } } }, "FilesDocs_FileChunk": { "type": "object", "description": "A chunk of a file read from the confined source repository.", "required": [ "sha256", "totalSize", "bytesBase64", "eof" ], "additionalProperties": false, "properties": { "sha256": { "type": "string", "description": "SHA-256 hex digest of the complete file." }, "totalSize": { "type": "integer", "description": "Total file size in bytes." }, "bytesBase64": { "type": "string", "description": "Base64-encoded bytes of this chunk." }, "eof": { "type": "boolean", "description": "`true` if this is the final chunk." } } }, "FilesDocs_WriteFileRequest": { "type": "object", "description": "Request body for a CAS write to the confined source repository.", "required": [ "contentBase64", "ifMatchSha256" ], "additionalProperties": false, "properties": { "contentBase64": { "type": "string", "maxLength": 22369622, "description": "Base64-encoded file content. Maximum 16 MB (encoded)." }, "ifMatchSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hex digest of the current HEAD. The write is rejected with `CONFLICT` if it doesn't match." } } }, "FilesDocs_WriteFileResult": { "type": "object", "description": "Result of a successful CAS write.", "required": [ "newSha256", "newSize" ], "additionalProperties": false, "properties": { "newSha256": { "type": "string", "description": "SHA-256 hex digest of the newly written content." }, "newSize": { "type": "integer", "description": "Size in bytes of the newly written file." } } }, "FilesDocs_Document": { "type": "object", "description": "A document record in the document library.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document ID." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organisation ID." }, "project_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Project the document belongs to, if any." }, "parent_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Parent folder ID, if any." }, "title": { "type": "string", "description": "Document title." }, "content": { "type": "string", "nullable": true, "description": "Document body content." }, "content_type": { "type": "string", "description": "MIME type or editor-specific content type identifier." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags." }, "metadata": { "type": "object", "description": "Arbitrary JSON metadata." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FilesDocs_CreateDocumentRequest": { "type": "object", "description": "Request body for creating a new document.", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Document title." }, "content": { "type": "string", "description": "Initial document content." }, "content_type": { "type": "string", "description": "MIME type or editor-specific content type identifier." }, "project_id": { "type": "string", "format": "uuid", "description": "Project to associate the document with." }, "parent_id": { "type": "string", "format": "uuid", "description": "Parent folder ID." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags." }, "metadata": { "type": "object", "description": "Arbitrary JSON metadata. Subject to size bounds." } } }, "FilesDocs_UpdateDocumentRequest": { "type": "object", "description": "Request body for updating an existing document. All fields are optional.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "New document title." }, "content": { "type": "string", "description": "New document content." }, "content_type": { "type": "string", "description": "New content type." }, "project_id": { "type": "string", "format": "uuid", "description": "Reassign to a different project." }, "parent_id": { "type": "string", "format": "uuid", "description": "Reassign to a different parent folder." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Replace the tag list." }, "metadata": { "type": "object", "description": "Replace the metadata object." } } }, "FilesDocs_ExplorerRoot": { "type": "object", "description": "A root entry in the document explorer tree.", "properties": { "id": { "type": "string", "description": "Root identifier (e.g. `personal`, `organization`)." }, "label": { "type": "string", "description": "Human-readable label." }, "kind": { "type": "string", "enum": [ "artifacts", "personal", "department", "organization", "projects", "shared", "sharing" ], "description": "Root category." } } }, "FilesDocs_ExplorerFolder": { "type": "object", "description": "A virtual folder in the document explorer.", "properties": { "id": { "type": "string", "format": "uuid" }, "root_id": { "type": "string", "enum": [ "artifacts", "personal", "department", "organization", "projects", "shared", "sharing" ], "description": "Explorer root this folder belongs to." }, "path": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of path segments from root to this folder." }, "project_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Associated project, if any." }, "created_at": { "type": "string", "format": "date-time" } } }, "FilesDocs_CreateFolderRequest": { "type": "object", "description": "Request body for creating a new document folder.", "required": [ "root_id", "path" ], "additionalProperties": false, "properties": { "root_id": { "type": "string", "enum": [ "artifacts", "personal", "department", "organization", "projects", "shared", "sharing" ], "description": "Explorer root the folder belongs to." }, "path": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "type": "string" }, "description": "Ordered list of path segments (at least one, at most 24)." }, "project_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Project to associate the folder with." } } }, "FilesDocs_PublishDocumentRequest": { "type": "object", "description": "Request body for the document publish API.", "required": [ "library", "category", "folder_path", "title", "source_path" ], "properties": { "library": { "type": "string", "description": "Target library bucket name." }, "category": { "type": "string", "description": "Category within the library." }, "folder_path": { "type": "array", "items": { "type": "string" }, "description": "Ordered path segments for the document's folder location." }, "title": { "type": "string", "description": "Document title." }, "source_path": { "type": "string", "description": "Canonical source path used for upsert resolution." }, "markdown": { "type": "string", "maxLength": 2097152, "description": "Markdown content for the document (up to 2 MB). Mutually exclusive with `pdf_base64`." }, "pdf_base64": { "type": "string", "description": "Base64-encoded PDF content. Mutually exclusive with `markdown`. Validated for JavaScript actions." }, "metadata": { "type": "object", "description": "Optional arbitrary metadata to attach to the document." } } }, "FilesDocs_PublishDocumentResult": { "type": "object", "description": "Result of a document publish operation.", "required": [ "id", "operation" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Document ID." }, "operation": { "type": "string", "enum": [ "created", "updated" ], "description": "Whether the document was newly created or an existing document was updated." }, "r2_key": { "type": "string", "description": "R2 object key where the file is stored." }, "file_url": { "type": "string", "format": "uri", "description": "Accessible URL of the stored file." }, "file_size": { "type": "integer", "description": "File size in bytes." }, "folder_path": { "type": "array", "items": { "type": "string" }, "description": "Resolved folder path segments." } } }, "FilesDocs_BBDoc": { "type": "object", "description": "A BB Doc — a collaborative document with Yjs CRDT backing.", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "content_type": { "type": "string", "enum": [ "pf2", "amsthm", "latex" ], "description": "Math/document format of the BB Doc." }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FilesDocs_CreateBBDocRequest": { "type": "object", "description": "Request body for creating a new BB Doc.", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Title of the new BB Doc." }, "fromTemplateId": { "type": "string", "format": "uuid", "description": "Optional template to initialise the document from." }, "initialContent": { "type": "string", "minLength": 1, "maxLength": 10485760, "description": "Optional initial content (up to 10 MB)." }, "initialFormat": { "type": "string", "enum": [ "pf2", "amsthm", "latex" ], "description": "Format of `initialContent`, if provided." }, "sourceDocumentId": { "type": "string", "format": "uuid", "description": "Optional existing BB Doc to copy content from." } } }, "FilesDocs_BBDocVersion": { "type": "object", "description": "A snapshot version of a BB Doc.", "properties": { "id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "version_number": { "type": "integer", "minimum": 1 }, "content_snapshot": { "type": "string", "description": "Serialised Yjs document state at this version." }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "FilesDocs_BBDocComment": { "type": "object", "description": "A comment thread on a BB Doc.", "properties": { "id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "anchor_from": { "type": "integer", "minimum": 0, "description": "Start character offset (Yjs doc position)." }, "anchor_to": { "type": "integer", "minimum": 0, "description": "End character offset (Yjs doc position)." }, "body": { "type": "string", "minLength": 1, "maxLength": 5000 }, "author_name": { "type": "string", "nullable": true }, "resolved": { "type": "boolean" }, "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true }, "assignee_name": { "type": "string", "nullable": true }, "assignment_done": { "type": "boolean" }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/FilesDocs_BBDocCommentReply" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FilesDocs_CreateCommentRequest": { "type": "object", "description": "Request body for creating a comment on a BB Doc.", "required": [ "anchorFrom", "anchorTo", "body" ], "additionalProperties": false, "properties": { "commentId": { "type": "string", "format": "uuid", "description": "Optional client-supplied ID for idempotency." }, "anchorFrom": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Start offset of the comment anchor in the Yjs document." }, "anchorTo": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "End offset of the comment anchor in the Yjs document." }, "body": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Comment body text." }, "authorName": { "type": "string", "maxLength": 200, "description": "Display name of the comment author." } } }, "FilesDocs_BBDocCommentReply": { "type": "object", "description": "A reply within a BB Doc comment thread.", "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "minLength": 1, "maxLength": 5000 }, "author_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "FilesDocs_CreateReplyRequest": { "type": "object", "description": "Request body for adding a reply to a comment thread.", "required": [ "body" ], "additionalProperties": false, "properties": { "replyId": { "type": "string", "format": "uuid", "description": "Optional client-supplied ID for idempotency." }, "body": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Reply body text." }, "authorName": { "type": "string", "maxLength": 200, "description": "Display name of the reply author." } } }, "FilesDocs_BBDocShare": { "type": "object", "description": "A share grant on a BB Doc.", "properties": { "id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "view", "comment", "suggest", "edit" ], "description": "Access level granted." }, "scope": { "type": "string", "description": "Sharing scope identifier." }, "scope_kind": { "type": "string", "enum": [ "resource", "file", "folder" ], "description": "Kind of scope this grant applies to." }, "target_id": { "type": "string", "nullable": true, "description": "Scoped target identifier." }, "recipient_org_id": { "type": "string", "format": "uuid", "nullable": true }, "recipient_user_id": { "type": "string", "format": "uuid", "nullable": true }, "path": { "type": "string", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "FilesDocs_CreateShareRequest": { "type": "object", "description": "Request body for creating a share grant on a BB Doc.", "additionalProperties": false, "properties": { "level": { "type": "string", "enum": [ "view", "comment", "suggest", "edit" ], "description": "Access level to grant. Defaults to `view`." }, "scope": { "type": "string", "description": "Sharing scope identifier." }, "target_id": { "type": "string", "maxLength": 200, "description": "Scoped target identifier." }, "recipient_org_id": { "type": "string", "format": "uuid", "description": "Organisation to share with." }, "recipient_user_id": { "type": "string", "format": "uuid", "description": "User to share with." }, "scope_kind": { "type": "string", "enum": [ "resource", "file", "folder" ], "description": "The kind of scope this grant applies to." }, "path": { "type": "string", "maxLength": 1024, "description": "Path scoping this grant (when `scope_kind` is `file` or `folder`)." } } }, "FilesDocs_ResourceVersion": { "type": "object", "description": "A version snapshot of a versioned API resource.", "properties": { "id": { "type": "string", "format": "uuid" }, "resource_id": { "type": "string", "format": "uuid" }, "resource_type": { "type": "string" }, "version": { "type": "integer", "minimum": 1, "description": "Sequential version number." }, "snapshot": { "type": "object", "description": "Full resource payload at this version." }, "changelog": { "type": "string", "nullable": true, "description": "Human-readable note recorded with this version." }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "FilesDocs_PromoteArtifactRequest": { "type": "object", "description": "Request body for promoting a Science artifact to the document library.", "required": [ "artifact_id", "project_id" ], "additionalProperties": false, "properties": { "artifact_id": { "type": "string", "format": "uuid", "description": "ID of the Science artifact to promote." }, "project_id": { "type": "string", "format": "uuid", "description": "Target project that will own the new document." }, "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Title for the new document (whitespace-trimmed). Defaults to the artifact name." }, "folder_id": { "type": "string", "format": "uuid", "description": "Target folder in the document library." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 200, "description": "MIME type override (whitespace-trimmed). Defaults to the artifact's detected content type." }, "dest_path": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Override the destination R2 object path (whitespace-trimmed)." } } }, "OrgAdmin_OrgSetting": { "type": "object", "description": "A single org-level configuration key-value record.", "properties": { "key": { "type": "string", "description": "Setting key slug." }, "value": { "type": [ "string", "null" ], "description": "Current setting value (stored as text; booleans appear as `\"true\"`/`\"false\"`)." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the setting was last modified." } } }, "OrgAdmin_OrgSettingSetRequest": { "type": "object", "additionalProperties": false, "description": "Request body for upserting an org setting. Only the `value` field is accepted (strict object).", "required": [ "value" ], "properties": { "value": { "type": "string", "maxLength": 4096, "description": "New setting value (stored verbatim as text; the stored procedure normalises boolean-shaped strings)." } } }, "OrgAdmin_CustomDomain": { "type": "object", "description": "A custom domain record for an organization.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Domain record identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization identifier." }, "saas_package_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SaaS package this domain is scoped to, or null for org-level domains." }, "domain": { "type": "string", "maxLength": 253, "description": "Fully-qualified domain name (lowercase)." }, "domain_type": { "type": "string", "enum": [ "primary", "alias", "subdomain" ], "description": "Classification of the domain's role." }, "is_default": { "type": "boolean", "description": "Whether this is the default domain for the environment." }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ], "description": "Target environment this domain serves." }, "api_base_url": { "type": [ "string", "null" ], "description": "HTTPS API base URL associated with this domain." }, "status": { "type": "string", "enum": [ "pending_verification", "active", "suspended", "deleted" ], "description": "Current lifecycle status." }, "dns_verification_token": { "type": [ "string", "null" ], "description": "Opaque token to publish as a TXT record at `_backbuild-verify.` to prove ownership." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the domain passed DNS verification." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record was last modified." } } }, "OrgAdmin_CreateDomainRequest": { "type": "object", "additionalProperties": false, "description": "Request body for registering a new org custom domain.", "required": [ "domain" ], "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Fully-qualified domain name to register (e.g. `app.acme.com`). Must match the pattern for valid hostnames (lowercase alphanumeric labels separated by dots)." }, "domain_type": { "type": "string", "enum": [ "primary", "alias", "subdomain" ], "description": "Domain role classification. Defaults to `alias` when omitted." }, "is_default": { "type": "boolean", "description": "Whether this should be the default domain for the environment. Defaults to `true` when `domain_type` is `primary`." }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ], "description": "Target environment. Defaults to `production` when omitted." }, "api_base_url": { "type": "string", "maxLength": 2048, "description": "HTTPS URL for the Backbuild API that serves this domain (must begin with `https://`). Defaults to the standard endpoint for the chosen environment when omitted." } } }, "OrgAdmin_OrgPolicies": { "type": "object", "description": "Organization control policies.", "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Organization identifier." }, "session_inactivity_timeout_minutes": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 525600, "description": "Session idle timeout in minutes. Null means the platform default applies." }, "max_concurrent_containers": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Maximum number of concurrently running containers for this org. Null means the platform default applies." }, "container_daily_hours_cap": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000, "description": "Maximum total container-hours per day across the org. Null means no cap beyond the platform default." }, "ai_daily_spend_cap_micros": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000000000000, "description": "Maximum AI spend in a calendar day, denominated in micro-USD (1 USD = 1,000,000 micros). Null means no cap." }, "extra_policies": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Extensible JSON bag for additional policy fields added in later releases." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When policies were last modified." } } }, "OrgAdmin_UpdatePoliciesRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Partial update body for org control policies. At least one field must be present. Set a numeric field to `null` to revert to the platform default.", "properties": { "session_inactivity_timeout_minutes": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 525600, "description": "Session idle timeout in minutes (0–525600 = up to 1 year). Null clears the org override." }, "max_concurrent_containers": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Maximum simultaneous running containers (0–100000). Null clears the org override." }, "container_daily_hours_cap": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000, "description": "Daily container-hours cap (0–1000000). Null clears the org override." }, "ai_daily_spend_cap_micros": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000000000000, "description": "Daily AI spend cap in micro-USD (0–1,000,000,000,000,000). Null clears the org override." }, "extra_policies": { "type": "object", "additionalProperties": true, "description": "Additional policy fields (arbitrary JSON object). Merged into the existing `extra_policies` by the stored procedure." } } }, "OrgAdmin_SlugAvailability": { "type": "object", "description": "Advisory slug availability result. Never reveals who owns the slug when unavailable.", "required": [ "available" ], "properties": { "available": { "type": "boolean", "description": "Whether the slug is available for use." }, "reason": { "type": [ "string", "null" ], "description": "Machine-readable reason when `available` is false: `taken` (already in use), `reserved` (reserved platform word), `invalid_format` (slug does not meet format rules), `uuid_shaped` (looks like a UUID and is disallowed), or `error` (lookup could not be completed)." } } }, "OrgAdmin_VisibilityCheckRequest": { "type": "object", "description": "Request body for a visibility check.", "required": [ "resource_type", "resource_id" ], "properties": { "resource_type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The type of resource to check (e.g. `project`, `document`)." }, "resource_id": { "type": "string", "format": "uuid", "description": "Identifier of the resource to evaluate." }, "target_user_id": { "type": "string", "format": "uuid", "description": "User to evaluate visibility for. Defaults to the authenticated caller when omitted." }, "target_group_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Group to evaluate visibility for (optional)." } } }, "OrgAdmin_VisibilityVerdict": { "type": "object", "description": "Visibility evaluation result from the stored procedure.", "properties": { "visible": { "type": "boolean", "description": "Whether the target principal can see the resource." }, "rule_applied": { "type": [ "string", "null" ], "description": "Identifier of the rule that determined the outcome, or null if the default applied." }, "effective_scope": { "type": [ "string", "null" ], "description": "The scope level at which the decisive rule was matched." } } }, "OrgAdmin_VisibilityRule": { "type": "object", "description": "A visibility rule record.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Rule identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "resource_type": { "type": "string", "description": "Resource type this rule applies to." }, "resource_id": { "type": "string", "format": "uuid", "description": "Resource this rule applies to." }, "rule_type": { "type": "string", "enum": [ "allow", "deny" ], "description": "Whether this rule grants or denies visibility." }, "scope": { "type": "string", "enum": [ "global", "org", "user", "role", "group", "department", "project", "org_hierarchy" ], "description": "The scope to which this rule applies." }, "scope_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Identifier of the scope target (e.g. user id, role id). Null for `global` scope." }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Evaluation priority (higher value = evaluated first)." }, "conditions": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Optional additional conditions (arbitrary JSON)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the rule expires. Null means the rule never expires." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Arbitrary metadata attached to this rule." }, "created_by": { "type": [ "string", "null" ], "format": "uuid", "description": "User who created the rule." }, "created_at": { "type": "string", "format": "date-time", "description": "When the rule was created." } } }, "OrgAdmin_CreateVisibilityRuleRequest": { "type": "object", "description": "Request body for creating a visibility rule. `scope_id` is required for all scopes except `global`.", "required": [ "resource_type", "resource_id", "scope" ], "properties": { "resource_type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The type of resource this rule applies to." }, "resource_id": { "type": "string", "format": "uuid", "description": "Identifier of the resource this rule applies to." }, "rule_type": { "type": "string", "enum": [ "allow", "deny" ], "description": "Whether the rule grants (`allow`) or denies (`deny`) visibility. Defaults to `allow` when omitted." }, "scope": { "type": "string", "enum": [ "global", "org", "user", "role", "group", "department", "project", "org_hierarchy" ], "description": "Scope at which the rule applies. `scope_id` is required for all values except `global`." }, "scope_id": { "type": "string", "format": "uuid", "description": "Identifier of the scope target (required unless `scope` is `global`)." }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Evaluation priority (0–1000; higher = evaluated first). Defaults to 0." }, "conditions": { "type": "object", "additionalProperties": true, "description": "Optional additional conditions (bounded JSON object)." }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional expiry timestamp (ISO 8601). The rule is automatically inactive after this time." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata (bounded JSON object)." } } }, "OrgAdmin_BootstrapContext": { "type": "object", "description": "One-hit bootstrap payload. Contains the bounded first-paint data slices for the authenticated user's shell: profile, organizations, projects, settings, and other areas the caller can see. Each slice is gated independently by the stored procedure — a gated or absent feature never fails the overall response. The exact shape of each slice matches the corresponding domain's full endpoint response.", "additionalProperties": true, "properties": { "user": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The authenticated user's profile slice." }, "organizations": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true }, "description": "Organizations the caller belongs to." }, "projects": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true }, "description": "First-paint project slice for the active organization." }, "settings": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Org and user settings slice." } } }, "OrgAdmin_CcpaOptOutResult": { "type": "object", "description": "Result of a CCPA §1798.120 opt-out request.", "properties": { "opted_out": { "type": "boolean", "description": "Whether the consumer is now opted out of data sale and sharing." }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the opt-out was first recorded (idempotent — this is the ORIGINAL opt-out instant, which anchors the §1798.135(c) 12-month wait-before-re-soliciting clock)." }, "idempotent": { "type": "boolean", "description": "True if the consumer was already opted out before this call." } } }, "OrgAdmin_CcpaDataCategoryEntry": { "type": "object", "description": "One category of personal information Backbuild collects.", "properties": { "category": { "type": "string", "description": "CCPA category name." }, "ccpa_category": { "type": "string", "description": "CCPA statutory reference (e.g. `1798.140(v)(1)(A)`)." }, "examples": { "type": "array", "items": { "type": "string" }, "description": "Illustrative data elements collected in this category." }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Categories of sources from which the information is collected." }, "purposes": { "type": "array", "items": { "type": "string" }, "description": "Business or commercial purposes for which the information is collected." }, "shared_with": { "type": "array", "items": { "type": "string" }, "description": "Categories of third parties with whom the information is shared." }, "sold": { "type": "boolean", "description": "Whether this category of information is sold (under CCPA's definition)." }, "shared_for_cross_context_behavioural_advertising": { "type": "boolean", "description": "Whether this category is shared for cross-context behavioural advertising under CPRA §1798.140(ah)." } } }, "OrgAdmin_CcpaDataCategoriesResult": { "type": "object", "description": "CCPA §1798.130 12-month look-back: categories of personal information collected, their sources, purposes, and sharing.", "properties": { "consumer_user_id": { "type": "string", "format": "uuid", "description": "The authenticated consumer's user id." }, "window_start": { "type": "string", "format": "date-time", "description": "Start of the look-back window (defaults to 12 months before the request)." }, "window_end": { "type": "string", "format": "date-time", "description": "End of the look-back window (time of the request)." }, "look_back_months": { "type": "integer", "description": "Duration of the look-back window in months (always 12)." }, "sold_in_window": { "type": "boolean", "description": "Whether any personal information was sold during the window." }, "shared_for_cross_context_behavioural_advertising_in_window": { "type": "boolean", "description": "Whether any personal information was shared for cross-context behavioural advertising during the window." }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/OrgAdmin_CcpaDataCategoryEntry" }, "description": "Enumerated categories of personal information." }, "framework_references": { "type": "array", "items": { "type": "string" }, "description": "Applicable statutory references." }, "request_id": { "type": "string", "description": "Correlation id for this disclosure request." } } }, "OrgAdmin_LegalAgreementTemplate": { "type": "object", "description": "An active legal agreement template.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Template identifier (UUIDv7)." }, "slug": { "type": "string", "description": "URL-safe slug identifying this template type (e.g. `dpa`, `baa`, `ccpa-addendum`)." }, "name": { "type": "string", "description": "Human-readable template name." }, "version": { "type": "string", "description": "Template version string." }, "content_hash": { "type": "string", "description": "SHA-256 hex hash of the template markdown content (used for integrity verification)." }, "content_md": { "type": [ "string", "null" ], "description": "Full markdown content of the template (present on detail endpoint only)." }, "is_active": { "type": "boolean", "description": "Whether the template is currently available for signing." }, "created_at": { "type": "string", "format": "date-time", "description": "When the template was created." } } }, "OrgAdmin_AgreementSignRequest": { "type": "object", "additionalProperties": false, "description": "Request body for signing a legal agreement. All personal fields must be accurate — they are embedded in the generated PDF and the audit record.", "required": [ "template_id", "signer_name", "signer_title", "signer_email", "signer_company" ], "properties": { "template_id": { "type": "string", "format": "uuid", "description": "Identifier of the template to sign (must be an active template)." }, "signer_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Full legal name of the person signing on behalf of the organization." }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Job title of the signatory." }, "signer_email": { "type": "string", "format": "email", "maxLength": 320, "description": "Email address of the signatory. A copy of the signed PDF is delivered here." }, "signer_company": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Legal entity name of the signing organization." }, "cc_recipients": { "type": "array", "maxItems": 5, "description": "Optional list of additional recipients (CC) for the signed-PDF email. Maximum 5 entries. Every CC email must belong to an active member of the signing organization — non-member addresses are rejected with `403 FORBIDDEN`.", "items": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320, "description": "CC recipient email (must be an active org member)." } } } } } }, "OrgAdmin_AgreementAcceptance": { "type": "object", "description": "A signed legal agreement acceptance record.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Acceptance record identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Organization that signed the agreement." }, "template_id": { "type": "string", "format": "uuid", "description": "Template that was signed." }, "template_slug": { "type": "string", "description": "Slug of the signed template." }, "document_hash": { "type": "string", "description": "SHA-256 hex hash of the template content at time of signing." }, "signature_hash": { "type": "string", "description": "HMAC-SHA256 signature over the canonical signing payload, using the platform signing key. Provides non-repudiation." }, "signer_name": { "type": "string", "description": "Name of the signatory." }, "signer_title": { "type": "string", "description": "Title of the signatory." }, "signer_email": { "type": "string", "format": "email", "description": "Email of the signatory." }, "signer_company": { "type": "string", "description": "Legal entity that signed." }, "ip_address": { "type": "string", "description": "IP address from which the signing request originated." }, "user_agent": { "type": "string", "description": "User-Agent header from the signing request." }, "signed_at": { "type": "string", "format": "date-time", "description": "When the agreement was signed." }, "pdf_generated": { "type": "boolean", "description": "Whether a signed PDF was successfully generated and stored." }, "status": { "type": "string", "enum": [ "active", "superseded", "revoked" ], "description": "Current acceptance status." }, "created_at": { "type": "string", "format": "date-time", "description": "When the acceptance record was created." } } }, "OrgCore_OrgSummary": { "type": "object", "description": "A summary of an organization visible to a member, as returned by the list-organizations endpoint.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Organization identifier (UUIDv7)." }, "name": { "type": "string", "description": "Organization display name." }, "slug": { "type": [ "string", "null" ], "description": "Optional URL-safe slug. Null when the organization has no slug." }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the organization logo." }, "role": { "type": [ "string", "null" ], "description": "The caller's role in this organization (e.g. `owner`, `admin`, `member`)." }, "is_active": { "type": "boolean", "description": "Whether this organization is active." }, "plan_tier": { "type": [ "string", "null" ], "enum": [ "free", "starter", "professional", "enterprise", null ], "description": "Billing plan tier." } } }, "OrgCore_Organization": { "type": "object", "description": "Full organization record.", "required": [ "id", "name", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Organization identifier (UUIDv7)." }, "name": { "type": "string", "description": "Display name (1–255 characters)." }, "slug": { "type": [ "string", "null" ], "description": "Optional URL-safe slug (3–63 chars, canonical grammar). Null when not set." }, "plan_tier": { "type": [ "string", "null" ], "enum": [ "free", "starter", "professional", "enterprise", null ], "description": "Billing plan tier." }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the organization logo." }, "is_active": { "type": "boolean", "description": "Whether the organization is active." }, "settings": { "type": "object", "additionalProperties": true, "description": "Organization settings object. Contains profile, billing_address, shipping_address, policies, and contacts sub-objects." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp (platform-assigned)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last-update timestamp." } } }, "OrgCore_SlugResolveResult": { "type": "object", "description": "Result of a slug or UUID resolution.", "required": [ "org_id" ], "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Canonical organization UUID." }, "canonical_slug": { "type": [ "string", "null" ], "description": "The organization's canonical slug, if one is set. Null when the organization has no slug." } } }, "OrgCore_CreateOrganizationRequest": { "type": "object", "additionalProperties": false, "description": "Create-organization request body. Extra fields are rejected — fields such as org_id, created_by, or plan override flags are not accepted.", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Organization display name." }, "slug": { "type": "string", "minLength": 3, "maxLength": 63, "description": "Optional canonical slug. Must be lowercase letters/numbers separated by single hyphens (no leading, trailing, or consecutive hyphens), not UUID-shaped, and not a reserved word. Auto-generated from the name when omitted." }, "plan_tier": { "type": "string", "enum": [ "free", "starter", "professional", "enterprise" ], "description": "Optional billing plan tier." }, "org_type": { "type": "string", "maxLength": 64, "description": "Optional entity type (e.g. `llc`, `corp`, `nonprofit`)." }, "description": { "type": "string", "maxLength": 4096, "description": "Optional description." }, "logo_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Optional logo URL." }, "website": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Optional website URL." }, "billing_email": { "type": "string", "format": "email", "maxLength": 320, "description": "Optional billing contact email." }, "settings": { "$ref": "#/components/schemas/OrgCore_OrganizationSettings" } } }, "OrgCore_UpdateOrganizationRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Update-organization request body. At least one field must be present. `slug: null` clears the optional slug.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New display name." }, "slug": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 63, "description": "New canonical slug (same grammar as create), or `null` to clear the slug." }, "description": { "type": "string", "maxLength": 4096, "description": "New description." }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "New logo URL, or `null` to clear." }, "website": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "New website URL, or `null` to clear." }, "billing_email": { "type": "string", "format": "email", "maxLength": 320, "description": "New billing contact email." }, "settings": { "$ref": "#/components/schemas/OrgCore_OrganizationSettings" } } }, "OrgCore_OrganizationSettings": { "type": "object", "additionalProperties": false, "description": "Organization settings patch. All sub-objects are optional; only supplied keys are merged.", "properties": { "profile": { "type": "object", "description": "Organization profile fields.", "properties": { "description": { "type": "string", "maxLength": 4096, "description": "Organization description." }, "legal_name": { "type": "string", "maxLength": 255, "description": "Legal entity name." }, "dba_name": { "type": "string", "maxLength": 255, "description": "Doing-business-as name." }, "entity_type": { "type": "string", "maxLength": 64, "description": "Legal entity type (e.g. `llc`, `corp`)." }, "tax_id_type": { "type": "string", "enum": [ "ein", "ssn", "itin", "other" ], "description": "Tax identifier type." }, "tax_id_value": { "type": "string", "maxLength": 64, "description": "Tax identifier value." }, "phone_number": { "type": "string", "maxLength": 64, "description": "Contact phone number." }, "website": { "type": "string", "maxLength": 2048, "description": "Organization website URL." }, "billing_email": { "type": "string", "format": "email", "maxLength": 320, "description": "Billing contact email." }, "support_email": { "type": "string", "format": "email", "maxLength": 320, "description": "Support contact email." } } }, "billing_address": { "$ref": "#/components/schemas/OrgCore_Address" }, "shipping_address": { "$ref": "#/components/schemas/OrgCore_Address" }, "policies": { "type": "object", "description": "Organization policy settings.", "properties": { "default_timezone": { "type": "string", "maxLength": 120, "description": "IANA timezone name (e.g. `America/New_York`)." }, "enforce_2fa": { "type": "boolean", "description": "Require two-factor authentication for all members." }, "allowed_domains": { "type": "array", "maxItems": 100, "items": { "type": "string", "description": "Email domain (e.g. `example.com` or `*.example.com`)." }, "description": "Email domains allowed for membership." }, "max_members": { "type": "integer", "minimum": 1, "maximum": 100000, "description": "Maximum allowed member count." } } }, "contacts": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/OrgCore_Contact" }, "description": "Organization contact records (up to 50)." } } }, "OrgCore_Address": { "type": "object", "additionalProperties": false, "description": "A postal address.", "properties": { "attention": { "type": "string", "maxLength": 255, "description": "Attention / care-of line." }, "line1": { "type": "string", "maxLength": 255, "description": "Street address line 1." }, "line2": { "type": "string", "maxLength": 255, "description": "Street address line 2." }, "city": { "type": "string", "maxLength": 120, "description": "City." }, "state_or_region": { "type": "string", "maxLength": 120, "description": "State, province, or region." }, "postal_code": { "type": "string", "maxLength": 32, "description": "Postal or ZIP code." }, "country": { "type": "string", "maxLength": 120, "description": "Country name or ISO code." } } }, "OrgCore_Contact": { "type": "object", "additionalProperties": false, "description": "An organization contact record.", "required": [ "title", "user_id" ], "properties": { "id": { "type": "string", "maxLength": 128, "description": "Optional contact record identifier." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Contact title or role (e.g. `CEO`, `Legal Counsel`)." }, "user_id": { "type": "string", "format": "uuid", "description": "Platform user identifier (UUIDv7)." }, "email": { "type": "string", "format": "email", "maxLength": 320, "description": "Contact email address." }, "display_name": { "type": "string", "maxLength": 255, "description": "Display name override. Must not contain zero-width, bidi-override, or mixed-script homoglyph characters." }, "notes": { "type": "string", "maxLength": 1024, "description": "Optional notes." } } }, "OrgCore_OrgMember": { "type": "object", "description": "An organization membership record.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "Member user identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Organization identifier." }, "role": { "type": "string", "description": "Member's role (e.g. `owner`, `admin`, `member`)." }, "status": { "type": "string", "description": "Membership status (e.g. `active`, `invited`, `suspended`)." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Member email address." }, "display_name": { "type": [ "string", "null" ], "description": "Member display name." }, "is_active": { "type": "boolean", "description": "Whether this membership is currently active." }, "joined_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the member joined the organization." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last-update timestamp." } } }, "OrgCore_UpsertMemberRequest": { "type": "object", "additionalProperties": false, "description": "Add-or-update member request body. Extra fields such as is_super_admin or created_by are rejected.", "required": [ "user_id", "role" ], "properties": { "user_id": { "type": "string", "format": "uuid", "description": "The user to add or update (UUIDv7)." }, "role": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Role to grant. Callers cannot grant a role higher than their own." }, "status": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Optional membership status." }, "email": { "type": "string", "format": "email", "maxLength": 255, "description": "Optional email. Required when adding a user not yet visible to the caller via RLS (e.g. a cross-tenant invite)." } } }, "OrgCore_AuthSettings": { "type": "object", "description": "Effective authentication settings for an organization (platform defaults merged with per-org overrides).", "required": [ "session_duration_days", "concurrent_sessions_per_user_limit", "passkey_satisfies_primary", "allow_password_login" ], "properties": { "session_duration_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Maximum session lifetime in days." }, "concurrent_sessions_per_user_limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum concurrent active sessions per user." }, "passkey_satisfies_primary": { "type": "boolean", "description": "When true, a passkey satisfies the primary authentication factor." }, "allow_password_login": { "type": "boolean", "description": "Whether password-based login is permitted for this organization." } } }, "OrgCore_UpdateAuthSettingsRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Update org auth policy. At least one field must be present. Disabling all authentication methods is rejected.", "properties": { "passkey_satisfies_primary": { "type": "boolean", "description": "Allow a passkey to satisfy the primary factor." }, "allow_password_login": { "type": "boolean", "description": "Enable or disable password-based login." }, "session_duration_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Session lifetime in days." }, "concurrent_sessions_per_user_limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum concurrent sessions per user." } } }, "OrgCore_OrgSettingsUpdateRequest": { "type": "object", "description": "Batch org-settings update request.", "required": [ "settings" ], "properties": { "settings": { "type": "object", "additionalProperties": true, "description": "Settings key-value map. Bounded by the platform JSONB size and depth limits." } } }, "OrgCore_UserPreferencesUpdateRequest": { "type": "object", "description": "Batch user-preferences update request.", "required": [ "preferences" ], "properties": { "preferences": { "type": "object", "additionalProperties": true, "description": "Preference key-value map. Bounded by the platform JSONB size and depth limits." } } }, "OrgCore_PersonalizationSettings": { "type": "object", "additionalProperties": false, "description": "Normalized personalization preferences.", "required": [ "themeMode", "language", "notifications" ], "properties": { "themeMode": { "type": "string", "enum": [ "light", "dark", "system" ], "description": "UI color scheme preference." }, "language": { "type": "string", "minLength": 1, "maxLength": 16, "description": "BCP-47 language tag (e.g. `en`, `fr`, `pt-BR`)." }, "stayLoggedInHours": { "type": "integer", "enum": [ 1, 8, 24, 168, 720 ], "description": "Preferred session lifetime in hours. Must be one of `1`, `8`, `24`, `168`, or `720`. The platform additionally clamps this to the organization's `session_duration_days` cap." }, "notifications": { "type": "object", "additionalProperties": false, "required": [ "emailNotifications", "pushNotifications", "weeklyDigest", "mentionAlerts" ], "description": "Notification preferences.", "properties": { "emailNotifications": { "type": "boolean", "description": "Receive email notifications." }, "pushNotifications": { "type": "boolean", "description": "Receive push notifications." }, "weeklyDigest": { "type": "boolean", "description": "Receive a weekly activity digest email." }, "mentionAlerts": { "type": "boolean", "description": "Receive alerts when mentioned." } } } } }, "Entities_Environment": { "type": "object", "description": "A logical deployment environment row (dev, staging, preprod, or prod) belonging to the caller's organization.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Environment identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization identifier." }, "env_key": { "type": "string", "enum": [ "dev", "staging", "preprod", "prod" ], "description": "Canonical environment key." }, "display_name": { "type": "string", "description": "Human-readable display name." }, "is_default": { "type": "boolean", "description": "True for the production (default) environment." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateEnvironmentRequest": { "type": "object", "description": "Body for creating a non-production logical environment.", "additionalProperties": false, "required": [ "env_key" ], "properties": { "env_key": { "type": "string", "enum": [ "dev", "staging", "preprod" ], "description": "The environment tier to create. `prod` cannot be created via this surface." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Optional human-readable label for the environment." } } }, "Entities_EnvironmentGrant": { "type": "object", "description": "An access grant that controls which users, groups, departments, or roles can access or manage an environment.", "properties": { "id": { "type": "string", "format": "uuid" }, "env_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "user", "group", "department", "role" ] }, "target_id": { "type": "string", "description": "Principal identifier within the scope." }, "capability": { "type": "string", "enum": [ "member", "manage" ] }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateEnvironmentGrantRequest": { "type": "object", "description": "Body for creating an environment access grant.", "additionalProperties": false, "required": [ "scope", "target_id" ], "properties": { "scope": { "type": "string", "enum": [ "user", "group", "department", "role" ], "description": "The principal scope being granted." }, "target_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Identifier of the principal within the given scope." }, "capability": { "type": "string", "enum": [ "member", "manage" ], "description": "Access level granted. Defaults to `member` when omitted." } } }, "Entities_Template": { "type": "object", "description": "A project template that can be used as a starting point when creating new projects.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "config": { "type": "object", "description": "Arbitrary JSON configuration for the template." }, "source_project_id": { "type": "string", "format": "uuid", "nullable": true }, "is_published": { "type": "boolean" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Entities_TemplateVersion": { "type": "object", "description": "A single version snapshot of a project template.", "properties": { "id": { "type": "string", "format": "uuid" }, "template_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "config": { "type": "object" }, "changelog": { "type": "string", "nullable": true }, "created_by_user_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateTemplateRequest": { "type": "object", "description": "Body for creating a project template.", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Display name for the template." }, "description": { "type": "string", "maxLength": 10000, "description": "Optional human-readable description. Content is screened by the platform content-safety gate; prohibited content returns `CONTENT_POLICY_VIOLATION`." }, "config": { "type": "object", "description": "Arbitrary JSON configuration (project structure, entity types, etc.). Defaults to `{}`." }, "source_project_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional project to seed the template from." } } }, "Entities_Entity": { "type": "object", "description": "A single entity instance belonging to a project.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "entity_type_id": { "type": "string", "format": "uuid" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "status": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "description": "Arbitrary field bag (top-level key merge on update)." }, "owner_scope": { "type": "string", "enum": [ "user", "project", "group", "department", "org" ], "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "state_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "Current workflow state (null when no workflow assigned)." }, "created_by_user_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateEntityRequest": { "type": "object", "description": "Body for creating a new entity inside a project.", "required": [ "entity_type_id", "name" ], "properties": { "entity_type_id": { "type": "string", "format": "uuid", "description": "Entity type to instantiate." }, "name": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Display name for the entity." }, "parent_id": { "type": "string", "format": "uuid", "description": "Optional parent entity for tree nesting." }, "data": { "type": "object", "description": "Field bag (alias: `metadata`). Only one need be supplied; they are merged." }, "metadata": { "type": "object", "description": "Alias for `data`. Symmetric with the GET response field name." }, "owner_scope": { "type": "string", "enum": [ "user", "project", "group", "department", "org" ] }, "owner_id": { "type": "string", "format": "uuid" } } }, "Entities_UpdateEntityRequest": { "type": "object", "description": "Body for updating an entity. At least one field (other than `expected_updated_at`) must be provided. The `metadata` bag uses a top-level key merge: a supplied key sets/overwrites it; an explicit `null` value removes it; an omitted key is preserved.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "data": { "type": "object", "description": "Alias for `metadata`." }, "metadata": { "type": "object", "description": "Field bag, top-level key merge. Send a key as `null` to delete it." }, "status": { "type": "string", "minLength": 1, "maxLength": 64 }, "parent_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Send `null` to detach from parent." }, "owner_scope": { "type": "string", "enum": [ "user", "project", "group", "department", "org" ] }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "expected_updated_at": { "type": "string", "format": "date-time", "description": "Optimistic-concurrency precondition. When provided the update fails with `CONFLICT` if the row was modified since this timestamp." } } }, "Entities_TransitionEntityRequest": { "type": "object", "description": "Body for a workflow-state transition.", "additionalProperties": false, "required": [ "to_state_id" ], "properties": { "to_state_id": { "type": "string", "format": "uuid", "description": "Target workflow-state identifier." }, "expected_updated_at": { "type": "string", "format": "date-time", "description": "Optimistic-concurrency precondition (same contract as entity update)." } } }, "Entities_EntityPin": { "type": "object", "description": "A per-user pin (star/bookmark) on an entity.", "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string", "format": "uuid" }, "position": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Entities_EntityType": { "type": "object", "description": "A user-defined entity type schema that governs a class of entities within an organization.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true, "description": "Hex color code." }, "parent_uuid": { "type": "string", "format": "uuid", "nullable": true }, "category": { "type": "string", "nullable": true }, "fields": { "type": "array", "items": { "type": "object" }, "nullable": true }, "ai_instructions": { "type": "object", "nullable": true }, "relationship_mode": { "type": "string", "enum": [ "open", "restricted" ], "nullable": true }, "html_template": { "type": "string", "nullable": true }, "css_styles": { "type": "string", "nullable": true }, "sample_data": { "type": "string", "nullable": true }, "render_template_full": { "type": "string", "nullable": true, "description": "Full-card Handlebars/HTML render template (max 256 KiB)." }, "render_template_full_styles": { "type": "string", "nullable": true, "description": "CSS for the full-card template (max 64 KiB)." }, "render_template_icon": { "type": "string", "nullable": true, "description": "Icon-size render template (max 256 KiB)." }, "render_template_icon_styles": { "type": "string", "nullable": true }, "owner_scope": { "type": "string", "enum": [ "user", "project", "group", "department", "org" ], "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "default_entity_owner_scope": { "type": "string", "enum": [ "creator", "project", "group", "department", "org" ], "nullable": true }, "permission_flags": { "type": "object", "nullable": true }, "settings": { "type": "object", "nullable": true }, "adopted_source_version": { "type": "integer", "nullable": true }, "source_current_version": { "type": "integer", "nullable": true, "description": "Non-null when this type is a subscriber clone; compare with `adopted_source_version` to detect available updates." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateEntityTypeRequest": { "type": "object", "description": "Body for creating a new entity type.", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9_-]+$", "description": "URL-safe identifier. Auto-generated from `name` when omitted." }, "description": { "type": "string", "maxLength": 2048 }, "icon": { "type": "string", "maxLength": 64 }, "color": { "type": "string", "maxLength": 32, "pattern": "^#[0-9a-fA-F]{3,8}$" }, "parent_uuid": { "type": "string", "format": "uuid", "nullable": true }, "category": { "type": "string", "maxLength": 128 }, "fields": { "type": "array", "items": { "type": "object" } }, "ai_instructions": { "type": "object" }, "relationship_mode": { "type": "string", "enum": [ "open", "restricted" ] }, "html_template": { "type": "string" }, "css_styles": { "type": "string" }, "sample_data": { "type": "string" }, "render_template_full": { "type": "string", "maxLength": 262144 }, "render_template_full_styles": { "type": "string", "maxLength": 65536 }, "render_template_icon": { "type": "string", "maxLength": 262144 }, "render_template_icon_styles": { "type": "string", "maxLength": 65536 }, "owner_scope": { "type": "string", "enum": [ "user", "project", "group", "department", "org" ] }, "owner_id": { "type": "string", "format": "uuid" }, "default_entity_owner_scope": { "type": "string", "enum": [ "creator", "project", "group", "department", "org" ] }, "permission_flags": { "type": "object" }, "settings": { "type": "object" } } }, "Entities_UpdateEntityTypeRequest": { "type": "object", "description": "Body for updating an entity type. At least one field (besides `changelog`) must be provided. Changing `fields` on an entity type that has live entities is validated by the stored procedure; a conflict is returned if the change would break existing data.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2048 }, "icon": { "type": "string", "maxLength": 64 }, "color": { "type": "string", "maxLength": 32, "pattern": "^#[0-9a-fA-F]{3,8}$" }, "parent_uuid": { "type": "string", "format": "uuid", "nullable": true }, "category": { "type": "string", "maxLength": 128 }, "fields": { "type": "array", "items": { "type": "object" } }, "ai_instructions": { "type": "object" }, "relationship_mode": { "type": "string", "enum": [ "open", "restricted" ] }, "html_template": { "type": "string" }, "css_styles": { "type": "string" }, "sample_data": { "type": "string" }, "render_template_full": { "type": "string", "maxLength": 262144 }, "render_template_full_styles": { "type": "string", "maxLength": 65536 }, "render_template_icon": { "type": "string", "maxLength": 262144 }, "render_template_icon_styles": { "type": "string", "maxLength": 65536 }, "owner_scope": { "type": "string", "enum": [ "user", "project", "group", "department", "org" ] }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "default_entity_owner_scope": { "type": "string", "enum": [ "creator", "project", "group", "department", "org" ] }, "permission_flags": { "type": "object" }, "changelog": { "type": "string", "maxLength": 500, "description": "Optional human-readable change note." } } }, "Entities_EntityComment": { "type": "object", "description": "A comment attached to an entity.", "properties": { "id": { "type": "string", "format": "uuid" }, "entity_id": { "type": "string", "format": "uuid" }, "parent_comment_id": { "type": "string", "format": "uuid", "nullable": true }, "user_id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateCommentRequest": { "type": "object", "description": "Body for creating an entity comment.", "required": [ "content" ], "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "Comment text (max 16 384 chars)." }, "parent_comment_id": { "type": "string", "format": "uuid", "description": "Optional parent comment for threaded replies." } } }, "Entities_EntityPermission": { "type": "object", "description": "A five-right access grant on an entity or entity type.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "resource_type": { "type": "string", "enum": [ "entity", "entity_type" ] }, "resource_id": { "type": "string", "format": "uuid", "nullable": true }, "criteria": { "type": "object", "nullable": true }, "subject_scope": { "type": "string", "enum": [ "user", "project", "group", "department", "org" ] }, "subject_id": { "type": "string", "format": "uuid", "nullable": true }, "can_visibility": { "type": "boolean" }, "can_read": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "can_purge": { "type": "boolean" }, "permission_flag": { "type": "string", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateEntityPermissionRequest": { "type": "object", "description": "Body for creating an entity or entity-type permission grant. Exactly one of `resource_id` or `criteria` must be provided.", "additionalProperties": false, "required": [ "resource_type", "subject_scope" ], "properties": { "resource_type": { "type": "string", "enum": [ "entity", "entity_type" ] }, "resource_id": { "type": "string", "format": "uuid", "description": "Specific resource identifier. Mutually exclusive with `criteria`." }, "criteria": { "type": "object", "description": "JSONB criteria for a rule-based grant (org admin only). Mutually exclusive with `resource_id`." }, "subject_scope": { "type": "string", "enum": [ "user", "project", "group", "department", "org" ] }, "subject_id": { "type": "string", "format": "uuid" }, "can_visibility": { "type": "boolean" }, "can_read": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "can_purge": { "type": "boolean" }, "permission_flag": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "Optional named custom permission flag (must match `^[a-z][a-z0-9_]{0,63}$`)." } } }, "Entities_EffectivePermissions": { "type": "object", "description": "Computed five-right effective permissions for the caller (or a specified user) on a specific entity or entity type, including contributing grant sources.", "properties": { "can_visibility": { "type": "boolean" }, "can_read": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "can_purge": { "type": "boolean" }, "sources": { "type": "array", "items": { "type": "object" }, "description": "List of contributing grants that produced the effective rights." } } }, "Entities_EntityMedia": { "type": "object", "description": "Descriptor for a binary media asset attached to an entity field.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Media descriptor identifier. This is the reference the entity field stores." }, "entity_id": { "type": "string", "format": "uuid" }, "field_key": { "type": "string", "description": "Entity field key the media is attached to." }, "content_type": { "type": "string", "description": "Server-determined MIME type (from magic-byte sniff)." }, "byte_size": { "type": "integer", "description": "Binary payload size in bytes." }, "file_name": { "type": "string", "description": "Sanitized display filename." }, "checksum_sha256": { "type": "string", "description": "SHA-256 hex digest of the binary content." }, "created_at": { "type": "string", "format": "date-time" } } }, "Entities_Relationship": { "type": "object", "description": "A directed relationship edge between two entities.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Relationship identifier (UUIDv7)." }, "source_entity_id": { "type": "string", "format": "uuid", "description": "Source (origin) entity." }, "target_entity_id": { "type": "string", "format": "uuid", "description": "Target (destination) entity." }, "relationship_type_id": { "type": "string", "format": "uuid", "description": "The type that defines this edge's semantics." }, "metadata": { "type": "object", "description": "Arbitrary JSONB metadata." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateRelationshipRequest": { "type": "object", "description": "Body for creating a relationship between two entities.", "required": [ "source_entity_id", "target_entity_id", "relationship_type_id" ], "additionalProperties": false, "properties": { "source_entity_id": { "type": "string", "format": "uuid", "description": "Source entity. Must differ from `target_entity_id`." }, "target_entity_id": { "type": "string", "format": "uuid", "description": "Target entity. Must differ from `source_entity_id`." }, "relationship_type_id": { "type": "string", "format": "uuid", "description": "Relationship type identifier." }, "metadata": { "type": "object", "description": "Optional JSONB metadata to attach to the edge." } } }, "Entities_RelationshipType": { "type": "object", "description": "Defines the semantics of a directed relationship type.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Relationship type identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Internal unique name within the organization." }, "forward_label": { "type": "string", "maxLength": 200, "description": "Human-readable label for the source→target direction (e.g. 'blocks')." }, "reverse_label": { "type": "string", "maxLength": 200, "description": "Human-readable label for the target→source direction (e.g. 'blocked by')." }, "description": { "type": "string", "maxLength": 2048, "nullable": true }, "icon": { "type": "string", "maxLength": 200, "nullable": true }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{3,8}$", "nullable": true, "description": "Optional hex color for display (e.g. `#FF5733` or `#F53`)." }, "created_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateRelationshipTypeRequest": { "type": "object", "description": "Body for creating a relationship type.", "required": [ "name", "forward_label", "reverse_label" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "forward_label": { "type": "string", "minLength": 1, "maxLength": 200 }, "reverse_label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2048 }, "icon": { "type": "string", "maxLength": 200 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{3,8}$", "description": "Hex color (e.g. `#FF5733` or `#F53`)." } } }, "Entities_View": { "type": "object", "description": "A saved view configuration (board, list, table, calendar, timeline, or gantt) over a project's entities.", "properties": { "id": { "type": "string", "format": "uuid", "description": "View identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "view_type": { "type": "string", "enum": [ "board", "list", "table", "calendar", "timeline", "gantt" ] }, "config": { "type": "object", "description": "View-type-specific rendering configuration." }, "filters": { "type": "object", "description": "Filter expression applied before rendering." }, "columns": { "type": "array", "description": "Column or field order/visibility config.", "items": { "type": "object" } }, "sort_config": { "type": "object", "nullable": true, "description": "Sort specification." }, "group_by": { "type": "string", "nullable": true, "description": "Field key to group rows by." }, "is_default": { "type": "boolean" }, "is_shared": { "type": "boolean" }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Entities_CreateViewRequest": { "type": "object", "description": "Body for creating a view. Only `name` is required; `view_type` defaults to `list` if omitted.", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "view_type": { "type": "string", "enum": [ "board", "list", "table", "calendar", "timeline", "gantt" ] }, "project_id": { "type": "string", "format": "uuid" }, "config": { "type": "object" }, "filters": { "type": "object" }, "columns": { "type": "array", "items": { "type": "object" } }, "sort_config": { "type": "object" }, "group_by": { "type": "string" }, "is_default": { "type": "boolean" }, "is_shared": { "type": "boolean" }, "metadata": { "type": "object" } } }, "Entities_UpdateViewRequest": { "type": "object", "description": "Body for updating a view. At least one field must be provided.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "config": { "type": "object" }, "filters": { "type": "object" }, "columns": { "type": "array", "items": { "type": "object" } }, "sort_config": { "type": "object", "nullable": true }, "group_by": { "type": "string", "nullable": true }, "is_default": { "type": "boolean" }, "is_shared": { "type": "boolean" }, "metadata": { "type": "object" } } }, "Entities_PipelineConfig": { "type": "object", "description": "Root CI/CD pipeline configuration for a project.", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "org_repo_id": { "type": "string", "format": "uuid", "description": "Connected repository identifier." }, "deploy_connection_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional deployment connection override." }, "default_backend": { "type": "string", "maxLength": 64, "nullable": true }, "allow_free_form": { "type": "boolean" }, "is_active": { "type": "boolean" }, "environments": { "type": "array", "items": { "$ref": "#/components/schemas/Entities_PipelineEnvironment" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Entities_UpsertPipelineConfigRequest": { "type": "object", "description": "Body for creating or updating the pipeline root configuration.", "required": [ "org_repo_id" ], "additionalProperties": false, "properties": { "org_repo_id": { "type": "string", "format": "uuid", "description": "Connected repository identifier. Required." }, "deploy_connection_id": { "type": "string", "format": "uuid", "nullable": true }, "default_backend": { "type": "string", "maxLength": 64, "nullable": true }, "allow_free_form": { "type": "boolean" }, "is_active": { "type": "boolean" } } }, "Entities_PipelineEnvironment": { "type": "object", "description": "A pipeline environment definition within a project pipeline.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "env_id": { "type": "string", "format": "uuid", "description": "The logical environment this pipeline env targets." }, "rank": { "type": "integer", "minimum": 0, "description": "Ordering of environments in the pipeline (0 = first)." }, "branch": { "type": "string", "maxLength": 255 }, "working_dir": { "type": "string", "maxLength": 512, "nullable": true }, "deploy_commands": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "Ordered list of shell command arrays to run." }, "container_size": { "type": "string", "maxLength": 32, "nullable": true }, "backend": { "type": "string", "maxLength": 64, "nullable": true }, "egress_allowlist": { "type": "array", "items": { "type": "string", "maxLength": 255 } }, "is_protected": { "type": "boolean" }, "auto_deploy_on_push": { "type": "boolean" } } }, "Entities_UpsertPipelineEnvironmentItem": { "type": "object", "description": "A single pipeline environment entry in the PUT /pipeline/environments array.", "required": [ "name", "env_id", "rank", "branch" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "description": "If provided, identifies an existing environment to update." }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "env_id": { "type": "string", "format": "uuid" }, "rank": { "type": "integer", "minimum": 0 }, "branch": { "type": "string", "minLength": 1, "maxLength": 255 }, "working_dir": { "type": "string", "minLength": 1, "maxLength": 512 }, "deploy_commands": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "container_size": { "type": "string", "maxLength": 32 }, "backend": { "type": "string", "maxLength": 64, "nullable": true }, "egress_allowlist": { "type": "array", "items": { "type": "string", "maxLength": 255 } }, "is_protected": { "type": "boolean" }, "auto_deploy_on_push": { "type": "boolean" } } }, "Entities_PipelineRun": { "type": "object", "description": "A single pipeline deploy or promotion run.", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "pipeline_env_id": { "type": "string", "format": "uuid" }, "triggered_by": { "type": "string", "format": "uuid" }, "run_type": { "type": "string", "enum": [ "deploy", "promote" ], "description": "Whether this is a direct deploy or a promotion." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "awaiting_approval" ] }, "commit_sha": { "type": "string", "nullable": true, "description": "The commit SHA being deployed." }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Entities_UpdateTemplateRequest": { "type": "object", "description": "Body for updating a project template. At least one field must be provided.", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "maxLength": 10000, "nullable": true, "description": "Set to `null` to clear. Content is screened by the platform content-safety gate." }, "config": { "type": "object", "description": "Replaces the template configuration." }, "changelog": { "type": "string", "maxLength": 5000, "description": "Optional human-readable change note for this version." } } }, "Projects_Project": { "type": "object", "description": "A project record.", "required": [ "id", "org_id", "name", "slug", "is_active", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Platform-assigned project identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "name": { "type": "string", "description": "Display name (1–255 chars)." }, "slug": { "type": "string", "description": "URL-safe slug (unique per org+environment). Auto-generated from the name when not supplied." }, "description": { "type": [ "string", "null" ], "description": "Optional summary (≤4096 chars)." }, "prefix": { "type": [ "string", "null" ], "description": "Optional short prefix used for human-friendly entity ids." }, "visibility": { "type": "string", "enum": [ "public", "private", "internal" ], "description": "Project visibility." }, "category_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional project category." }, "owner_scope": { "type": "string", "description": "Ownership scope (e.g. `organization`)." }, "is_active": { "type": "boolean", "description": "False when archived or soft-deleted." }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "User who created the project." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp (assigned by the platform)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last-update timestamp." }, "settings": { "type": "object", "additionalProperties": true, "description": "Project settings object." } } }, "Projects_CreateProjectRequest": { "type": "object", "additionalProperties": false, "description": "Create-project request body. `org_id` is taken from the session and is rejected if supplied (strict object).", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Project name." }, "slug": { "type": "string", "minLength": 3, "maxLength": 63, "description": "Optional canonical slug (lowercase alphanumeric with single internal hyphens, not UUID-shaped). Auto-generated from the name when omitted; reserved words are rejected." }, "description": { "type": "string", "maxLength": 4096, "description": "Optional project summary." }, "settings": { "type": "object", "additionalProperties": true, "description": "Optional bounded settings object." } } }, "Projects_UpdateProjectRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Update-project request body. At least one field must be present. All fields optional; `description` accepts null to clear.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New name." }, "slug": { "type": "string", "minLength": 3, "maxLength": 63, "description": "New canonical slug." }, "description": { "type": [ "string", "null" ], "maxLength": 4096, "description": "New description; null clears it." }, "visibility": { "type": "string", "enum": [ "public", "private", "internal" ], "description": "New visibility." }, "is_active": { "type": "boolean", "description": "Archive (false) / unarchive (true)." }, "settings": { "type": "object", "additionalProperties": true, "description": "Replacement settings object." } } }, "Projects_AddMemberRequest": { "type": "object", "additionalProperties": false, "description": "Add-member request body.", "required": [ "user_id", "role" ], "properties": { "user_id": { "type": "string", "format": "uuid", "description": "User to add (UUIDv7)." }, "role": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Role to grant within the project." } } }, "Projects_ProjectMember": { "type": "object", "description": "A project membership record.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "Member user id." }, "project_id": { "type": "string", "format": "uuid", "description": "Project id." }, "role": { "type": "string", "description": "Member's role within the project." }, "display_name": { "type": [ "string", "null" ], "description": "Member display name." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Member email." }, "created_at": { "type": "string", "format": "date-time", "description": "When the membership was created." } } }, "Releases_Release": { "type": "object", "description": "A SaaS package release record.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Release identifier (UUIDv7)." }, "package_id": { "type": "string", "format": "uuid", "description": "Owning SaaS package identifier." }, "release_name": { "type": "string", "maxLength": 200, "description": "Human-readable release name." }, "release_notes": { "type": [ "string", "null" ], "maxLength": 10000, "description": "Optional markdown release notes." }, "status": { "type": "string", "enum": [ "draft", "testing", "approved", "rejected", "archived" ], "description": "Current lifecycle status." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Releases_CreateReleaseRequest": { "type": "object", "required": [ "release_name" ], "additionalProperties": false, "properties": { "release_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable release name, unique within the package." }, "release_notes": { "type": "string", "maxLength": 10000, "description": "Optional markdown release notes." } } }, "Releases_UpdateReleaseStatusRequest": { "type": "object", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "testing", "approved", "rejected", "archived" ], "description": "Target status. `draft` is omitted because you cannot manually transition back to draft." }, "reason": { "type": "string", "maxLength": 4000, "description": "Optional reason for the transition (required for `rejected` by convention)." } } }, "Releases_DeployReleaseRequest": { "type": "object", "required": [ "environment" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ], "description": "Target deployment environment." }, "notes": { "type": "string", "maxLength": 5000, "description": "Optional deployment notes." }, "rollout_strategy": { "type": "string", "enum": [ "immediate", "targeted", "percentage", "progressive" ], "description": "Rollout strategy. Defaults to `immediate` when omitted." }, "target_org_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Specific organization IDs for `targeted` strategy." }, "target_percentage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Rollout percentage for the `percentage` strategy." }, "rollout_stages": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_RolloutStage" }, "minItems": 1, "maxItems": 20, "description": "Stage definitions for `progressive` strategy (1–20)." } } }, "Releases_RolloutStage": { "type": "object", "description": "A single stage in a progressive rollout plan.", "properties": { "target_percentage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Target rollout percentage at this stage." }, "wait_hours": { "type": "integer", "minimum": 0, "description": "Hours to wait before automatically advancing to the next stage. Defaults to 0." } } }, "Releases_CreateApprovalPolicyRequest": { "type": "object", "required": [ "category", "name", "rules" ], "description": "Request body for creating a release approval policy. Policies have a maximum request body size of 8 KiB.", "additionalProperties": false, "properties": { "category": { "type": "string", "enum": [ "staging_promotion", "preprod_promotion", "production_deployment", "security_review", "compliance_review", "rollback_authorization" ], "description": "Policy category." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Policy name." }, "description": { "type": "string", "maxLength": 2000, "description": "Optional policy description." }, "rules": { "$ref": "#/components/schemas/Releases_ApprovalConditionNode", "description": "Root condition node. Max depth 5." } } }, "Releases_ApprovalConditionNode": { "description": "A node in the approval condition tree. The top-level `rules` field must be a branch node (`operator` + `conditions`). Leaf nodes specify a specific_users, role, group, or cross_role condition. Maximum tree depth is 5; each branch may have 1–10 children.", "oneOf": [ { "type": "object", "required": [ "operator", "conditions" ], "description": "Branch node — combines child conditions with AND or OR.", "properties": { "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_ApprovalConditionNode" }, "minItems": 1, "maxItems": 10 } } }, { "type": "object", "required": [ "type", "user_ids", "required_count" ], "description": "Leaf — requires approvals from specific named users.", "properties": { "type": { "type": "string", "enum": [ "specific_users" ] }, "user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 20 }, "required_count": { "type": "integer", "minimum": 1 }, "label": { "type": "string", "maxLength": 200 } } }, { "type": "object", "required": [ "type", "role_key", "required_count" ], "description": "Leaf — requires approvals from members of a specific role.", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "role_key": { "type": "string", "minLength": 1, "maxLength": 50 }, "required_count": { "type": "integer", "minimum": 1 }, "label": { "type": "string", "maxLength": 200 } } }, { "type": "object", "required": [ "type", "group_ids", "required_count" ], "description": "Leaf — requires approvals from one or more groups.", "properties": { "type": { "type": "string", "enum": [ "group" ] }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 20 }, "required_count": { "type": "integer", "minimum": 1 }, "from_each": { "type": "boolean" }, "label": { "type": "string", "maxLength": 200 } } }, { "type": "object", "required": [ "type", "role_keys", "min_roles_represented", "min_total_approvals" ], "description": "Leaf — requires approvals from a minimum number of distinct roles (separation-of-duties).", "properties": { "type": { "type": "string", "enum": [ "cross_role" ] }, "role_keys": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 20 }, "min_roles_represented": { "type": "integer", "minimum": 1 }, "min_total_approvals": { "type": "integer", "minimum": 1 }, "label": { "type": "string", "maxLength": 200 } } } ] }, "Releases_ApprovalPolicy": { "type": "object", "description": "A release approval policy record.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "category": { "type": "string", "enum": [ "staging_promotion", "preprod_promotion", "production_deployment", "security_review", "compliance_review", "rollback_authorization" ] }, "name": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "rules": { "$ref": "#/components/schemas/Releases_ApprovalConditionNode" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Releases_CreateRolloutRequest": { "type": "object", "required": [ "deployment_id", "strategy" ], "additionalProperties": false, "description": "Request body to create a rollout plan.", "properties": { "deployment_id": { "type": "string", "format": "uuid", "description": "Deployment identifier to roll out." }, "strategy": { "type": "string", "enum": [ "immediate", "targeted", "percentage", "progressive" ], "description": "Rollout strategy." }, "target_org_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 1000, "description": "Specific organizations for `targeted` strategy (max 1000)." }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_RolloutStage" }, "maxItems": 20, "description": "Stage definitions for `progressive` strategy (max 20)." } } }, "Releases_RolloutActionRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 2000, "description": "Optional reason for the rollout action (pause, resume, cancel)." } } }, "Releases_ProductUpsertRequest": { "type": "object", "required": [ "base_tool", "display_name" ], "additionalProperties": false, "description": "Request body to create or update a release product.", "properties": { "base_tool": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Base tool identifier for this product." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable product name." }, "branding_config_id": { "type": "string", "format": "uuid", "description": "Optional branding config identifier." }, "custom_domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Optional custom domain for release downloads (max 253 chars)." }, "data_residency": { "type": "string", "enum": [ "us", "eu" ], "description": "Data residency region for release artefacts. Optional." } } }, "Releases_Product": { "type": "object", "description": "A release product record.", "properties": { "slug": { "type": "string", "description": "Product slug." }, "org_id": { "type": "string", "format": "uuid" }, "base_tool": { "type": "string" }, "display_name": { "type": "string" }, "branding_config_id": { "type": [ "string", "null" ], "format": "uuid" }, "custom_domain": { "type": [ "string", "null" ], "maxLength": 253 }, "data_residency": { "type": "string", "enum": [ "us", "eu" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_PublishStartRequest": { "type": "object", "required": [ "version" ], "additionalProperties": false, "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Version string (e.g. `1.2.3`)." }, "channel": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Distribution channel (e.g. `stable`, `beta`, `nightly`). Optional." }, "publisher_token_hash_hex": { "type": "string", "description": "Hex-encoded hash of the publisher token for this publish flow. Optional.", "pattern": "^[0-9a-fA-F]+$" } } }, "Releases_StagingVersion": { "type": "object", "description": "A staged (not-yet-finalized) release version record.", "properties": { "id": { "type": "string", "format": "uuid" }, "product_slug": { "type": "string" }, "version": { "type": "string", "maxLength": 100 }, "channel": { "type": "string", "maxLength": 50 }, "state": { "type": "string", "enum": [ "staging", "complete", "finalized", "yanked" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_AddArtefactRequest": { "type": "object", "required": [ "os", "arch", "r2_key", "archive_format", "sha256_hex", "size_bytes" ], "additionalProperties": false, "properties": { "os": { "type": "string", "description": "Target operating system (e.g. `linux`, `darwin`, `windows`)." }, "arch": { "type": "string", "description": "Target CPU architecture (e.g. `x86_64`, `aarch64`)." }, "r2_key": { "type": "string", "maxLength": 1024, "description": "R2 object key where the binary was uploaded." }, "archive_format": { "type": "string", "description": "Archive format (e.g. `zip`, `tar.gz`)." }, "sha256_hex": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$", "description": "Lowercase hex-encoded SHA-256 of the artefact binary (exactly 64 chars)." }, "size_bytes": { "type": "integer", "minimum": 0, "description": "Artefact file size in bytes." }, "os_signature": { "type": "object", "description": "Optional OS-level code-signing signature object (structure is OS-dependent).", "additionalProperties": true } } }, "Releases_PublishCompleteRequest": { "type": "object", "additionalProperties": false, "properties": { "release_notes_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "URL to the release notes page (max 2048 chars)." }, "min_supported_os": { "type": "object", "description": "Minimum OS version map (e.g. `{windows: '10', macos: '12.0'}`).", "additionalProperties": true }, "required_upgrade": { "type": "boolean", "description": "Whether this is a forced upgrade. Clients below this version will be blocked." } } }, "Releases_PublishFinalizeRequest": { "type": "object", "required": [ "manifest_sha256_hex", "manifest_sig_hex" ], "additionalProperties": false, "properties": { "manifest_sha256_hex": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$", "description": "Hex-encoded SHA-256 of the release manifest (exactly 64 chars)." }, "manifest_sig_hex": { "type": "string", "pattern": "^[0-9a-fA-F]{128}$", "description": "Hex-encoded Ed25519 signature over the manifest hash (exactly 128 chars / 64 bytes)." } } }, "Releases_PromoteRequest": { "type": "object", "required": [ "version", "target_channel" ], "additionalProperties": false, "properties": { "version": { "type": "string", "maxLength": 100, "description": "Version string to promote." }, "target_channel": { "type": "string", "maxLength": 50, "description": "Destination channel (e.g. `stable`)." } } }, "Releases_YankRequest": { "type": "object", "required": [ "product_slug", "version", "reason" ], "additionalProperties": false, "properties": { "product_slug": { "type": "string", "description": "Product slug to identify the release." }, "version": { "type": "string", "maxLength": 100, "description": "Version string to yank." }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Mandatory reason for yanking (audit trail)." } } }, "Releases_SetRolloutRequest": { "type": "object", "required": [ "product_slug", "version", "percentage" ], "additionalProperties": false, "properties": { "product_slug": { "type": "string", "description": "Product slug." }, "version": { "type": "string", "maxLength": 100, "description": "Version string." }, "percentage": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Rollout percentage. `0` pauses rollout; `100` completes it." } } }, "Releases_SigningKeyCreateRequest": { "type": "object", "required": [ "key_id", "public_key_hex" ], "additionalProperties": false, "properties": { "key_id": { "type": "string", "maxLength": 200, "description": "Human-readable key identifier (e.g. `prod-2025-01`)." }, "public_key_hex": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$", "description": "Hex-encoded 32-byte Ed25519 public key (exactly 64 hex chars)." }, "signed_by_key_id": { "type": "string", "maxLength": 200, "description": "Optional key_id of the predecessor key that signs the succession." }, "successor_signature_hex": { "type": "string", "pattern": "^[0-9a-fA-F]{128}$", "description": "Optional hex-encoded 64-byte Ed25519 signature of this key's public_key_hex by the `signed_by_key_id` key (exactly 128 hex chars)." } } }, "Releases_SigningKeyRevokeRequest": { "type": "object", "required": [ "reason" ], "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Mandatory reason for revocation (audit trail)." } } }, "Releases_SigningKey": { "type": "object", "description": "A release signing key record.", "properties": { "key_id": { "type": "string", "maxLength": 200 }, "org_id": { "type": "string", "format": "uuid" }, "public_key_hex": { "type": "string" }, "is_active": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "signed_by_key_id": { "type": [ "string", "null" ] }, "successor_signature_hex": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_CurrentVersion": { "type": "object", "description": "The current published release version for a product/channel.", "properties": { "version": { "type": "string" }, "channel": { "type": "string" }, "release_notes_url": { "type": [ "string", "null" ] }, "required_upgrade": { "type": "boolean" }, "artefacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "manifest_sha256_hex": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" } } }, "Releases_DeploymentConfigUpsertRequest": { "type": "object", "required": [ "repo_id", "vault_ref", "dek_secret_ref" ], "additionalProperties": false, "description": "Request body to create or update a deployment configuration.", "properties": { "repo_id": { "type": "string", "format": "uuid", "description": "Repository identifier (UUIDv7)." }, "vault_ref": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Vault reference for secret injection." }, "dek_secret_ref": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Data-encryption key secret reference." }, "webhook_secret_ref": { "type": "string", "maxLength": 255, "description": "Optional webhook signing secret reference." }, "dek_epoch": { "type": "integer", "minimum": 1, "description": "Optional DEK epoch for key rotation tracking (min 1)." } } }, "Releases_DeploymentEnvironmentUpsertRequest": { "type": "object", "required": [ "config_id", "name", "branch" ], "additionalProperties": false, "description": "Request body to create or update a deployment environment.", "properties": { "config_id": { "type": "string", "format": "uuid", "description": "Parent deployment config identifier." }, "name": { "type": "string", "maxLength": 64, "description": "Environment name (e.g. `production`, `staging`)." }, "branch": { "type": "string", "maxLength": 255, "description": "Git branch to deploy from." }, "working_dir": { "type": "string", "maxLength": 512, "description": "Optional working directory within the repository." }, "deploy_commands": { "type": "array", "items": { "type": "string" }, "maxItems": 64, "description": "Ordered list of deploy commands to execute (max 64)." }, "container_size": { "type": "string", "enum": [ "basic", "standard-1", "standard-2", "standard-3", "standard-4" ], "description": "Deploy container size." }, "exposed_secret_keys": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 128, "description": "List of secret item UUIDs to inject as environment variables (max 128)." }, "github_token_secret_ref": { "type": "string", "description": "Optional GitHub token secret reference for private repo access." }, "egress_allowlist": { "type": "array", "items": { "type": "string" }, "maxItems": 64, "description": "Optional network egress allowlist (max 64 entries)." }, "auto_deploy": { "type": "boolean", "description": "Whether to auto-trigger a deploy on branch push." } } }, "Releases_DeploymentApprovalPolicyRequest": { "type": "object", "required": [ "environment", "role_keys" ], "additionalProperties": false, "description": "Request body to set a deployment approval policy.", "properties": { "environment": { "type": "string", "enum": [ "production", "preprod" ], "description": "Target deployment environment." }, "role_keys": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "minItems": 1, "maxItems": 32, "description": "Role keys that are eligible approvers (1–32, each max 64 chars)." }, "min_total_approvals": { "type": "integer", "minimum": 2, "description": "Minimum total approvals required (minimum 2). Optional." }, "min_roles_represented": { "type": "integer", "minimum": 2, "description": "Minimum distinct roles that must be represented in the approvals (minimum 2). Optional." } } }, "Releases_DeploymentApproveRequest": { "type": "object", "required": [ "environment_id", "commit_sha", "action" ], "additionalProperties": false, "properties": { "environment_id": { "type": "string", "format": "uuid", "description": "Deployment environment identifier." }, "commit_sha": { "type": "string", "maxLength": 255, "description": "Commit SHA being approved." }, "action": { "type": "string", "enum": [ "approve", "reject" ], "description": "Approval decision." } } }, "Releases_DeploymentSoloModeRequest": { "type": "object", "required": [ "config_id" ], "additionalProperties": false, "properties": { "config_id": { "type": "string", "format": "uuid", "description": "Deployment config identifier." }, "enabled": { "type": "boolean", "description": "Whether to enable solo-operator mode. Optional; SP applies its own default when omitted." } } }, "Releases_DeploymentRunStartRequest": { "type": "object", "required": [ "environment_id", "commit_sha" ], "additionalProperties": false, "properties": { "environment_id": { "type": "string", "format": "uuid", "description": "Deployment environment identifier." }, "commit_sha": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Commit SHA to deploy." }, "trigger": { "type": "string", "enum": [ "manual", "webhook", "poller", "retry" ], "description": "What triggered this run. Optional." }, "instance_token_id": { "type": "string", "format": "uuid", "description": "Optional pre-created instance token identifier." } } }, "Releases_DeployRunResult": { "type": "object", "description": "Result of starting a deployment run.", "properties": { "run_id": { "type": "string", "format": "uuid" }, "orchestrated": { "type": "boolean", "description": "`true` if the deploy container was successfully started." }, "orchestration_error": { "type": [ "string", "null" ], "description": "Non-fatal message if the container could not be started. The run record still exists and can be retried." } } }, "Releases_DeploymentRunEventRequest": { "type": "object", "required": [ "client_event_id" ], "additionalProperties": false, "description": "At least `client_event_id` is required; all other fields are optional.", "properties": { "client_event_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-generated idempotency key for this event." }, "level": { "type": "string", "enum": [ "info", "warn", "error" ], "description": "Log level. Optional." }, "phase": { "type": "string", "maxLength": 64, "description": "Deployment phase (e.g. `checkout`, `build`, `deploy`). Optional." }, "error_class": { "type": "string", "maxLength": 64, "description": "Error class or type for error-level events. Optional." }, "sqlstate": { "type": "string", "maxLength": 5, "description": "5-char PostgreSQL SQLSTATE code for DB errors. Optional." }, "failing_migration": { "type": "string", "maxLength": 128, "description": "Migration filename that triggered the failure. Optional." }, "wrangler_binding": { "type": "string", "maxLength": 128, "description": "Cloudflare wrangler binding name involved in a failure. Optional." }, "message": { "type": "string", "maxLength": 2048, "description": "Event message. Optional." }, "status": { "type": "string", "enum": [ "queued", "provisioning", "running", "succeeded", "failed", "cancelled" ], "description": "Overall run status at the time of this event. Terminal statuses (`succeeded`, `failed`, `cancelled`) revoke the instance token. Optional." } } }, "Releases_FeatureFlag": { "type": "object", "description": "A system feature flag record.", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "maxLength": 128, "description": "URL-safe slug identifier." }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 4096 }, "is_enabled": { "type": "boolean" }, "rollout_status": { "type": "string", "enum": [ "off", "org", "alpha", "beta", "ga" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_FeatureFlagUpsertRequest": { "type": "object", "additionalProperties": false, "description": "At least one field must be present. When `slug` identifies an existing flag, it is updated; otherwise a new flag is created.", "properties": { "slug": { "type": "string", "maxLength": 128, "description": "Unique slug (max 128 chars)." }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 4096 }, "is_enabled": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true } } }, "Releases_FeatureFlagStatusSetRequest": { "type": "object", "required": [ "rollout_status" ], "additionalProperties": false, "description": "Set the rollout tier. Exactly one of `feature_flag_id` or `feature_flag_slug` is required.", "properties": { "feature_flag_id": { "type": "string", "format": "uuid", "description": "Feature flag identifier." }, "feature_flag_slug": { "type": "string", "maxLength": 128, "description": "Feature flag slug." }, "rollout_status": { "type": "string", "enum": [ "off", "org", "alpha", "beta", "ga" ], "description": "New rollout tier." } } }, "Releases_FeatureFlagChannelOrgRequest": { "type": "object", "required": [ "org_id", "channel", "member" ], "additionalProperties": false, "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Organization identifier." }, "channel": { "type": "string", "enum": [ "alpha", "beta" ], "description": "Release channel." }, "member": { "type": "boolean", "description": "`true` to add, `false` to remove." }, "reason": { "type": "string", "maxLength": 2000, "description": "Optional reason for the change (audit trail)." } } }, "Releases_FeatureFlagOrgEntitlementRequest": { "type": "object", "required": [ "org_id" ], "additionalProperties": false, "description": "Set or clear a per-org feature flag override. Exactly one of `feature_flag_id` or `feature_flag_slug` is required unless `clear` is `true`.", "properties": { "org_id": { "type": "string", "format": "uuid" }, "feature_flag_id": { "type": "string", "format": "uuid" }, "feature_flag_slug": { "type": "string", "maxLength": 128 }, "is_enabled": { "type": "boolean", "description": "Override value. Required unless `clear` is `true`." }, "reason": { "type": "string", "maxLength": 2000, "description": "Optional reason for the override." }, "clear": { "type": "boolean", "description": "When `true`, removes the per-org override entirely." } } }, "Releases_FeatureFlagUpdateRequest": { "type": "object", "additionalProperties": false, "description": "Partial update of a system feature flag definition. At least one field must be provided.", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 128, "description": "URL-safe slug for the flag." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable flag name." }, "description": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Optional description of the flag's purpose." }, "is_enabled": { "type": "boolean", "description": "Whether the flag is currently enabled system-wide." }, "metadata": { "type": "object", "description": "Arbitrary JSON metadata (max 8 KiB)." } } }, "Releases_Campaign": { "type": "object", "description": "A marketing or lifecycle campaign.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "campaign_type": { "type": "string", "enum": [ "drip", "sequence", "one_shot" ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_CampaignCreateRequest": { "type": "object", "required": [ "name", "campaign_type" ], "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "campaign_type": { "type": "string", "enum": [ "drip", "sequence", "one_shot" ] }, "trigger": { "type": "object", "additionalProperties": true, "description": "Trigger configuration JSON." }, "is_active": { "type": "boolean", "description": "Whether the campaign is active. Defaults to `false`." }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } } }, "Releases_CampaignUpdateRequest": { "type": "object", "additionalProperties": false, "description": "All fields optional.", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "campaign_type": { "type": "string", "enum": [ "drip", "sequence", "one_shot" ] }, "trigger": { "type": "object", "additionalProperties": true }, "is_active": { "type": "boolean" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } } }, "Releases_CampaignStep": { "type": "object", "description": "A single step within a campaign.", "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 200 }, "step_type": { "type": "string", "enum": [ "email", "notification", "delay", "condition", "action" ] }, "position": { "type": "integer", "minimum": 0, "description": "0-based display order." }, "config": { "type": "object", "additionalProperties": true }, "delay_seconds": { "type": "integer", "minimum": 0 }, "template_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "Releases_CampaignStepCreateRequest": { "type": "object", "required": [ "campaign_id", "name", "step_type", "position" ], "additionalProperties": false, "properties": { "campaign_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 200 }, "step_type": { "type": "string", "enum": [ "email", "notification", "delay", "condition", "action" ] }, "position": { "type": "integer", "minimum": 0, "description": "0-based position. Converted to 1-based `step_number` internally." }, "config": { "type": "object", "additionalProperties": true }, "delay_seconds": { "type": "integer", "minimum": 0 }, "template_id": { "type": "string", "format": "uuid" }, "metadata": { "type": "object", "additionalProperties": true } } }, "Releases_CampaignStepUpdateRequest": { "type": "object", "additionalProperties": false, "description": "Partial update of a campaign step. At least one field must be provided.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Step display name." }, "position": { "type": "integer", "minimum": 0, "description": "0-based position in the step sequence (converted to 1-based `step_number` internally)." }, "config": { "type": "object", "additionalProperties": true, "description": "Action configuration for the step." }, "delay_seconds": { "type": "integer", "minimum": 0, "description": "Delay before the step executes, in seconds (converted to `delay_minutes` internally)." }, "template_id": { "type": "string", "format": "uuid", "description": "Optional linked template identifier." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Arbitrary metadata / conditions object." } } }, "Releases_CampaignEnrollmentRequest": { "type": "object", "required": [ "campaign_id", "target_user_id" ], "additionalProperties": false, "properties": { "campaign_id": { "type": "string", "format": "uuid" }, "target_user_id": { "type": "string", "format": "uuid", "description": "User to enroll." }, "trigger_data": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true } } }, "Releases_CampaignEnrollment": { "type": "object", "description": "A campaign enrollment record.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "format": "uuid" }, "entity_id": { "type": "string", "format": "uuid", "description": "Enrolled entity identifier (user ID)." }, "entity_type": { "type": "string", "description": "Entity type (`user`)." }, "status": { "type": "string", "enum": [ "active", "completed", "paused", "cancelled", "failed" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_AutomationRule": { "type": "object", "description": "An automation rule record.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "trigger_type": { "type": "string", "maxLength": 100 }, "trigger_config": { "type": "object", "additionalProperties": true }, "action_type": { "type": "string", "maxLength": 100 }, "action_config": { "type": "object", "additionalProperties": true }, "is_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_AutomationRuleCreateRequest": { "type": "object", "required": [ "name", "trigger_type", "trigger_config", "action_type", "action_config" ], "additionalProperties": false, "description": "Validation rules: `webhook` action requires HTTPS `url` and `method` in `action_config`; `run_ai_session` action requires non-empty `prompt`; `cron` trigger requires a 5-field `expression` in `trigger_config`.", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "trigger_type": { "type": "string", "maxLength": 100 }, "trigger_config": { "type": "object", "additionalProperties": true }, "action_type": { "type": "string", "maxLength": 100 }, "action_config": { "type": "object", "additionalProperties": true }, "is_enabled": { "type": "boolean" } } }, "Releases_AutomationRuleUpdateRequest": { "type": "object", "additionalProperties": false, "description": "All fields optional. Same `action_config`/`trigger_config` validation rules as create apply.", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "trigger_type": { "type": "string", "maxLength": 100 }, "trigger_config": { "type": "object", "additionalProperties": true }, "action_type": { "type": "string", "maxLength": 100 }, "action_config": { "type": "object", "additionalProperties": true }, "is_enabled": { "type": "boolean" } } }, "Releases_TimeTrigger": { "type": "object", "description": "A cron-based time trigger record.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 200 }, "cron_expression": { "type": "string", "description": "5-field cron expression (minute hour day-of-month month day-of-week)." }, "action_type": { "type": "string", "maxLength": 100 }, "action_config": { "type": "object", "additionalProperties": true }, "is_enabled": { "type": "boolean" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_TimeTriggerCreateRequest": { "type": "object", "required": [ "name", "cron_expression", "action_type", "action_config" ], "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "cron_expression": { "type": "string", "description": "Valid 5-field cron expression." }, "action_type": { "type": "string", "maxLength": 100 }, "action_config": { "type": "object", "additionalProperties": true }, "is_enabled": { "type": "boolean" }, "next_run_at": { "type": "string", "format": "date-time" } } }, "Releases_TimeTriggerUpdateRequest": { "type": "object", "additionalProperties": false, "description": "All fields optional.", "properties": { "name": { "type": "string", "maxLength": 200 }, "cron_expression": { "type": "string", "description": "Valid 5-field cron expression." }, "action_type": { "type": "string", "maxLength": 100 }, "action_config": { "type": "object", "additionalProperties": true }, "is_enabled": { "type": "boolean" }, "next_run_at": { "type": "string", "format": "date-time" } } }, "Releases_ApprovalWorkflow": { "type": "object", "description": "An approval workflow record.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "entity_type_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] }, "trigger_type": { "type": "string", "enum": [ "manual", "event", "schedule", "webhook", "condition" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_WorkflowStep" } }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_WorkflowCreateRequest": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "entity_type_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] }, "trigger_type": { "type": "string", "enum": [ "manual", "event", "schedule", "webhook", "condition" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_WorkflowStepCreateRequest" }, "maxItems": 100, "description": "Up to 100 steps can be provided at creation time." } } }, "Releases_WorkflowUpdateRequest": { "type": "object", "additionalProperties": false, "description": "At least one non-`changelog` field must be provided.", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "entity_type_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] }, "trigger_type": { "type": "string", "enum": [ "manual", "event", "schedule", "webhook", "condition" ] }, "changelog": { "type": "string", "maxLength": 500, "description": "Optional change summary for audit purposes only (max 500 chars). Not a substitute for a data-field update." } } }, "Releases_WorkflowState": { "type": "object", "description": "A workflow state record representing a lifecycle position.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "7-char hex color code." }, "position": { "type": "integer", "minimum": 0 }, "is_initial": { "type": "boolean" }, "is_terminal": { "type": "boolean" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_WorkflowStateCreateRequest": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "7-char hex color code (e.g. `#4CAF50`). Optional." }, "position": { "type": "integer", "minimum": 0, "description": "0-based display order. Optional." }, "is_initial": { "type": "boolean" }, "is_terminal": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true } } }, "Releases_WorkflowStep": { "type": "object", "description": "A single state-transition step in an approval workflow.", "properties": { "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "from_state_id": { "type": "string", "format": "uuid" }, "to_state_id": { "type": "string", "format": "uuid" }, "required_role": { "type": [ "string", "null" ], "maxLength": 200 }, "required_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "sort_order": { "type": "integer" } } }, "Releases_WorkflowStepCreateRequest": { "type": "object", "required": [ "from_state_id", "to_state_id" ], "additionalProperties": false, "properties": { "from_state_id": { "type": "string", "format": "uuid", "description": "Source workflow state." }, "to_state_id": { "type": "string", "format": "uuid", "description": "Target workflow state." }, "required_role": { "type": "string", "maxLength": 200, "description": "Role required to execute this transition." }, "required_group_id": { "type": "string", "format": "uuid", "description": "Optional group required to execute this transition." } } }, "Releases_WorkflowStepUpdateRequest": { "type": "object", "additionalProperties": false, "description": "At least one non-`changelog` field must be provided.", "properties": { "from_state_id": { "type": "string", "format": "uuid" }, "to_state_id": { "type": "string", "format": "uuid" }, "required_role": { "type": [ "string", "null" ], "maxLength": 200 }, "required_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "sort_order": { "type": "integer" }, "changelog": { "type": "string", "maxLength": 500, "description": "Optional change summary for audit purposes only (max 500 chars)." } } }, "Releases_Changeset": { "type": "object", "description": "A changeset grouping related changes for review.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 500 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "changeset_type": { "type": "string", "enum": [ "feature", "bugfix", "hotfix", "refactor", "config" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "critical" ] }, "status": { "type": "string", "description": "Current lifecycle status." }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_Change" } }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_ChangesetCreateRequest": { "type": "object", "required": [ "title" ], "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "maxLength": 5000 }, "project_id": { "type": "string", "format": "uuid" }, "changeset_type": { "type": "string", "enum": [ "feature", "bugfix", "hotfix", "refactor", "config" ], "description": "Defaults to `feature` when omitted." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "critical" ], "description": "Defaults to `normal` when omitted." }, "metadata": { "type": "object", "additionalProperties": true } } }, "Releases_ChangesetUpdateRequest": { "type": "object", "additionalProperties": false, "description": "All fields optional. The `status` field is not permitted here — use lifecycle endpoints.", "properties": { "title": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "maxLength": 5000 }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "critical" ] }, "metadata": { "type": "object", "additionalProperties": true } } }, "Releases_Change": { "type": "object", "description": "A single resource change within a changeset.", "properties": { "id": { "type": "string", "format": "uuid" }, "changeset_id": { "type": "string", "format": "uuid" }, "change_type": { "type": "string", "enum": [ "create", "update", "delete", "move", "rename" ] }, "resource_type": { "type": "string", "maxLength": 100 }, "resource_id": { "type": [ "string", "null" ], "format": "uuid" }, "before_state": { "type": [ "object", "null" ], "additionalProperties": true }, "after_state": { "type": [ "object", "null" ], "additionalProperties": true }, "diff": { "type": [ "object", "null" ], "additionalProperties": true }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_ChangeCreateRequest": { "type": "object", "required": [ "change_type", "resource_type" ], "additionalProperties": false, "description": "The `changeset_id` is taken from the path parameter; do not include it in the body.", "properties": { "change_type": { "type": "string", "enum": [ "create", "update", "delete", "move", "rename" ], "description": "`create` → INSERT, `update`/`move`/`rename` → UPDATE, `delete` → DELETE." }, "resource_type": { "type": "string", "maxLength": 100 }, "resource_id": { "type": "string", "format": "uuid" }, "before_state": { "type": "object", "additionalProperties": true }, "after_state": { "type": "object", "additionalProperties": true }, "diff": { "type": "object", "additionalProperties": true }, "description": { "type": "string", "maxLength": 2000 }, "metadata": { "type": "object", "additionalProperties": true } } }, "Releases_ChangeApprovalRequest": { "type": "object", "required": [ "changeset_id", "decision" ], "additionalProperties": false, "properties": { "changeset_id": { "type": "string", "format": "uuid" }, "decision": { "type": "string", "enum": [ "approve", "reject", "request_changes" ] }, "comment": { "type": "string", "maxLength": 5000 }, "conditions": { "type": "array", "items": { "type": "string" }, "description": "Optional list of conditions attached to this decision." } } }, "Releases_RollbackRequest": { "type": "object", "required": [ "environment" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "enum": [ "staging", "preprod", "production" ], "description": "Target environment to roll back." }, "notes": { "type": "string", "maxLength": 5000, "description": "Optional rollback notes." } } }, "Releases_UndeployRequest": { "type": "object", "required": [ "environment" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "enum": [ "staging", "preprod", "production" ], "description": "Target environment to undeploy from." }, "notes": { "type": "string", "maxLength": 5000, "description": "Optional undeploy notes." } } }, "Releases_DeploymentResult": { "type": "object", "description": "Result of a deploy, rollback, or undeploy operation.", "properties": { "deployment_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string" }, "status": { "type": "string" }, "deployed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Releases_EnvironmentStatus": { "type": "object", "description": "Deployment status for a single environment.", "properties": { "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "current_release": { "type": [ "string", "null" ] }, "deployed_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } } }, "Releases_DeploymentHistoryEntry": { "type": "object", "description": "A single deployment history record.", "properties": { "id": { "type": "string", "format": "uuid" }, "release_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string" }, "status": { "type": "string" }, "deployed_at": { "type": "string", "format": "date-time" }, "deployed_by": { "type": "string", "format": "uuid" } } }, "Releases_RequestApprovalRequest": { "type": "object", "required": [ "environment" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "enum": [ "staging", "preprod", "production" ], "description": "Target environment for which approval is requested." } } }, "Releases_ApproveRequest": { "type": "object", "required": [ "environment" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "enum": [ "staging", "preprod", "production" ], "description": "Target environment being approved." }, "comment": { "type": "string", "maxLength": 2000, "description": "Optional approval comment." } } }, "Releases_RejectRequest": { "type": "object", "required": [ "environment", "reason" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "enum": [ "staging", "preprod", "production" ], "description": "Target environment being rejected." }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Mandatory rejection reason." } } }, "Releases_ApprovalStatusResult": { "type": "object", "description": "Result of an approval policy evaluation for a release and environment.", "properties": { "approved": { "type": "boolean" }, "pending_conditions": { "type": "array", "items": { "type": "string" } }, "approvers": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Releases_CreateCommentRequest": { "type": "object", "required": [ "content" ], "additionalProperties": false, "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Comment content (markdown)." }, "comment_type": { "type": "string", "enum": [ "general", "bug", "test_pass", "test_fail", "approval", "rejection", "task" ], "description": "Optional comment category." }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ], "description": "Optional environment context for the comment." }, "parent_comment_id": { "type": "string", "format": "uuid", "description": "Optional parent comment ID for threaded replies." } } }, "Releases_Comment": { "type": "object", "description": "A release comment record.", "properties": { "id": { "type": "string", "format": "uuid" }, "release_id": { "type": "string", "format": "uuid" }, "author_id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "comment_type": { "type": "string" }, "environment": { "type": [ "string", "null" ] }, "parent_comment_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "Releases_ComplianceCheckRequest": { "type": "object", "required": [ "target_environment" ], "additionalProperties": false, "properties": { "target_environment": { "type": "string", "enum": [ "staging", "preprod", "production" ], "description": "Environment to evaluate compliance for." } } }, "Releases_ImportToDraftRequest": { "type": "object", "required": [ "environment" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ], "description": "Source environment to import the current deployment state from." } } }, "Releases_RolloutPlan": { "type": "object", "description": "A rollout plan record.", "properties": { "id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": "string", "format": "uuid" }, "strategy": { "type": "string", "enum": [ "immediate", "targeted", "percentage", "progressive" ] }, "current_stage": { "type": "integer" }, "status": { "type": "string" }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/Releases_RolloutStage" } }, "created_at": { "type": "string", "format": "date-time" } } }, "SaasPkg_SlugResolveResult": { "type": "object", "description": "Resolved package identity for a slug or UUID lookup.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Canonical package UUID." }, "slug": { "type": "string", "description": "Canonical URL slug for the package." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization UUID." }, "redirect": { "type": "boolean", "description": "True when the lookup input was a UUID rather than the canonical slug. A client shell MAY update its URL to the slug form; no HTTP redirect is issued." } }, "required": [ "id", "slug", "org_id", "redirect" ], "additionalProperties": false }, "SaasPkg_PlanRef": { "type": "object", "description": "Lightweight pricing plan reference (id + slug + display name).", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "plan_tier": { "type": "string", "enum": [ "academic_free", "pro", "team", "business", "enterprise" ] } }, "required": [ "id", "slug", "name", "plan_tier" ], "additionalProperties": false }, "SaasPkg_OffsetPagination": { "type": "object", "description": "Offset/limit pagination metadata.", "properties": { "total": { "type": "integer", "description": "Total items matching the query." }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "total", "limit", "offset" ], "additionalProperties": false }, "SaasPkg_PagePagination": { "type": "object", "description": "Page/page_size pagination metadata.", "properties": { "total": { "type": "integer", "description": "Total items matching the query." }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": [ "total", "page", "page_size", "total_pages" ], "additionalProperties": false }, "SaasPkg_Package": { "type": "object", "description": "A SaaS package definition.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "maxLength": 64 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "status": { "type": "string", "description": "Publication state.", "enum": [ "draft", "published", "archived" ] }, "metadata": { "type": [ "object", "null" ], "description": "Arbitrary JSON metadata." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "org_id", "name", "slug", "status", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_CreatePackageRequest": { "type": "object", "description": "Request body for creating a SaaS package.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name." }, "slug": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Unique URL slug (lowercase alphanumeric + hyphens). When omitted the API derives one from `name`." }, "description": { "type": "string", "maxLength": 4096 }, "app_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Application display name (shown in the packaged app shell)." }, "subdomain": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9-]+$", "description": "Subdomain slug (lowercase alphanumeric + hyphens)." } }, "required": [ "name" ], "additionalProperties": false }, "SaasPkg_UpdatePackageRequest": { "type": "object", "description": "Request body for updating a SaaS package. At least one field (excluding `id`) required.", "properties": { "id": { "type": "string", "format": "uuid", "description": "URL-mirrored package UUID. Accepted for convenience but the path parameter takes precedence." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64, "description": "Canonical URL slug. Pass `null` to clear the slug and release the slug registry row." }, "description": { "type": [ "string", "null" ], "maxLength": 4096 }, "app_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "subdomain": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9-]+$" }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "favicon_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "theme_config": { "type": [ "object", "null" ], "description": "Theme/branding JSON config." }, "org_config": { "type": [ "object", "null" ] }, "login_screen_config": { "type": [ "object", "null" ] }, "plan_group_config": { "type": [ "object", "null" ], "description": "Config defining the plan group keys (used as valid `category` values on pricing plans)." }, "billing_interval_config": { "type": [ "object", "null" ] } }, "additionalProperties": false }, "SaasPkg_SignupCardConfig": { "type": "object", "description": "Curation config for the signup card marketing surface. No field is required; omit a field to leave it unchanged.", "properties": { "tagline": { "type": [ "string", "null" ], "maxLength": 200, "description": "Short marketing tagline. Must not contain `<` or `>`." }, "badge": { "type": [ "string", "null" ], "maxLength": 30, "description": "Short badge label (e.g. 'Popular'). Must not contain `<` or `>`." }, "accent": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$", "description": "Accent color as `#RRGGBB`." }, "icon_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "Package icon. Must be an `https://` URL on an allowed CDN hostname." }, "recommended": { "type": [ "boolean", "null" ] }, "cta_label": { "type": [ "string", "null" ], "maxLength": 30, "description": "Call-to-action button label. Must not contain `<` or `>`." } }, "additionalProperties": false }, "SaasPkg_PackageCurationPatchRequest": { "type": "object", "description": "Curation-only PATCH for a package. Requires `saas_package.curate` permission. At least one field required.", "properties": { "show_on_org_signup": { "type": "boolean", "description": "Whether this package appears on the org signup screen." }, "signup_rollup_sort_order": { "type": "integer", "minimum": 0, "description": "Display order on the signup rollup." }, "signup_card_config": { "oneOf": [ { "$ref": "#/components/schemas/SaasPkg_SignupCardConfig" }, { "type": "null" } ] }, "academic_verification_purpose": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Purpose statement shown during academic verification." }, "project_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 200, "description": "Full-replace set of project UUIDs whose entity types/entities this package carries." }, "expected_version": { "type": [ "integer", "null" ], "minimum": 0, "description": "Optimistic concurrency version. When provided, the SP rejects the update if the current version differs." } }, "additionalProperties": false }, "SaasPkg_ClonePackageRequest": { "type": "object", "description": "Request body for cloning a SaaS package. Source package ID comes from the URL path. The clone always starts in `draft` status.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Name for the cloned package." }, "description": { "type": "string", "maxLength": 4096 } }, "required": [ "name" ], "additionalProperties": false }, "SaasPkg_PricingPlanPrice": { "type": "object", "description": "Price definition for a billing interval.", "properties": { "monthly": { "type": [ "number", "null" ], "minimum": 0, "description": "Monthly price in USD cents." }, "annual": { "type": [ "number", "null" ], "minimum": 0, "description": "Annual price in USD cents (per year)." }, "quarterly": { "type": [ "number", "null" ], "minimum": 0 } }, "additionalProperties": false }, "SaasPkg_PricingPlan": { "type": "object", "description": "A pricing plan for a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "maxLength": 64 }, "plan_tier": { "type": "string", "enum": [ "academic_free", "pro", "team", "business", "enterprise" ] }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "prices": { "$ref": "#/components/schemas/SaasPkg_PricingPlanPrice" }, "is_active": { "type": "boolean" }, "metadata": { "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "package_id", "name", "slug", "plan_tier", "is_active", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_PricingPlanPriceRow": { "type": "object", "description": "Per-timeframe price row.", "properties": { "timeframe_key": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "quarterly", "semiannual", "yearly", "custom" ] }, "interval_unit": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ], "description": "Required for `custom` timeframe_key." }, "interval_count": { "type": "integer", "minimum": 1, "maximum": 366, "description": "Required for `custom` timeframe_key." }, "label": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required for `custom` timeframe_key." }, "price_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code (default `USD`)." }, "badge": { "type": "string", "maxLength": 255 }, "sort_order": { "type": "integer", "minimum": 0 }, "is_active": { "type": "boolean" } }, "required": [ "timeframe_key", "price_cents" ], "additionalProperties": false }, "SaasPkg_CreatePricingPlanRequest": { "type": "object", "description": "Request body for creating a pricing plan. `plan_type` defaults to `recurring`. Recurring plans require `billing_interval` (or legacy `interval`). Free plans must have `price_cents: 0`.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9-]+$" }, "plan_tier": { "type": "string", "enum": [ "academic_free", "pro", "team", "business", "enterprise" ] }, "category": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Builder-defined group key. Must match a key in the package's `plan_group_config.groups`. The reserved value `system` is not permitted." }, "plan_type": { "type": "string", "enum": [ "free", "one_time", "recurring" ], "default": "recurring" }, "billing_interval": { "type": "string", "enum": [ "monthly", "yearly", "quarterly" ], "description": "Required when `plan_type` is `recurring`." }, "interval": { "type": "string", "enum": [ "month", "year", "quarter" ], "description": "Legacy alias for `billing_interval`. Prefer `billing_interval`." }, "price_cents": { "type": "integer", "minimum": 0 }, "price_cents_yearly": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code (default `USD`)." }, "description": { "type": "string", "maxLength": 4096 }, "trial_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "grace_period_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "credits_monthly": { "type": "integer", "minimum": 0 }, "credit_cost_microcents": { "type": "integer", "minimum": 0 }, "max_projects": { "type": "integer", "minimum": 0 }, "max_members": { "type": "integer", "minimum": 0 }, "storage_bytes": { "type": "integer", "minimum": 0 }, "db_storage_bytes": { "type": "integer", "minimum": 0 }, "is_per_seat": { "type": "boolean" }, "min_seats": { "type": "integer", "minimum": 1 }, "max_seats": { "type": "integer", "minimum": 1 }, "features": { "description": "Plan feature list. Either an array of feature-string labels or a JSON feature map." }, "limits": { "type": "object", "description": "Arbitrary limits JSON." }, "sort_order": { "type": "integer", "minimum": 0 }, "is_active": { "type": "boolean" }, "is_highlighted": { "type": "boolean" }, "usage_billing": { "type": "object" }, "metadata": { "type": "object" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_PricingPlanPriceRow" }, "maxItems": 50, "description": "Per-timeframe price rows. When present, the SP upserts one row per entry." } }, "required": [ "name", "plan_tier", "category", "price_cents" ], "additionalProperties": false }, "SaasPkg_UpdatePricingPlanRequest": { "type": "object", "description": "Request body for updating a pricing plan. At least one field (excluding `id`) required.", "properties": { "id": { "type": "string", "format": "uuid", "description": "URL-mirrored. Accepted for convenience but ignored in favour of the path parameter." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9-]+$" }, "plan_tier": { "type": "string", "enum": [ "academic_free", "pro", "team", "business", "enterprise" ] }, "category": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "plan_type": { "type": "string", "enum": [ "free", "one_time", "recurring" ] }, "billing_interval": { "type": "string", "enum": [ "monthly", "yearly", "quarterly" ] }, "interval": { "type": "string", "enum": [ "month", "year", "quarter" ] }, "price_cents": { "type": "integer", "minimum": 0 }, "price_cents_yearly": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "description": { "type": "string", "maxLength": 4096 }, "trial_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "grace_period_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "credits_monthly": { "type": "integer", "minimum": 0 }, "credit_cost_microcents": { "type": "integer", "minimum": 0 }, "max_projects": { "type": "integer", "minimum": 0 }, "max_members": { "type": "integer", "minimum": 0 }, "storage_bytes": { "type": "integer", "minimum": 0 }, "db_storage_bytes": { "type": "integer", "minimum": 0 }, "is_per_seat": { "type": "boolean" }, "min_seats": { "type": "integer", "minimum": 1 }, "max_seats": { "type": "integer", "minimum": 1 }, "is_highlighted": { "type": "boolean" }, "features": { "description": "Plan feature list." }, "limits": { "type": [ "object", "null" ] }, "sort_order": { "type": "integer", "minimum": 0 }, "is_active": { "type": "boolean" }, "usage_billing": { "type": [ "object", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_PricingPlanPriceRow" }, "maxItems": 50 } }, "additionalProperties": false }, "SaasPkg_PricingPlanCurationPatchRequest": { "type": "object", "description": "Curation-only PATCH for a pricing plan. Requires `saas_package.curate` permission. At least one field required.", "properties": { "show_on_signup": { "type": "boolean" }, "signup_tier_slug": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9-]+$" }, "eligibility_check": { "type": [ "string", "null" ], "enum": [ "none", "academic", "employee" ] }, "requires_any_plan_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "maxItems": 50 }, "fallback_plan_id": { "type": [ "string", "null" ], "format": "uuid" }, "expected_version": { "type": [ "integer", "null" ], "minimum": 0 } }, "additionalProperties": false }, "SaasPkg_RenamePlanSlugRequest": { "type": "object", "description": "Request body for renaming a pricing plan slug.", "properties": { "new_slug": { "type": "string", "minLength": 1, "maxLength": 64, "description": "New URL slug (lowercase alphanumeric + hyphens)." } }, "required": [ "new_slug" ], "additionalProperties": false }, "SaasPkg_SyncPricingPlansRequest": { "type": "object", "description": "Request body for triggering a Stripe pricing-plan sync for a specific environment.", "properties": { "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ], "description": "Target billing environment to sync." }, "plan_id": { "type": "string", "description": "Optional — restrict sync to a single plan by its external provider ID." } }, "required": [ "environment" ], "additionalProperties": false }, "SaasPkg_Promotion": { "type": "object", "description": "A promotional discount for a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 500 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "internal_note": { "type": [ "string", "null" ], "maxLength": 5000 }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discount_value": { "type": "number", "exclusiveMinimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "applies_to": { "type": "string", "enum": [ "all", "categories", "plans" ] }, "applicable_categories": { "type": [ "array", "null" ], "items": { "type": "string" } }, "applicable_plan_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "applies_to_intervals": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "monthly", "yearly", "quarterly" ] } }, "stripe_duration": { "type": "string", "enum": [ "once", "forever", "repeating" ] }, "duration_months": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_redemptions": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "badge_label": { "type": [ "string", "null" ], "maxLength": 100 }, "is_featured": { "type": "boolean" }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "package_id", "name", "discount_type", "discount_value", "is_active", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_CreatePromotionRequest": { "type": "object", "description": "Request body for creating a promotion.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "maxLength": 10000 }, "internal_note": { "type": "string", "maxLength": 5000 }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discount_value": { "type": "number", "exclusiveMinimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "usd" }, "applies_to": { "type": "string", "enum": [ "all", "categories", "plans" ], "default": "all" }, "applicable_categories": { "type": "array", "items": { "type": "string" } }, "applicable_plan_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "applies_to_intervals": { "type": "array", "items": { "type": "string", "enum": [ "monthly", "yearly", "quarterly" ] } }, "stripe_duration": { "type": "string", "enum": [ "once", "forever", "repeating" ], "default": "once" }, "duration_months": { "type": "integer", "exclusiveMinimum": 0 }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_redemptions": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "badge_label": { "type": [ "string", "null" ], "maxLength": 100 }, "is_featured": { "type": "boolean", "default": false }, "sort_order": { "type": "integer", "default": 0 }, "is_active": { "type": "boolean", "default": true } }, "required": [ "name", "discount_type", "discount_value" ], "additionalProperties": false }, "SaasPkg_UpdatePromotionRequest": { "type": "object", "description": "Request body for updating a promotion. At least one field (excluding `id`) required. All fields from `CreatePromotionRequest` are accepted as optional.", "properties": { "id": { "type": "string", "format": "uuid", "description": "URL-mirrored. Ignored in favour of the path parameter." }, "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "maxLength": 10000 }, "internal_note": { "type": "string", "maxLength": 5000 }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed_amount" ] }, "discount_value": { "type": "number", "exclusiveMinimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "applies_to": { "type": "string", "enum": [ "all", "categories", "plans" ] }, "applicable_categories": { "type": "array", "items": { "type": "string" } }, "applicable_plan_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "applies_to_intervals": { "type": "array", "items": { "type": "string", "enum": [ "monthly", "yearly", "quarterly" ] } }, "stripe_duration": { "type": "string", "enum": [ "once", "forever", "repeating" ] }, "duration_months": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_redemptions": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "badge_label": { "type": [ "string", "null" ], "maxLength": 100 }, "is_featured": { "type": "boolean" }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" } }, "additionalProperties": false }, "SaasPkg_SyncPromotionsRequest": { "type": "object", "description": "Request body for triggering a Stripe promotions sync for a specific environment.", "properties": { "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] } }, "required": [ "environment" ], "additionalProperties": false }, "SaasPkg_CustomDomain": { "type": "object", "description": "A custom domain attached to a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "domain": { "type": "string", "format": "hostname", "description": "The fully-qualified domain name." }, "verified": { "type": "boolean", "description": "Whether the domain has passed DNS verification." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "package_id", "domain", "verified", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_CreateDomainRequest": { "type": "object", "description": "Request body for adding a custom domain.", "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Fully-qualified domain name to add (e.g. `app.example.com`)." }, "domain_type": { "type": "string", "enum": [ "primary", "alias", "subdomain" ] }, "is_default": { "type": "boolean" }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "api_base_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS base URL of the API for this domain. Must use `https://` scheme." } }, "required": [ "domain" ], "additionalProperties": false }, "SaasPkg_MarketingPage": { "type": "object", "description": "A marketing page for a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "slug": { "type": [ "string", "null" ], "maxLength": 128 }, "title": { "type": "string", "maxLength": 255 }, "page_type": { "type": "string", "enum": [ "landing", "feature", "pricing", "about", "custom" ] }, "content": { "type": [ "object", "null" ], "description": "Page content as a bounded JSON structure." }, "seo_title": { "type": [ "string", "null" ], "maxLength": 255 }, "seo_description": { "type": [ "string", "null" ], "maxLength": 512 }, "og_image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "sort_order": { "type": [ "integer", "null" ], "minimum": 0 }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "metadata": { "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "package_id", "title", "page_type", "status", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_CreateMarketingPageRequest": { "type": "object", "description": "Request body for creating a marketing page.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9-]+$" }, "page_type": { "type": "string", "enum": [ "landing", "feature", "pricing", "about", "custom" ], "default": "custom" }, "content": { "type": "object", "description": "Page content as a bounded JSON structure." }, "seo_title": { "type": "string", "maxLength": 255 }, "seo_description": { "type": "string", "maxLength": 512 }, "og_image_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Open Graph image URL. Must use `https://` scheme." }, "sort_order": { "type": "integer", "minimum": 0 }, "metadata": { "type": "object" } }, "required": [ "title" ], "additionalProperties": false }, "SaasPkg_UpdateMarketingPageRequest": { "type": "object", "description": "Request body for updating a marketing page. At least one field (excluding `id`) required.", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9-]+$" }, "page_type": { "type": "string", "enum": [ "landing", "feature", "pricing", "about", "custom" ] }, "content": { "type": [ "object", "null" ] }, "seo_title": { "type": [ "string", "null" ], "maxLength": 255 }, "seo_description": { "type": [ "string", "null" ], "maxLength": 512 }, "og_image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "sort_order": { "type": [ "integer", "null" ], "minimum": 0 }, "metadata": { "type": [ "object", "null" ] } }, "additionalProperties": false }, "SaasPkg_SeedData": { "type": "object", "description": "A seed data entry for a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 4096 }, "entity_type": { "type": "string", "maxLength": 128 }, "data": { "description": "Arbitrary seed data payload (any JSON)." }, "sort_order": { "type": [ "integer", "null" ], "minimum": 0 }, "is_required": { "type": [ "boolean", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "package_id", "name", "entity_type", "data", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_CreateSeedDataRequest": { "type": "object", "description": "Request body for creating a seed data entry.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 4096 }, "entity_type": { "type": "string", "minLength": 1, "maxLength": 128 }, "data": { "description": "Seed data payload (any JSON value)." }, "sort_order": { "type": "integer", "minimum": 0 }, "is_required": { "type": "boolean" }, "metadata": { "type": "object" } }, "required": [ "name", "entity_type", "data" ], "additionalProperties": false }, "SaasPkg_UpdateSeedDataRequest": { "type": "object", "description": "Request body for updating a seed data entry. At least one field (excluding `id`) required.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 4096 }, "entity_type": { "type": "string", "minLength": 1, "maxLength": 128 }, "data": { "description": "Seed data payload." }, "sort_order": { "type": [ "integer", "null" ], "minimum": 0 }, "is_required": { "type": "boolean" }, "metadata": { "type": [ "object", "null" ] } }, "additionalProperties": false }, "SaasPkg_ConnectorConfig": { "type": "object", "description": "A connector configuration for a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255 }, "connector_type": { "type": "string", "maxLength": 128 }, "description": { "type": [ "string", "null" ], "maxLength": 4096 }, "config": { "type": [ "object", "null" ], "description": "Connector configuration JSON." }, "is_required": { "type": [ "boolean", "null" ] }, "sort_order": { "type": [ "integer", "null" ], "minimum": 0 }, "metadata": { "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "package_id", "name", "connector_type", "config", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_CreateConnectorRequest": { "type": "object", "description": "Request body for creating a connector configuration.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "connector_type": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": "string", "maxLength": 4096 }, "config": { "type": "object", "description": "Connector configuration JSON. Required." }, "is_required": { "type": "boolean" }, "sort_order": { "type": "integer", "minimum": 0 }, "metadata": { "type": "object" } }, "required": [ "name", "connector_type", "config" ], "additionalProperties": false }, "SaasPkg_UpdateConnectorRequest": { "type": "object", "description": "Request body for updating a connector configuration. At least one field (excluding `id`) required.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "connector_type": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": [ "string", "null" ], "maxLength": 4096 }, "config": { "type": [ "object", "null" ] }, "is_required": { "type": "boolean" }, "sort_order": { "type": [ "integer", "null" ], "minimum": 0 }, "metadata": { "type": [ "object", "null" ] } }, "additionalProperties": false }, "SaasPkg_ScreenDefinition": { "type": "object", "description": "A screen definition for a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "screen_key": { "type": "string", "maxLength": 200, "description": "Unique key for this screen within the package (alphanumeric + dots + underscores + hyphens)." }, "screen_type": { "type": [ "string", "null" ], "enum": [ "core", "custom", "view_based" ] }, "layout_config": { "type": [ "object", "null" ] }, "component_config": { "type": [ "object", "null" ] }, "visibility": { "type": [ "object", "null" ] }, "sort_order": { "type": [ "integer", "null" ], "minimum": 0 }, "is_active": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "package_id", "screen_key", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_CreateScreenDefinitionRequest": { "type": "object", "description": "Request body for creating a screen definition.", "properties": { "screen_key": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9._-]+$", "description": "Unique screen key within the package." }, "screen_type": { "type": "string", "enum": [ "core", "custom", "view_based" ] }, "layout_config": { "type": "object" }, "component_config": { "type": "object" }, "visibility": { "type": "object" }, "sort_order": { "type": "integer", "minimum": 0 }, "is_active": { "type": "boolean" } }, "required": [ "screen_key" ], "additionalProperties": false }, "SaasPkg_UpdateScreenDefinitionRequest": { "type": "object", "description": "Request body for updating a screen definition. At least one field (excluding `id`) required.", "properties": { "id": { "type": "string", "format": "uuid" }, "screen_key": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[a-zA-Z0-9._-]+$" }, "screen_type": { "type": "string", "enum": [ "core", "custom", "view_based" ] }, "layout_config": { "type": [ "object", "null" ] }, "component_config": { "type": [ "object", "null" ] }, "visibility": { "type": [ "object", "null" ] }, "sort_order": { "type": [ "integer", "null" ], "minimum": 0 }, "is_active": { "type": "boolean" }, "changelog": { "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "SaasPkg_AppConfig": { "type": "object", "description": "A per-platform application configuration for a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux", "web" ] }, "app_name": { "type": "string", "maxLength": 500 }, "bundle_identifier": { "type": [ "string", "null" ], "maxLength": 500 }, "version_name": { "type": [ "string", "null" ], "maxLength": 64 }, "version_code": { "type": [ "integer", "null" ], "minimum": 1 }, "icon_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "splash_screen_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "splash_background_color": { "type": [ "string", "null" ], "pattern": "^#[0-9A-Fa-f]{6}$" }, "signing_config_ref": { "type": [ "string", "null" ] }, "platform_config": { "type": [ "object", "null" ] }, "eas_project_id": { "type": [ "string", "null" ], "maxLength": 255 }, "status": { "type": [ "string", "null" ], "enum": [ "draft", "building", "published", "suspended" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "package_id", "platform", "app_name", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_CreateAppConfigRequest": { "type": "object", "description": "Request body for creating an app configuration.", "properties": { "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux", "web" ] }, "app_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "bundle_identifier": { "type": "string", "maxLength": 500 }, "version_name": { "type": "string", "maxLength": 64 }, "version_code": { "type": "integer", "minimum": 1 }, "icon_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "splash_screen_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "splash_background_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Hex color like `#FFFFFF`." }, "signing_config_ref": { "type": "string" }, "platform_config": { "type": "object" }, "eas_project_id": { "type": "string", "maxLength": 255 } }, "required": [ "platform", "app_name" ], "additionalProperties": false }, "SaasPkg_UpdateAppConfigRequest": { "type": "object", "description": "Request body for updating an app configuration. At least one field (excluding `id`) required.", "properties": { "id": { "type": "string", "format": "uuid" }, "app_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "bundle_identifier": { "type": [ "string", "null" ], "maxLength": 500 }, "version_name": { "type": [ "string", "null" ], "maxLength": 64 }, "version_code": { "type": [ "integer", "null" ], "minimum": 1 }, "icon_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "splash_screen_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "splash_background_color": { "type": [ "string", "null" ], "pattern": "^#[0-9A-Fa-f]{6}$" }, "signing_config_ref": { "type": [ "string", "null" ] }, "platform_config": { "type": [ "object", "null" ] }, "eas_project_id": { "type": [ "string", "null" ], "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "building", "published", "suspended" ] } }, "additionalProperties": false }, "SaasPkg_DataBundle": { "type": "object", "description": "A versioned data bundle for a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "bundle_hash": { "type": "string", "maxLength": 512, "description": "Content hash for integrity verification." }, "content": { "description": "Bundle content (any JSON)." }, "bundle_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "bundle_size_bytes": { "type": [ "integer", "null" ], "minimum": 0 }, "status": { "type": "string", "enum": [ "draft", "published", "rollback" ] }, "created_at": { "type": "string", "format": "date-time" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "package_id", "bundle_hash", "content", "status", "created_at" ], "additionalProperties": false }, "SaasPkg_CreateDataBundleRequest": { "type": "object", "description": "Request body for creating a data bundle.", "properties": { "bundle_hash": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Content hash for the bundle." }, "content": { "description": "Bundle content (any JSON)." }, "bundle_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "bundle_size_bytes": { "type": "integer", "minimum": 0 } }, "required": [ "bundle_hash", "content" ], "additionalProperties": false }, "SaasPkg_RevenueSummary": { "type": "object", "description": "Revenue summary metrics for a SaaS package.", "properties": { "mrr": { "type": "number", "description": "Monthly Recurring Revenue in USD cents." }, "arr": { "type": "number", "description": "Annual Recurring Revenue in USD cents." }, "churn_rate": { "type": "number", "description": "Subscriber churn rate (0–1 fraction)." }, "active_subscribers": { "type": "integer" }, "trial_subscribers": { "type": "integer" }, "total_revenue": { "type": "number", "description": "Total lifetime revenue in USD cents." }, "as_of": { "type": "string", "format": "date-time", "description": "Snapshot timestamp for these metrics." } }, "required": [ "mrr", "arr", "churn_rate", "active_subscribers", "trial_subscribers", "total_revenue", "as_of" ], "additionalProperties": false }, "SaasPkg_RevenueTimeseries": { "type": "object", "description": "Revenue time-series data.", "properties": { "interval": { "type": "string", "enum": [ "day", "week", "month" ] }, "periods": { "type": "integer" }, "series": { "type": "array", "items": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date-time" }, "mrr": { "type": "number" }, "new_subscribers": { "type": "integer" }, "churned_subscribers": { "type": "integer" }, "revenue": { "type": "number" } }, "required": [ "period_start", "mrr", "new_subscribers", "churned_subscribers", "revenue" ], "additionalProperties": false } } }, "required": [ "interval", "periods", "series" ], "additionalProperties": false }, "SaasPkg_RevenueByPlan": { "type": "object", "description": "Revenue breakdown by pricing plan.", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "plan_id": { "type": "string", "format": "uuid" }, "plan_name": { "type": "string" }, "plan_slug": { "type": "string" }, "active_subscribers": { "type": "integer" }, "mrr": { "type": "number" }, "revenue_share": { "type": "number", "description": "Fraction of total MRR (0–1)." } }, "required": [ "plan_id", "plan_name", "plan_slug", "active_subscribers", "mrr", "revenue_share" ], "additionalProperties": false } } }, "required": [ "plans" ], "additionalProperties": false }, "SaasPkg_FeatureFlag": { "type": "object", "description": "A custom feature flag for a SaaS package.", "properties": { "id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "maxLength": 128, "description": "Unique slug identifier within the package." }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "is_enabled": { "type": "boolean", "description": "Package-level default value." }, "metadata": { "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "package_id", "slug", "name", "is_enabled", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_CreateFeatureFlagRequest": { "type": "object", "description": "Request body for creating a custom feature flag.", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Lowercase alphanumeric + hyphens. Must be unique within the package." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "is_enabled": { "type": "boolean", "default": false, "description": "Package-level default enable state." }, "metadata": { "type": "object" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "SaasPkg_UpdateFeatureFlagRequest": { "type": "object", "description": "Request body for updating a custom feature flag. All fields optional.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "is_enabled": { "type": "boolean" }, "metadata": { "type": [ "object", "null" ] } }, "additionalProperties": false }, "SaasPkg_SystemAssignmentItem": { "type": "object", "description": "A system feature flag assignment override.", "properties": { "feature_flag_id": { "type": "string", "format": "uuid", "description": "System feature flag UUID." }, "is_enabled": { "type": "boolean" }, "metadata": { "type": [ "object", "null" ] } }, "required": [ "feature_flag_id" ], "additionalProperties": false }, "SaasPkg_SystemAssignmentsRequest": { "type": "object", "description": "Batch request to update system feature flag assignments for a package.", "properties": { "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_SystemAssignmentItem" }, "minItems": 1 } }, "required": [ "assignments" ], "additionalProperties": false }, "SaasPkg_ScopedAssignmentItem": { "type": "object", "description": "A feature flag assignment targeting either a system or custom flag.", "properties": { "feature_flag_id": { "type": "string", "format": "uuid" }, "flag_source": { "type": "string", "enum": [ "system", "custom" ], "description": "Whether this flag is a system-managed flag or a package custom flag." }, "is_enabled": { "type": "boolean" }, "metadata": { "type": [ "object", "null" ] } }, "required": [ "feature_flag_id", "flag_source" ], "additionalProperties": false }, "SaasPkg_ScopedAssignmentsRequest": { "type": "object", "description": "Batch request to update feature flag assignments scoped to a plan or tenant.", "properties": { "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_ScopedAssignmentItem" }, "minItems": 1 } }, "required": [ "assignments" ], "additionalProperties": false }, "SaasPkg_AiModelOverride": { "type": "object", "description": "Model-centric view of an AI model with its package-level override state.", "properties": { "model_id": { "type": "string", "format": "uuid", "description": "Either the system model UUID or the org model UUID." }, "display_name": { "type": "string" }, "model_string": { "type": "string", "description": "Provider model identifier string (e.g. `gpt-4o`)." }, "is_system_model": { "type": "boolean", "description": "True when this model is provided by the platform; false for org-owned models." }, "is_enabled_for_package": { "type": "boolean", "description": "Current enable/disable state for this package." } }, "required": [ "model_id", "display_name", "model_string", "is_system_model", "is_enabled_for_package" ], "additionalProperties": false }, "SaasPkg_AiModelOverrideEntry": { "type": "object", "description": "A single AI model override entry in a batch request.", "properties": { "system_model_id": { "type": "string", "format": "uuid", "description": "System model UUID. Exactly one of `system_model_id` or `org_model_id` must be present." }, "org_model_id": { "type": "string", "format": "uuid", "description": "Org model UUID. Exactly one of `system_model_id` or `org_model_id` must be present." }, "is_enabled": { "type": "boolean" } }, "required": [ "is_enabled" ], "additionalProperties": false }, "SaasPkg_AiModelBatchOverrideRequest": { "type": "object", "description": "Batch request to upsert AI model overrides for a package.", "properties": { "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/SaasPkg_AiModelOverrideEntry" }, "minItems": 1, "maxItems": 200 } }, "required": [ "overrides" ], "additionalProperties": false }, "SaasPkg_AiModelUpsertRequest": { "type": "object", "description": "Request body for upserting a single AI model override. Exactly one of `system_model_id` or `org_model_id` must be provided. The schema uses `.strict()` — unknown fields are rejected.", "properties": { "system_model_id": { "type": "string", "format": "uuid", "description": "System model UUID. Mutually exclusive with `org_model_id`." }, "org_model_id": { "type": "string", "format": "uuid", "description": "Org-owned model UUID. Mutually exclusive with `system_model_id`." }, "is_enabled": { "type": "boolean" } }, "required": [ "is_enabled" ], "additionalProperties": false }, "SaasPkg_Integration": { "type": "object", "description": "A third-party integration configured for an organization. Secret values are never included in responses.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "stripe", "resend", "sendgrid", "ses", "twilio", "signalwire" ], "description": "Integration provider identifier." }, "config": { "type": [ "object", "null" ], "description": "Non-secret configuration fields for this integration. `_secret_ref` fields are stripped from this object before it is returned." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "org_id", "provider", "created_at", "updated_at" ], "additionalProperties": false }, "SaasPkg_ConfigureIntegrationRequest": { "type": "object", "description": "Request body for configuring a third-party integration. Secret values are encrypted at rest and never returned.", "properties": { "provider": { "type": "string", "enum": [ "stripe", "resend", "sendgrid", "ses", "twilio", "signalwire" ], "description": "Integration provider to configure." }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Non-secret provider configuration key/value pairs." }, "secrets": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Secret provider key/value pairs. At least one entry required. Values are encrypted at rest and never returned." } }, "required": [ "provider", "config", "secrets" ], "additionalProperties": false }, "SaasPkg_IntegrationTestResult": { "type": "object", "description": "Result of a live connectivity test for an integration.", "properties": { "success": { "type": "boolean", "description": "Whether the provider connectivity test passed." }, "message": { "type": "string", "description": "Human-readable detail about the test outcome (may be absent on success)." } }, "required": [ "success" ], "additionalProperties": false }, "SaasPlatform_PausedSubscription": { "type": "object", "description": "A SaaS subscription that is currently paused because the seller's payment account has been disabled.", "required": [ "subscription_id", "saas_package_id", "package_name", "seller_org_id", "seller_name", "paused_at" ], "properties": { "subscription_id": { "type": "string", "format": "uuid", "description": "Subscription identifier." }, "saas_package_id": { "type": "string", "format": "uuid", "description": "SaaS package identifier." }, "package_name": { "type": "string", "description": "Human-readable package name." }, "seller_org_id": { "type": "string", "format": "uuid", "description": "Seller organization identifier." }, "seller_name": { "type": "string", "description": "Seller organization display name." }, "paused_at": { "type": "string", "format": "date-time", "description": "When the subscription was paused." } } }, "SaasPlatform_TenantProvision": { "type": "object", "description": "A tenant provisioning record representing a deployed instance of a SaaS package for a specific tenant.", "required": [ "provision_id", "saas_package_id", "tenant_name", "tenant_slug", "status", "created_at" ], "properties": { "provision_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "tenant_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "tenant_slug": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9-]+$" }, "admin_user_id": { "type": "string", "format": "uuid", "nullable": true }, "admin_email": { "type": "string", "format": "email", "nullable": true }, "admin_display_name": { "type": "string", "maxLength": 255, "nullable": true }, "tenant_settings": { "type": "object", "nullable": true, "description": "Package-specific tenant configuration." }, "status": { "type": "string", "enum": [ "provisioning", "active", "deprovisioning", "deprovisioned", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_CustomerSubscription": { "type": "object", "description": "A customer subscription to a SaaS package.", "required": [ "subscription_id", "saas_package_id", "subscriber_org_id", "pricing_plan_id", "status", "created_at" ], "properties": { "subscription_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "subscriber_org_id": { "type": "string", "format": "uuid" }, "pricing_plan_id": { "type": "string", "format": "uuid" }, "stripe_subscription_id": { "type": "string", "maxLength": 255, "nullable": true }, "quantity": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "active", "paused", "cancelled", "past_due", "trialing" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_AppConfig": { "type": "object", "description": "A platform-specific app configuration record.", "required": [ "config_id", "saas_package_id", "platform", "created_at" ], "properties": { "config_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux", "web" ] }, "bundle_id": { "type": "string", "nullable": true, "description": "App bundle/package identifier for the platform." }, "version_name": { "type": "string", "nullable": true }, "version_code": { "type": "integer", "nullable": true }, "config_data": { "type": "object", "nullable": true, "description": "Platform-specific configuration fields." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_DataBundle": { "type": "object", "description": "A versioned data bundle (seed data, configuration, or content payload) for a SaaS package.", "required": [ "bundle_id", "saas_package_id", "version", "status", "created_at" ], "properties": { "bundle_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "version": { "type": "string", "description": "Semver-formatted bundle version." }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "published", "superseded" ] }, "bundle_url": { "type": "string", "format": "uri", "nullable": true, "description": "Download URL for the bundle payload." }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_BuildJob": { "type": "object", "description": "A native app build job.", "required": [ "build_id", "saas_package_id", "platform", "build_system", "build_type", "status", "created_at" ], "properties": { "build_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "app_config_id": { "type": "string", "format": "uuid", "nullable": true }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux" ] }, "build_system": { "type": "string", "enum": [ "cloudflare_container", "codemagic", "eas_build", "self_hosted_mac" ] }, "build_type": { "type": "string", "enum": [ "development", "preview", "production" ] }, "status": { "type": "string", "enum": [ "pending", "queued", "in_progress", "success", "failed", "cancelled" ] }, "error_message": { "type": "string", "nullable": true }, "artifact_url": { "type": "string", "format": "uri", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_ScreenDefinition": { "type": "object", "description": "A screen definition describing the layout and component configuration of a screen in the generated app.", "required": [ "screen_id", "saas_package_id", "screen_key", "screen_type", "is_active", "created_at" ], "properties": { "screen_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "screen_key": { "type": "string", "description": "Unique key for the screen within the package." }, "screen_type": { "type": "string", "enum": [ "core", "custom", "view_based" ] }, "display_name": { "type": "string", "nullable": true }, "layout_config": { "type": "object", "nullable": true, "description": "Screen layout and component configuration." }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_StoreAccount": { "type": "object", "description": "A store account credential for submitting apps to an app store. Credential fields are masked in responses.", "required": [ "account_id", "saas_package_id", "platform", "account_type", "account_name", "is_active", "created_at" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] }, "account_type": { "type": "string", "enum": [ "apple_app_store_connect", "google_play_console", "microsoft_partner_center" ] }, "account_name": { "type": "string" }, "is_active": { "type": "boolean" }, "last_validated_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_StoreListing": { "type": "object", "description": "A store listing for a SaaS package app.", "required": [ "listing_id", "saas_package_id", "app_title", "created_at" ], "properties": { "listing_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "app_title": { "type": "string", "maxLength": 255 }, "short_description": { "type": "string", "maxLength": 500, "nullable": true }, "full_description": { "type": "string", "maxLength": 8000, "nullable": true }, "keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "nullable": true }, "screenshots": { "type": "array", "items": { "type": "string", "format": "uri" }, "nullable": true }, "icon_url": { "type": "string", "format": "uri", "nullable": true }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] }, "status": { "type": "string", "enum": [ "draft", "pending_review", "in_review", "approved", "rejected", "published" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_StoreSubmission": { "type": "object", "description": "A store submission record.", "required": [ "submission_id", "saas_package_id", "status", "created_at" ], "properties": { "submission_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "listing_id": { "type": "string", "format": "uuid", "nullable": true }, "build_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_review", "in_review", "approved", "rejected", "published" ] }, "reviewer_notes": { "type": "string", "nullable": true }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_ComplianceCheckResult": { "type": "object", "description": "Result of a compliance pre-check.", "required": [ "passed", "issues" ], "properties": { "passed": { "type": "boolean", "description": "Whether all compliance checks passed." }, "issues": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "severity" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "field": { "type": "string", "nullable": true } } } } } }, "SaasPlatform_AgeRating": { "type": "object", "description": "An age rating record for a SaaS package on a specific store platform.", "required": [ "rating_id", "saas_package_id", "platform", "rating_category", "created_at" ], "properties": { "rating_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] }, "rating_category": { "type": "string", "description": "Platform-specific age rating category (e.g. `4+`, `E`, `USK 0`)." }, "content_descriptors": { "type": "array", "items": { "type": "string" }, "nullable": true }, "questionnaire_answers": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_KycSession": { "type": "object", "description": "A KYC verification session.", "required": [ "session_id", "saas_package_id", "status", "created_at" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "expired", "failed" ] }, "redirect_url": { "type": "string", "format": "uri", "description": "URL to redirect the user to the KYC provider." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_KycRequirements": { "type": "object", "description": "KYC requirements for a SaaS package.", "required": [ "saas_package_id", "requirements" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "requirements": { "type": "array", "items": { "type": "object", "required": [ "type", "label", "required" ], "properties": { "type": { "type": "string", "description": "Requirement type (e.g. `identity_document`, `business_registration`)." }, "label": { "type": "string" }, "required": { "type": "boolean" }, "description": { "type": "string", "nullable": true } } } }, "supported_regions": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "SaasPlatform_BaseBinary": { "type": "object", "description": "A base binary artifact (pre-compiled app shell) used as the foundation for build jobs.", "required": [ "binary_id", "platform", "release_version", "build_number", "status", "created_at" ], "properties": { "binary_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux" ] }, "release_version": { "type": "string", "description": "Human-readable release version (e.g. `1.0.0`)." }, "build_number": { "type": "integer", "description": "Monotonically increasing build number." }, "status": { "type": "string", "enum": [ "building", "ready", "deprecated", "failed" ] }, "artifact_url": { "type": "string", "format": "uri", "nullable": true }, "artifact_hash": { "type": "string", "nullable": true }, "artifact_size_bytes": { "type": "integer", "nullable": true }, "build_system": { "type": "string", "nullable": true }, "git_commit_sha": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_ReleaseBatch": { "type": "object", "description": "A release batch grouping build jobs for coordinated rollout.", "required": [ "batch_id", "status", "rollout_strategy", "created_at" ], "properties": { "batch_id": { "type": "string", "format": "uuid" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled", "failed" ] }, "rollout_strategy": { "type": "string", "enum": [ "all_at_once", "staged_percentage", "staged_manual" ] }, "rollout_percentage": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "job_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Build job identifiers included in this batch." }, "completed_jobs": { "type": "integer" }, "total_jobs": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_FailedBuildJob": { "type": "object", "description": "A failed build job with triage and retry information.", "required": [ "job_id", "build_id", "status", "action", "created_at" ], "properties": { "job_id": { "type": "string", "format": "uuid" }, "build_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "retrying", "resolved", "abandoned" ] }, "action": { "type": "string", "enum": [ "repackage", "submit_to_store" ] }, "failure_reason": { "type": "string", "nullable": true }, "retry_count": { "type": "integer" }, "last_retried_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_MarketplaceListing": { "type": "object", "description": "A published marketplace listing (public view).", "required": [ "listing_id", "title", "category", "pricing_type", "created_at" ], "properties": { "listing_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "maxLength": 10000, "nullable": true }, "category": { "type": "string", "maxLength": 100 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "pricing_type": { "type": "string", "enum": [ "free", "one_time", "subscription" ] }, "price_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "rating": { "type": "number", "nullable": true }, "download_count": { "type": "integer" }, "screenshots": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 50 }, "created_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_MarketplaceListingAdmin": { "description": "A marketplace listing with management-level fields (including draft/suspended status).", "allOf": [ { "$ref": "#/components/schemas/SaasPlatform_MarketplaceListing" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "pending_review", "published", "suspended" ] }, "publisher_org_id": { "type": "string", "format": "uuid" }, "template_id": { "type": "string", "format": "uuid", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "SaasPlatform_MarketplaceReview": { "type": "object", "description": "A review for a marketplace listing.", "required": [ "review_id", "listing_id", "rating", "created_at" ], "properties": { "review_id": { "type": "string", "format": "uuid" }, "listing_id": { "type": "string", "format": "uuid" }, "publisher_org_id": { "type": "string", "format": "uuid", "nullable": true }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "review_text": { "type": "string", "maxLength": 10000, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_MarketplaceSubscription": { "type": "object", "description": "A subscription to a marketplace listing.", "required": [ "subscription_id", "listing_id", "subscriber_org_id", "created_at" ], "properties": { "subscription_id": { "type": "string", "format": "uuid" }, "listing_id": { "type": "string", "format": "uuid" }, "publisher_org_id": { "type": "string", "format": "uuid", "nullable": true }, "subscriber_org_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_MarketplacePackage": { "type": "object", "description": "A SaaS package available in the marketplace.", "required": [ "package_id", "name", "created_at" ], "properties": { "package_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "logo_url": { "type": "string", "format": "uri", "nullable": true }, "slug": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_PricingPlan": { "type": "object", "description": "A pricing plan for a SaaS package.", "required": [ "plan_id", "saas_package_id", "name", "created_at" ], "properties": { "plan_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "price_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "billing_interval": { "type": "string", "enum": [ "monthly", "yearly", "one_time" ], "nullable": true }, "features": { "type": "array", "items": { "type": "string" }, "nullable": true }, "visibility": { "type": "string", "enum": [ "public", "signup", "private" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_Addon": { "type": "object", "description": "An add-on for a SaaS package.", "required": [ "addon_id", "saas_package_id", "name", "created_at" ], "properties": { "addon_id": { "type": "string", "format": "uuid" }, "saas_package_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "price_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "compatible_plan_slugs": { "type": "array", "items": { "type": "string" }, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_ResolvedDomain": { "type": "object", "description": "Domain resolution result mapping a custom domain to its associated SaaS package.", "required": [ "domain", "saas_package_id" ], "properties": { "domain": { "type": "string" }, "saas_package_id": { "type": "string", "format": "uuid" }, "package_name": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "logo_url": { "type": "string", "format": "uri", "nullable": true } } }, "SaasPlatform_AppConfigPublic": { "type": "object", "description": "Public app configuration returned by the marketplace app-config endpoint.", "required": [ "saas_package_id" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "domain": { "type": "string", "nullable": true }, "platform_configs": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Keyed by platform name. Each value is the platform-specific configuration object." } } }, "SaasPlatform_BuildTarget": { "type": "object", "description": "A build target (platform + environment combination).", "required": [ "platform", "environment" ], "properties": { "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux", "web" ] }, "environment": { "type": "string", "enum": [ "development", "staging", "preprod", "production" ] }, "saas_package_id": { "type": "string", "format": "uuid", "nullable": true }, "org_id": { "type": "string", "format": "uuid", "nullable": true }, "binary_id": { "type": "string", "format": "uuid", "nullable": true }, "is_available": { "type": "boolean" } } }, "SaasPlatform_DeprovisionRequest": { "type": "object", "description": "Optional request body for deprovisioning a tenant. The body may be omitted entirely.", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Human-readable reason for deprovisioning, recorded in the audit log." } } }, "SaasPlatform_TenantProvisionRequest": { "type": "object", "description": "Request body for provisioning a new tenant.", "required": [ "saas_package_id", "tenant_name", "tenant_slug" ], "additionalProperties": false, "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "tenant_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "tenant_slug": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9-]+$" }, "admin_user_id": { "type": "string", "format": "uuid" }, "admin_email": { "type": "string", "format": "email" }, "admin_display_name": { "type": "string", "maxLength": 255 }, "tenant_settings": { "type": "object" } } }, "SaasPlatform_CustomerSubscriptionCreateRequest": { "type": "object", "description": "Request body for creating a customer subscription.", "required": [ "pricing_plan_id", "subscriber_org_id" ], "additionalProperties": false, "properties": { "pricing_plan_id": { "type": "string", "format": "uuid" }, "subscriber_org_id": { "type": "string", "format": "uuid" }, "stripe_subscription_id": { "type": "string", "maxLength": 255 }, "quantity": { "type": "integer", "minimum": 1 } } }, "SaasPlatform_CustomerSubscriptionUpdateRequest": { "type": "object", "description": "Request body for updating a customer subscription. At least one field must be provided.", "additionalProperties": false, "properties": { "pricing_plan_id": { "type": "string", "format": "uuid", "description": "New pricing plan for the subscription." }, "quantity": { "type": "integer", "minimum": 1 }, "stripe_subscription_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "metadata": { "type": "object", "description": "Arbitrary JSON metadata for the subscription." } } }, "SaasPlatform_AppConfigCreateRequest": { "type": "object", "description": "Request body for creating an app config.", "required": [ "saas_package_id", "platform" ], "additionalProperties": false, "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux", "web" ] }, "bundle_id": { "type": "string" }, "version_name": { "type": "string" }, "version_code": { "type": "integer" }, "config_data": { "type": "object" } } }, "SaasPlatform_AppConfigUpdateRequest": { "type": "object", "description": "Request body for updating an app config. At least one field required.", "additionalProperties": false, "properties": { "bundle_id": { "type": "string" }, "version_name": { "type": "string" }, "version_code": { "type": "integer" }, "config_data": { "type": "object" } } }, "SaasPlatform_DataBundleCreateRequest": { "type": "object", "description": "Request body for creating a data bundle.", "required": [ "saas_package_id", "version" ], "additionalProperties": false, "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "description": { "type": "string" }, "bundle_url": { "type": "string", "format": "uri" } } }, "SaasPlatform_BuildJobCreateRequest": { "type": "object", "description": "Request body for creating a build job. Web is not a valid platform.", "required": [ "saas_package_id", "platform", "build_system", "build_type" ], "additionalProperties": false, "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "app_config_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux" ] }, "build_system": { "type": "string", "enum": [ "cloudflare_container", "codemagic", "eas_build", "self_hosted_mac" ] }, "build_type": { "type": "string", "enum": [ "development", "preview", "production" ] }, "build_config": { "type": "object" } } }, "SaasPlatform_BuildStatusUpdateRequest": { "type": "object", "description": "Request body for updating a build job's status.", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pending", "queued", "in_progress", "success", "failed", "cancelled" ] }, "error_message": { "type": "string" }, "artifact_url": { "type": "string", "format": "uri" } } }, "SaasPlatform_ScreenDefinitionCreateRequest": { "type": "object", "description": "Request body for creating a screen definition.", "required": [ "saas_package_id", "screen_key", "screen_type" ], "additionalProperties": false, "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "screen_key": { "type": "string" }, "screen_type": { "type": "string", "enum": [ "core", "custom", "view_based" ] }, "display_name": { "type": "string" }, "layout_config": { "type": "object" }, "is_active": { "type": "boolean" } } }, "SaasPlatform_ScreenDefinitionUpdateRequest": { "type": "object", "description": "Request body for updating a screen definition.", "additionalProperties": false, "properties": { "display_name": { "type": "string" }, "layout_config": { "type": "object" }, "is_active": { "type": "boolean" } } }, "SaasPlatform_StoreAccountCreateRequest": { "type": "object", "description": "Request body for creating a store account.", "required": [ "saas_package_id", "platform", "account_type", "account_name" ], "additionalProperties": false, "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] }, "account_type": { "type": "string", "enum": [ "apple_app_store_connect", "google_play_console", "microsoft_partner_center" ] }, "account_name": { "type": "string" }, "credentials": { "type": "object", "description": "Platform-specific credential fields. Encrypted at rest." } } }, "SaasPlatform_StoreAccountUpdateRequest": { "type": "object", "description": "Request body for updating a store account.", "additionalProperties": false, "properties": { "account_name": { "type": "string" }, "credentials": { "type": "object", "description": "Platform-specific credential fields. Encrypted at rest." }, "is_active": { "type": "boolean" } } }, "SaasPlatform_StoreListingCreateRequest": { "type": "object", "description": "Request body for creating a store listing. Textual content fields are evaluated against the platform content policy before storage.", "required": [ "saas_package_id", "app_title", "platform" ], "additionalProperties": false, "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] }, "app_title": { "type": "string", "maxLength": 255 }, "short_description": { "type": "string", "maxLength": 500 }, "full_description": { "type": "string", "maxLength": 8000 }, "keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "screenshots": { "type": "array", "items": { "type": "string", "format": "uri" } }, "icon_url": { "type": "string", "format": "uri" } } }, "SaasPlatform_StoreListingUpdateRequest": { "type": "object", "description": "Request body for updating a store listing. Textual content fields are re-evaluated against the platform content policy.", "additionalProperties": false, "properties": { "app_title": { "type": "string", "maxLength": 255 }, "short_description": { "type": "string", "maxLength": 500 }, "full_description": { "type": "string", "maxLength": 8000 }, "keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "screenshots": { "type": "array", "items": { "type": "string", "format": "uri" } }, "icon_url": { "type": "string", "format": "uri" } } }, "SaasPlatform_ComplianceCheckRequest": { "type": "object", "description": "Request body for the local compliance pre-check (submission-level).", "required": [ "submission_id" ], "properties": { "submission_id": { "type": "string", "format": "uuid" } } }, "SaasPlatform_DbComplianceCheckRequest": { "type": "object", "description": "Request body for the database-backed compliance check.", "required": [ "saas_package_id" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] } } }, "SaasPlatform_AgeRatingCreateRequest": { "type": "object", "description": "Request body for creating an age rating.", "required": [ "saas_package_id", "platform", "rating_category" ], "additionalProperties": false, "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos" ] }, "rating_category": { "type": "string" }, "content_descriptors": { "type": "array", "items": { "type": "string" } }, "questionnaire_answers": { "type": "object" } } }, "SaasPlatform_AgeRatingUpdateRequest": { "type": "object", "description": "Request body for updating an age rating.", "additionalProperties": false, "properties": { "rating_category": { "type": "string" }, "content_descriptors": { "type": "array", "items": { "type": "string" } }, "questionnaire_answers": { "type": "object" } } }, "SaasPlatform_KycSessionCreateRequest": { "type": "object", "description": "Request body for creating a KYC session.", "required": [ "saas_package_id" ], "properties": { "saas_package_id": { "type": "string", "format": "uuid" }, "return_url": { "type": "string", "format": "uri", "description": "URL to redirect to after KYC completion." } } }, "SaasPlatform_BaseBinaryCreateRequest": { "type": "object", "description": "Request body for registering a base binary.", "required": [ "platform", "release_version", "build_number" ], "additionalProperties": false, "properties": { "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux" ] }, "release_version": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Human-readable release version (e.g. `1.0.0`)." }, "build_number": { "type": "integer", "minimum": 1, "description": "Monotonically increasing build number." }, "artifact_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "artifact_hash": { "type": "string", "maxLength": 128, "description": "SHA-256 or similar hash of the artifact for integrity verification." }, "artifact_size_bytes": { "type": "integer", "minimum": 0 }, "build_system": { "type": "string", "maxLength": 128 }, "git_commit_sha": { "type": "string", "maxLength": 64 } } }, "SaasPlatform_BaseBinaryStatusUpdateRequest": { "type": "object", "description": "Request body for updating a base binary's status. Status transitions: only `ready`, `deprecated`, or `failed` are accepted.", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "ready", "deprecated", "failed" ] }, "artifact_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "artifact_hash": { "type": "string", "maxLength": 128 }, "artifact_size_bytes": { "type": "integer", "minimum": 0 }, "error_details": { "type": "object", "description": "Structured error details for failed binaries." } } }, "SaasPlatform_ReleaseBatchCreateRequest": { "type": "object", "description": "Request body for creating a release batch.", "required": [ "base_binary_id", "platform" ], "additionalProperties": false, "properties": { "base_binary_id": { "type": "string", "format": "uuid", "description": "Base binary to roll out in this batch." }, "platform": { "type": "string", "enum": [ "ios", "android", "windows", "macos", "linux" ] }, "rollout_strategy": { "type": "string", "enum": [ "all_at_once", "staged_percentage", "staged_manual" ] }, "rollout_percentage": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "SaasPlatform_BatchProgressRequest": { "type": "object", "description": "Request body for reporting batch progress. All increment fields and status are optional; omit any field to leave it unchanged.", "additionalProperties": false, "properties": { "increment_completed": { "type": "integer", "minimum": 0, "description": "Number of successfully completed jobs to add to the batch counter." }, "increment_failed": { "type": "integer", "minimum": 0, "description": "Number of failed jobs to add to the batch counter." }, "increment_skipped": { "type": "integer", "minimum": 0, "description": "Number of skipped jobs to add to the batch counter." }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed", "cancelled" ] }, "error_details": { "type": "object", "description": "Structured error details for failed batches." } } }, "SaasPlatform_MarketplaceListingCreateRequest": { "type": "object", "description": "Request body for creating a marketplace listing.", "required": [ "title", "category", "pricing_type" ], "additionalProperties": false, "properties": { "template_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "maxLength": 10000 }, "category": { "type": "string", "maxLength": 100 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "pricing_type": { "type": "string", "enum": [ "free", "one_time", "subscription" ] }, "price_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "screenshots": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 50 } } }, "SaasPlatform_MarketplaceListingUpdateRequest": { "type": "object", "description": "Request body for partially updating a marketplace listing.", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "maxLength": 10000 }, "category": { "type": "string", "maxLength": 100 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "pricing_type": { "type": "string", "enum": [ "free", "one_time", "subscription" ] }, "price_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "screenshots": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 50 }, "status": { "type": "string", "enum": [ "draft", "pending_review", "published", "suspended" ] } } }, "SaasPlatform_MarketplaceReviewCreateRequest": { "type": "object", "description": "Request body for creating a marketplace review.", "required": [ "listing_id", "rating" ], "additionalProperties": false, "properties": { "listing_id": { "type": "string", "format": "uuid" }, "publisher_org_id": { "type": "string", "format": "uuid" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "review_text": { "type": "string", "maxLength": 10000 } } }, "SaasPlatform_MarketplaceSubscriptionCreateRequest": { "type": "object", "description": "Request body for creating a marketplace subscription.", "required": [ "listing_id" ], "additionalProperties": false, "properties": { "listing_id": { "type": "string", "format": "uuid" }, "publisher_org_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" } } }, "SaasPlatform_MarketingEventBatchRequest": { "type": "object", "description": "A batch of marketing analytics events. Maximum 25 events per request. Maximum 100 KB total. This endpoint requires service authorization — unauthorized calls return 403.", "required": [ "events" ], "properties": { "events": { "type": "array", "maxItems": 25, "items": { "type": "object", "required": [ "eventId", "product", "visitorId", "sessionId", "eventName" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Unique event identifier for deduplication." }, "product": { "type": "string", "description": "Product identifier the event originated from." }, "visitorId": { "type": "string", "format": "uuid", "description": "Anonymous visitor identifier." }, "sessionId": { "type": "string", "format": "uuid", "description": "Session identifier." }, "eventName": { "type": "string", "description": "Name of the event (e.g. `page_view`, `cta_click`)." }, "organizationId": { "type": "string", "format": "uuid", "description": "Organization identifier when the event is authenticated to an org." } }, "additionalProperties": true } } } }, "ScienceAcademic_VerificationInitiateRequest": { "type": "object", "additionalProperties": false, "required": [ "requested_plan_slug" ], "description": "Initiate-verification body. `org_id`/`user_id`/`plan_key` are NOT accepted (pinned from the session / SP).", "properties": { "requested_plan_slug": { "type": "string", "enum": [ "academic_free" ], "description": "The verification-gated plan being requested." }, "return_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS URL the verified user is redirected back to after the KYC handoff. Must be https (a javascript: or other scheme is rejected)." } } }, "ScienceAcademic_SubscriptionCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "verification_id" ], "properties": { "verification_id": { "type": "string", "format": "uuid", "description": "A completed verification to consume." } } }, "ScienceAcademic_SubscriptionRenewRequest": { "type": "object", "additionalProperties": false, "required": [ "verification_id" ], "properties": { "verification_id": { "type": "string", "format": "uuid", "description": "A fresh completed verification to consume for the renewal." } } }, "ScienceAcademic_BulkImportRequest": { "type": "object", "additionalProperties": false, "required": [ "rows" ], "properties": { "rows": { "type": "array", "minItems": 1, "maxItems": 500, "description": "Verification rows to create.", "items": { "type": "object", "additionalProperties": false, "required": [ "subject_user_id", "institution_name", "role" ], "properties": { "subject_user_id": { "type": "string", "format": "uuid", "description": "The subject user the verification is for." }, "institution_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Verified institution name." }, "role": { "type": "string", "enum": [ "student", "faculty", "staff", "researcher" ], "description": "Academic role." }, "saas_package_id": { "type": "string", "format": "uuid", "description": "Target SaaS package (defaults to the Science package)." }, "expires_at": { "type": "string", "format": "date-time", "description": "Verification expiry." } } } }, "provider": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Source provider/label for the import batch." } } }, "ScienceAcademic_EraseRequest": { "type": "object", "additionalProperties": false, "description": "Erase body. Omit `user_id` to erase your own data; provide it (with review/super-admin authority) to target another subject.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "Subject to erase (defaults to the caller)." } } }, "ScienceAcademic_VerificationInitiateResult": { "type": "object", "description": "Result of initiating a verification.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Verification id." }, "org_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "Verification status." }, "requested_plan_slug": { "type": "string", "description": "The requested plan." }, "created_at": { "type": "string", "format": "date-time" }, "reused": { "type": "boolean", "description": "True when an existing in-flight verification was returned." } } }, "ScienceAcademic_Verification": { "type": "object", "description": "An academic verification record.", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "requested_plan_slug": { "type": "string" }, "didit_session_id": { "type": [ "string", "null" ], "description": "External KYC session reference." }, "status": { "type": "string", "description": "e.g. pending, completed, declined, expired." }, "document_type": { "type": [ "string", "null" ] }, "document_country": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "declined_reason": { "type": [ "string", "null" ] }, "consumed_subscription_id": { "type": [ "string", "null" ], "format": "uuid" }, "consumed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ScienceAcademic_Subscription": { "type": "object", "description": "An academic subscription record.", "properties": { "subscription_id": { "type": "string", "format": "uuid" }, "plan_key": { "type": "string", "description": "The academic plan key." }, "status": { "type": "string", "description": "Subscription status." }, "cancel_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true }, "reused": { "type": "boolean", "description": "True when an existing subscription was returned." } } }, "ScienceStudio_CloneRequest": { "type": "object", "additionalProperties": false, "description": "Request body for cloning the canonical Substrate Framework into the caller's organization. All fields are optional; the SP provides defaults when omitted.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name for the cloned project. Defaults to `'Substrate Framework'` when omitted." }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9 _-]*$", "description": "URL-safe slug for the cloned project (1–100 chars; must start with alphanumeric; allowed characters: `a-z A-Z 0-9 space _ -`). Defaults to `'substrate-framework'` when omitted." } } }, "ScienceStudio_ForkRequest": { "type": "object", "additionalProperties": false, "description": "Request body for forking a read-only Substrate clone. `source_project_id` is required; name and slug are optional.", "required": [ "source_project_id" ], "properties": { "source_project_id": { "type": "string", "format": "uuid", "description": "UUIDv7 of the existing read-only Substrate clone to fork. Must belong to the caller's organization." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name for the forked project. Defaults to a platform-generated name when omitted." }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9 _-]*$", "description": "URL-safe slug for the forked project (1–100 chars; must start with alphanumeric; allowed characters: `a-z A-Z 0-9 space _ -`). Auto-generated from the name when omitted." } } }, "ScienceStudio_SubstrateCloneResult": { "type": "object", "description": "Result of a successful Substrate Framework clone operation.", "required": [ "project_id", "cloned_from", "org_id", "documents_cloned", "already_existed", "backfilled" ], "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Platform-assigned identifier (UUIDv7) of the newly created or existing clone project." }, "cloned_from": { "type": "string", "format": "uuid", "description": "Identifier of the canonical Substrate source project that was cloned." }, "org_id": { "type": "string", "format": "uuid", "description": "Organization that received the clone." }, "documents_cloned": { "type": "integer", "minimum": 0, "description": "Number of documents copied into the clone project." }, "already_existed": { "type": "boolean", "description": "`true` when a clone already existed for this organization and was not re-created." }, "backfilled": { "type": "boolean", "description": "`true` when the existing clone was missing some documents and they were backfilled from the canonical source." } } }, "ScienceStudio_SubstrateForkResult": { "type": "object", "description": "Result of a successful Substrate clone fork operation.", "required": [ "project_id", "forked_from", "org_id", "documents_forked" ], "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Platform-assigned identifier (UUIDv7) of the newly created editable fork project." }, "forked_from": { "type": "string", "format": "uuid", "description": "Identifier of the source read-only clone that was forked." }, "org_id": { "type": "string", "format": "uuid", "description": "Organization that owns the fork." }, "documents_forked": { "type": "integer", "minimum": 0, "description": "Number of documents copied into the fork project." } } }, "ScienceStudio_Production": { "type": "object", "description": "A Scripted Media Studio production record.", "required": [ "id", "org_id", "project_id", "title", "slug", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Platform-assigned production identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "project_id": { "type": "string", "format": "uuid", "description": "Project that contains this production." }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display title of the production." }, "slug": { "type": "string", "minLength": 1, "maxLength": 120, "description": "URL-safe slug for the production (unique within the project)." }, "status": { "type": "string", "description": "Lifecycle status (e.g. `draft`, `generating`, `published`, `failed`)." }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "User who created the production." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last-update timestamp." } } }, "ScienceStudio_ProductionCreateRequest": { "type": "object", "additionalProperties": true, "description": "Request body for creating a new production. `title` and `slug` are required; additional content is set via the dedicated content-setter endpoints. Additional fields are forwarded to the SP.", "required": [ "title", "slug" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display title of the production." }, "slug": { "type": "string", "minLength": 1, "maxLength": 120, "description": "URL-safe slug (unique within the project)." } } }, "ScienceStudio_ProductionUpdateRequest": { "type": "object", "description": "Partial update for a production's top-level metadata fields. The SP validates and applies only the supplied fields. At least one field must be present.", "minProperties": 1, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "New production title." }, "slug": { "type": "string", "minLength": 1, "maxLength": 120, "description": "New URL-safe slug (unique within the project)." }, "status": { "type": "string", "description": "New lifecycle status." } }, "additionalProperties": true }, "ScienceStudio_ContentSetRequest": { "type": "object", "description": "Generic replace-the-set content body. The SP is the authority for structure validation; the route passes the full body through. This schema accepts any well-formed JSON object.", "additionalProperties": true }, "ScienceStudio_ScriptContent": { "type": "object", "description": "A production script version record.", "required": [ "production_id", "version" ], "properties": { "production_id": { "type": "string", "format": "uuid", "description": "Production this script version belongs to." }, "version": { "type": "integer", "description": "Script version number (monotonically increasing)." }, "sections": { "type": "array", "description": "Ordered list of script sections (e.g. intro, body, outro). Each section contains one or more segments with speaker and text assignments.", "items": { "type": "object", "additionalProperties": true } }, "created_at": { "type": "string", "format": "date-time", "description": "When this version was saved." } } }, "ScienceStudio_ScriptSetRequest": { "type": "object", "description": "Request body for replacing the production script. The SP performs strict validation of the nested sections/segments/speaker structure.", "additionalProperties": true }, "ScienceStudio_LinkSecretRequest": { "type": "object", "additionalProperties": false, "description": "Request body for linking a vault-stored credential to a production for renderer injection. The secret value never passes through this endpoint; only the vault reference and injection metadata are stored.", "required": [ "vault_id", "item_key", "purpose" ], "properties": { "vault_id": { "type": "string", "format": "uuid", "description": "UUIDv7 of the vault containing the secret." }, "item_key": { "type": "string", "minLength": 1, "description": "Key of the secret item within the vault." }, "purpose": { "type": "string", "minLength": 1, "description": "Human-readable description of the link's purpose (e.g. `'TTS synthesis'`)." }, "allowed_origin": { "type": "string", "description": "Optional origin constraint restricting where the renderer may present this credential (e.g. `'https://api.elevenlabs.io'`)." }, "injection_field": { "type": "string", "description": "Optional target field or header name the renderer should inject the credential value into (e.g. `'x-api-key'`)." } } }, "ScienceStudio_SecretLink": { "type": "object", "description": "A vault-to-production secret link record. The vault item value is never included.", "required": [ "link_id", "production_id", "vault_id", "item_key", "purpose", "created_at" ], "properties": { "link_id": { "type": "string", "format": "uuid", "description": "Platform-assigned link identifier (UUIDv7)." }, "production_id": { "type": "string", "format": "uuid", "description": "Production this link belongs to." }, "vault_id": { "type": "string", "format": "uuid", "description": "Vault containing the linked secret." }, "item_key": { "type": "string", "description": "Key of the secret item within the vault." }, "purpose": { "type": "string", "description": "Declared purpose of the link." }, "allowed_origin": { "type": [ "string", "null" ], "description": "Optional origin constraint for the credential." }, "injection_field": { "type": [ "string", "null" ], "description": "Optional target field for injection." }, "created_at": { "type": "string", "format": "date-time", "description": "When the link was created." } } }, "ScienceStudio_EstimateResult": { "type": "object", "description": "A preflight render-cost estimate for the production. No credits are reserved or spent.", "properties": { "estimated_credits": { "type": "number", "description": "Predicted render credit cost if generate were called now with the same mode." }, "mode": { "type": "string", "enum": [ "audio", "video", "full" ], "description": "Render mode the estimate applies to." }, "cache_hit": { "type": "boolean", "description": "Whether the estimate predicts a full cache hit (no credits would be spent)." }, "gates": { "type": "object", "description": "Predicted state of the three render change-gates (script→TTS, audio→STT, visuals→render). Present but structure is SP-determined.", "additionalProperties": true } } }, "ScienceStudio_GenerateRequest": { "type": "object", "description": "Request body for generating (rendering) a production.", "properties": { "safety_factor": { "type": "number", "exclusiveMinimum": 0, "description": "Optional safety multiplier for credit cost estimation. Must be positive." }, "estimate": { "type": "boolean", "description": "When `true`, returns only the credit estimate without enqueuing a render job (dry-run mode)." }, "mode": { "type": "string", "enum": [ "audio", "video", "full" ], "description": "Render scope: `audio` re-synthesizes narration only; `video` renders video against existing audio; `full` (default) synthesizes audio first if changed, then renders video." } }, "additionalProperties": true }, "ScienceStudio_GenerateResult": { "type": "object", "description": "Result of enqueuing a render job.", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Platform-assigned render job identifier (UUIDv7). Poll `GET /v1/projects/{projectId}/studio/jobs/{jobId}` for status." }, "estimated_credits": { "type": "number", "description": "Predicted credit cost for this render job." }, "mode": { "type": "string", "enum": [ "audio", "video", "full" ], "description": "Render mode that was applied." }, "gates": { "type": "object", "description": "Predicted state of the three render change-gates.", "additionalProperties": true } } }, "ScienceStudio_JobStatus": { "type": "object", "description": "Status and progress record for a Studio render job.", "required": [ "job_id", "status" ], "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Render job identifier." }, "production_id": { "type": "string", "format": "uuid", "description": "Production this job belongs to." }, "status": { "type": "string", "enum": [ "queued", "generating_audio", "generating_video", "compositing", "completed", "failed" ], "description": "Current lifecycle status of the render job." }, "progress_pct": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100, "description": "Percentage completion (0–100), or `null` while the job is queued." }, "error_message": { "type": [ "string", "null" ], "description": "Human-readable error description when `status` is `failed`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the job was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the job was last updated." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the job completed (or `null` if still in progress)." } } }, "ScienceStudio_OutputRecord": { "type": "object", "description": "A composed render output record. Raw pipeline captures are never returned.", "required": [ "output_id", "production_id", "format", "r2_key" ], "properties": { "output_id": { "type": "string", "format": "uuid", "description": "Platform-assigned output identifier (UUIDv7)." }, "production_id": { "type": "string", "format": "uuid", "description": "Production this output belongs to." }, "render_id": { "type": "string", "format": "uuid", "description": "Render job that produced this output." }, "format": { "type": "string", "description": "Output format key (e.g. `mp4_9_16`, `mp4_16_9`)." }, "r2_key": { "type": "string", "description": "Storage key for the composed output file. Note: a future update will replace this with a short-TTL presigned URL." }, "mime": { "type": "string", "description": "MIME type of the output file." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Duration of the rendered output in milliseconds." }, "created_at": { "type": "string", "format": "date-time", "description": "When the output was composed." } } }, "ScienceStudio_Voice": { "type": "object", "description": "A TTS voice available in the organization's voice library.", "required": [ "voice_id", "display_name", "is_custom" ], "properties": { "voice_id": { "type": "string", "format": "uuid", "description": "Platform-assigned voice identifier (UUIDv7)." }, "provider_voice_id": { "type": [ "string", "null" ], "description": "External provider identifier for custom voices (e.g. ElevenLabs voice id)." }, "display_name": { "type": "string", "description": "Human-readable voice name for display in the Studio editor." }, "is_custom": { "type": "boolean", "description": "`true` for organization-added custom voices; `false` for platform built-in voices." }, "created_at": { "type": "string", "format": "date-time", "description": "When the voice was added." } } }, "ScienceStudio_VoiceAddRequest": { "type": "object", "description": "Request body for registering a custom TTS provider voice in the organization's voice library.", "required": [ "provider_voice_id", "display_name" ], "properties": { "provider_voice_id": { "type": "string", "minLength": 1, "description": "External provider identifier for the voice (e.g. ElevenLabs voice id)." }, "display_name": { "type": "string", "minLength": 1, "description": "Human-readable display name for the voice in the Studio editor." } }, "additionalProperties": true }, "ScienceStudio_MediaAsset": { "type": "object", "description": "A media asset record in the organization's media library.", "required": [ "asset_id", "org_id", "kind", "mime" ], "properties": { "asset_id": { "type": "string", "format": "uuid", "description": "Platform-assigned asset identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "kind": { "type": "string", "enum": [ "music", "sfx" ], "description": "Asset category." }, "mime": { "type": "string", "description": "MIME type of the asset." }, "duration_ms": { "type": [ "integer", "null" ], "minimum": 0, "description": "Duration of the audio asset in milliseconds." }, "r2_key": { "type": [ "string", "null" ], "description": "Storage key for the asset bytes in R2 (server-assigned)." }, "checksum_sha256": { "type": [ "string", "null" ], "description": "SHA-256 hex digest of the asset bytes." }, "created_at": { "type": "string", "format": "date-time", "description": "When the asset was registered." } } }, "ScienceStudio_UploadAudioRequest": { "type": "object", "additionalProperties": false, "description": "Request body for uploading an audio file to the org media library. Audio bytes are supplied as a base64-encoded string. Maximum decoded size is 25 MB.", "required": [ "kind", "mime", "data_base64" ], "properties": { "kind": { "type": "string", "enum": [ "music", "sfx" ], "description": "Asset category: `music` for background tracks, `sfx` for sound effects." }, "mime": { "type": "string", "minLength": 1, "maxLength": 100, "description": "MIME type of the audio file (e.g. `audio/mpeg`, `audio/wav`, `audio/ogg`, `audio/flac`). Must be in the platform audio allow-list." }, "filename": { "type": "string", "maxLength": 255, "description": "Optional original filename for display purposes." }, "data_base64": { "type": "string", "minLength": 1, "description": "Base64-encoded audio file bytes. Maximum decoded size is 25 MB." }, "duration_ms": { "type": "integer", "minimum": 0, "maximum": 86400000, "description": "Optional audio duration in milliseconds (0–86 400 000). When omitted the renderer measures it during the first render pass." } } }, "ScienceStudio_ShapeRecord": { "type": "object", "description": "A shape asset record in the organization's shape library.", "required": [ "shape_id", "org_id" ], "properties": { "shape_id": { "type": "string", "format": "uuid", "description": "Platform-assigned shape identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name for the shape." }, "created_at": { "type": "string", "format": "date-time", "description": "When the shape was imported." } } }, "Security_RoleListData": { "type": "object", "required": [ "roles", "total_count" ], "additionalProperties": false, "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/Security_Role" } }, "total_count": { "type": "integer", "minimum": 0, "description": "Total matching roles (for pagination)." } } }, "Security_Role": { "type": "object", "required": [ "id", "name", "is_system", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 150, "pattern": "^[a-z0-9][a-z0-9._-]*$", "description": "Role slug key." }, "name": { "type": "string", "minLength": 1, "maxLength": 150, "description": "Display name." }, "description": { "type": [ "string", "null" ], "description": "Optional description." }, "is_system": { "type": "boolean", "description": "True for platform-defined catalog roles. System roles cannot be modified by clients." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permission slugs assigned to this role." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Arbitrary metadata." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Security_RoleCreateRequest": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 150, "description": "Role display name. Must be unique within the organization." }, "description": { "type": "string", "maxLength": 1000, "description": "Optional description." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Optional initial set of permission slugs. Unknown slugs are rejected." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Arbitrary metadata." } } }, "Security_RoleUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 150 }, "description": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Full replacement permission slug set." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true } } }, "Security_PermissionListData": { "type": "object", "required": [ "permissions", "total_count" ], "additionalProperties": false, "properties": { "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Security_Permission" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "Security_Permission": { "type": "object", "required": [ "id", "name", "resource", "action" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Dot-notation permission slug." }, "description": { "type": [ "string", "null" ] }, "resource": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Resource dimension (e.g. `project`, `org`)." }, "action": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Action dimension (e.g. `view`, `manage_roles`)." }, "is_system": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Security_PermissionCreateRequest": { "type": "object", "required": [ "name", "resource", "action" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Dot-notation permission slug. Must be unique." }, "description": { "type": "string", "description": "Optional description." }, "resource": { "type": "string", "minLength": 1, "maxLength": 100 }, "action": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "Security_PolicyListData": { "type": "object", "required": [ "policies", "total_count" ], "additionalProperties": false, "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Security_Policy" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "Security_Policy": { "type": "object", "required": [ "id", "name", "effect", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Policy display name." }, "description": { "type": [ "string", "null" ] }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "description": "Policy effect." }, "resource_type": { "type": [ "string", "null" ], "maxLength": 500 }, "resource_pattern": { "type": [ "string", "null" ] }, "operation": { "type": [ "string", "null" ] }, "action_pattern": { "type": [ "string", "null" ] }, "conditions": { "type": [ "object", "null" ], "additionalProperties": true }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Security_PolicyCreateRequest": { "type": "object", "additionalProperties": false, "description": "At least one of `policy_name`/`name` is required; at least one of `resource_type`/`resource_pattern` is required; at least one of `operation`/`action_pattern` is required.", "properties": { "policy_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Alias for `policy_name`." }, "description": { "type": "string" }, "effect": { "type": "string", "enum": [ "allow", "deny" ] }, "resource_type": { "type": "string", "maxLength": 500 }, "resource_pattern": { "type": "string" }, "operation": { "type": "string" }, "action_pattern": { "type": "string" }, "conditions": { "type": "object", "additionalProperties": true }, "is_active": { "type": "boolean" } } }, "Security_PolicyUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": [ "string", "null" ] }, "effect": { "type": "string", "enum": [ "allow", "deny" ] }, "resource_type": { "type": [ "string", "null" ], "maxLength": 500 }, "resource_pattern": { "type": [ "string", "null" ] }, "operation": { "type": [ "string", "null" ] }, "action_pattern": { "type": [ "string", "null" ] }, "conditions": { "type": [ "object", "null" ], "additionalProperties": true }, "is_active": { "type": "boolean" } } }, "Security_DepartmentListData": { "type": "object", "required": [ "departments", "total_count" ], "additionalProperties": false, "properties": { "departments": { "type": "array", "items": { "$ref": "#/components/schemas/Security_Department" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "Security_Department": { "type": "object", "required": [ "id", "name", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Security_DepartmentCreateRequest": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string" } } }, "Security_DepartmentUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ] } } }, "Security_GroupListData": { "type": "object", "required": [ "groups", "total_count" ], "additionalProperties": false, "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Security_Group" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "Security_Group": { "type": "object", "required": [ "id", "name", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Security_GroupCreateRequest": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string" } } }, "Security_GroupUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ] } } }, "Security_SyncResult": { "type": "object", "additionalProperties": true, "description": "RBAC sync summary (roles added, permissions reconciled, policies refreshed, etc.)." }, "Security_Overview": { "type": "object", "additionalProperties": true, "description": "Security overview payload including alert counts, authentication metrics, health score, violation stats, and optional recommendations." }, "Security_AuditEventListData": { "type": "object", "required": [ "events", "total_count" ], "additionalProperties": false, "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/Security_AuditEvent" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "Security_AuditEvent": { "type": "object", "required": [ "id", "event_type", "action", "outcome", "severity", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "event_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "action": { "type": "string", "minLength": 1, "maxLength": 100 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 50 }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "risk_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "target_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "session_id": { "type": [ "string", "null" ] }, "ip_address": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] }, "resource_type": { "type": [ "string", "null" ], "maxLength": 100 }, "resource_id": { "type": [ "string", "null" ], "format": "uuid" }, "details": { "type": [ "object", "null" ], "additionalProperties": true }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Security_AuditEventCreateRequest": { "type": "object", "required": [ "event_type", "action", "outcome", "severity" ], "additionalProperties": false, "properties": { "event_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "action": { "type": "string", "minLength": 1, "maxLength": 100 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 50 }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "risk_score": { "type": "number", "minimum": 0, "maximum": 100 }, "target_user_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string" }, "ip_address": { "type": "string" }, "user_agent": { "type": "string" }, "resource_type": { "type": "string", "maxLength": 100 }, "resource_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true }, "expires_at": { "type": "string", "format": "date-time" } } }, "Security_AlertListData": { "type": "object", "required": [ "alerts", "total_count" ], "additionalProperties": false, "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/Security_Alert" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "Security_Alert": { "type": "object", "required": [ "id", "alert_type", "severity", "status", "title", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "alert_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "status": { "type": "string", "enum": [ "active", "acknowledged", "resolved", "false_positive" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "pattern_id": { "type": [ "string", "null" ] }, "risk_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "indicators": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "affected_resources": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "response_actions": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "recommendations": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "resolution_notes": { "type": [ "string", "null" ], "maxLength": 5000 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Security_AlertCreateRequest": { "type": "object", "required": [ "alert_type", "severity", "title" ], "additionalProperties": false, "properties": { "alert_type": { "type": "string", "minLength": 1, "maxLength": 100 }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "status": { "type": "string", "enum": [ "active", "acknowledged", "resolved", "false_positive" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "maxLength": 5000 }, "pattern_id": { "type": "string" }, "risk_score": { "type": "number", "minimum": 0, "maximum": 100 }, "indicators": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "affected_resources": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "response_actions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recommendations": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": true }, "expires_at": { "type": "string", "format": "date-time" } } }, "Security_AlertUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "active", "acknowledged", "resolved", "false_positive" ] }, "resolution_notes": { "type": "string", "maxLength": 5000 }, "metadata": { "type": "object", "additionalProperties": true } } }, "Security_DsarCreateRequest": { "type": "object", "required": [ "request_type", "subject_email" ], "additionalProperties": false, "properties": { "request_type": { "type": "string", "enum": [ "access", "rectification", "erasure", "portability", "restriction", "objection" ], "description": "GDPR Art. 15-20 request type." }, "subject_email": { "type": "string", "format": "email", "maxLength": 320, "description": "Email address of the data subject." }, "subject_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Full name of the data subject." }, "description": { "type": "string", "maxLength": 5000 }, "data_categories": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "description": "Specific data categories in scope." }, "urgency": { "type": "string", "enum": [ "normal", "urgent" ] } } }, "Security_DsarRequest": { "type": "object", "required": [ "id", "request_type", "subject_email", "status", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "request_type": { "type": "string", "enum": [ "access", "rectification", "erasure", "portability", "restriction", "objection" ] }, "subject_email": { "type": "string", "format": "email" }, "subject_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "data_categories": { "type": [ "array", "null" ], "items": { "type": "string" } }, "urgency": { "type": "string", "enum": [ "normal", "urgent" ] }, "status": { "type": "string", "description": "Current status of the DSAR (e.g. `pending`, `in_progress`, `completed`, `rejected`)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Security_DsarListData": { "type": "object", "required": [ "requests", "total_count" ], "additionalProperties": false, "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/Security_DsarRequest" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "Security_DsarRestrictRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Optional reason for activating the processing restriction." } } }, "Security_DsarUnrestrictRequest": { "type": "object", "additionalProperties": false, "properties": { "user_id": { "type": "string", "format": "uuid", "description": "Target subject UUID. Omit to lift the restriction for the authenticated caller. Supply with `compliance.manage` to lift for another user." }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "Security_DsarObjectionRequest": { "type": "object", "required": [ "scope" ], "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "marketing", "analytics", "profiling", "all" ], "description": "Processing scope to object to. Use `all` to object to all scopes." }, "reason": { "type": "string", "maxLength": 2000 } } }, "Security_EmergencyAccessRequest": { "type": "object", "required": [ "reason", "target_resource_type", "target_resource_id" ], "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 2000, "description": "Mandatory justification for the break-glass access (minimum 10 characters)." }, "target_resource_type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Resource type being accessed under emergency." }, "target_resource_id": { "type": "string", "format": "uuid", "description": "UUID of the resource being accessed." }, "duration_minutes": { "type": "integer", "minimum": 5, "maximum": 480, "description": "Grant duration in minutes (default 60, max 480)." } } }, "Security_CookieConsentRequest": { "type": "object", "required": [ "consent_categories", "consent_given" ], "additionalProperties": false, "properties": { "consent_categories": { "type": "array", "items": { "type": "string", "enum": [ "necessary", "analytics", "marketing", "preferences" ] }, "description": "Cookie categories included in this consent decision." }, "consent_given": { "type": "boolean", "description": "Whether consent was given (`true`) or withdrawn (`false`)." }, "consent_method": { "type": "string", "enum": [ "banner", "settings", "api" ], "description": "How the consent was collected." } } }, "Security_MarketingConsentRequest": { "type": "object", "required": [ "consent_given" ], "additionalProperties": false, "properties": { "consent_given": { "type": "boolean" }, "consent_method": { "type": "string", "enum": [ "banner", "settings", "api" ] } } }, "Security_ParentalConsentRequest": { "type": "object", "required": [ "child_user_id", "parent_email", "consent_method", "consent_given" ], "additionalProperties": false, "properties": { "child_user_id": { "type": "string", "format": "uuid", "description": "UUID of the child user account requiring parental consent." }, "parent_email": { "type": "string", "format": "email", "maxLength": 320, "description": "Email address of the consenting parent/guardian." }, "consent_method": { "type": "string", "enum": [ "email_verification", "credit_card", "phone_call", "video_conference", "government_id" ], "description": "COPPA-approved verification method used to obtain consent." }, "consent_given": { "type": "boolean" } } }, "Security_ScannerTool": { "type": "string", "enum": [ "codeql", "semgrep", "gitleaks", "osv-scanner", "trivy", "zap", "nuclei", "garak", "promptfoo" ], "description": "Supported security scanner tool identifier." }, "Security_Finding": { "type": "object", "required": [ "fingerprint", "severity", "title" ], "additionalProperties": false, "properties": { "fingerprint": { "type": "string", "pattern": "^[0-9a-fA-F]{16,128}$", "description": "Hex fingerprint (16–128 chars) for deduplication." }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "rule_id": { "type": "string", "maxLength": 200, "description": "Scanner rule or check identifier." }, "title": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": { "type": "string", "maxLength": 20000 }, "location": { "type": "object", "additionalProperties": true, "description": "File/line/column location of the finding." }, "raw": { "type": "object", "additionalProperties": true, "description": "Original scanner output object (opaque)." } } }, "Security_FindingsIngestRequest": { "type": "object", "required": [ "findings" ], "additionalProperties": false, "properties": { "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Security_Finding" }, "maxItems": 1000, "description": "Batch of up to 1,000 normalized findings." }, "scan_run_id": { "type": "string", "format": "uuid", "description": "ID of the active scan run this batch belongs to." } } }, "Security_IngestResult": { "type": "object", "additionalProperties": false, "properties": { "ingested": { "type": "integer", "minimum": 0, "description": "Number of findings accepted." }, "deduplicated": { "type": "integer", "minimum": 0, "description": "Findings skipped because they match an existing fingerprint." }, "daily_quota_remaining": { "type": "integer", "minimum": 0, "description": "Findings remaining in today's quota (50,000/key/day)." } } }, "Security_ScanRun": { "type": "object", "required": [ "id", "tool", "status", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "tool": { "$ref": "#/components/schemas/Security_ScannerTool" }, "status": { "type": "string", "enum": [ "active", "finished", "failed" ] }, "findings_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Security_ScanRunListData": { "type": "object", "required": [ "scan_runs", "total_count" ], "additionalProperties": false, "properties": { "scan_runs": { "type": "array", "items": { "$ref": "#/components/schemas/Security_ScanRun" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "Security_FindingListData": { "type": "object", "required": [ "findings", "total_count" ], "additionalProperties": false, "properties": { "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Security_Finding" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "Security_McpRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "additionalProperties": true, "description": "JSON-RPC 2.0 request object.", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "description": "Request ID (string, integer, or null). Omit for notifications.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "initialize", "tools/list", "tools/call", "resources/list", "resources/read", "ping" ], "description": "MCP method name." }, "params": { "type": "object", "additionalProperties": true, "description": "Method-specific parameters." } } }, "Security_McpResponse": { "type": "object", "required": [ "jsonrpc" ], "additionalProperties": true, "description": "JSON-RPC 2.0 response object. Contains either `result` (on success) or `error` (on JSON-RPC-level error). HTTP status is always 200 for JSON-RPC responses per the JSON-RPC 2.0 spec.", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "description": "Mirrors the request ID.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "result": { "type": "object", "additionalProperties": true, "description": "Present on successful calls." }, "error": { "type": "object", "additionalProperties": false, "description": "Present on JSON-RPC-level errors.", "properties": { "code": { "type": "integer", "description": "JSON-RPC error code." }, "message": { "type": "string" }, "data": { "description": "Optional error detail.", "additionalProperties": true } } } } }, "SheetsSlidesCollaboration_DocumentRecord": { "type": "object", "description": "A document catalog record (applies to both BB Sheets spreadsheets and BB Slides decks).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Platform-assigned document identifier (UUIDv7)." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization identifier." }, "project_id": { "type": "string", "format": "uuid", "description": "Owning project identifier." }, "name": { "type": "string", "description": "Document display name." }, "content_type": { "type": "string", "description": "MIME type identifying the document kind (e.g. `application/x-bbsheet` or `application/x-bbslides`)." }, "created_by_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "User who created the document." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last-update timestamp." } } }, "SheetsSlidesCollaboration_CreateSheetRequest": { "type": "object", "additionalProperties": false, "description": "Request body for creating a BB Sheets spreadsheet. `org_id` is always pinned from the session. Unknown keys are rejected (strict schema).", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Spreadsheet display name (trimmed, 1–500 chars)." }, "fromTemplateId": { "type": "string", "format": "uuid", "description": "Optional template spreadsheet id to copy the initial grid state from." } } }, "SheetsSlidesCollaboration_CreateSlidesRequest": { "type": "object", "additionalProperties": false, "description": "Request body for creating a BB Slides deck. `org_id` is always pinned from the session. Unknown keys are rejected (strict schema).", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Deck display name (trimmed, 1–500 chars)." }, "fromTemplateId": { "type": "string", "format": "uuid", "description": "Optional template deck id to copy the initial content from." } } }, "SheetsSlidesCollaboration_SheetComment": { "type": "object", "description": "A cell comment thread on a BB Sheets spreadsheet.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Comment identifier." }, "document_id": { "type": "string", "format": "uuid", "description": "Parent spreadsheet identifier." }, "anchor_from": { "type": "integer", "minimum": 0, "maximum": 2000000000, "description": "Packed integer encoding the top-left corner of the anchored cell rectangle." }, "anchor_to": { "type": "integer", "minimum": 0, "maximum": 2000000000, "description": "Packed integer encoding the bottom-right corner of the anchored cell rectangle." }, "body": { "type": "string", "maxLength": 5000, "description": "Comment body text." }, "author_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Author user identifier." }, "author_name": { "type": [ "string", "null" ], "maxLength": 200, "description": "Author display name." }, "resolved": { "type": "boolean", "description": "Whether the comment thread is resolved." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the thread was resolved." }, "assignee_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Assigned user identifier." }, "assignee_name": { "type": [ "string", "null" ], "description": "Assigned user display name." }, "assignment_done": { "type": [ "boolean", "null" ], "description": "Whether the assignment task is marked done." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last-update timestamp." }, "replies": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Replies attached to this comment thread." } } }, "SheetsSlidesCollaboration_CreateSheetCommentRequest": { "type": "object", "additionalProperties": false, "description": "Request body for creating a cell comment. `org_id` and `author_id` are always pinned from the session. Unknown keys are rejected (strict schema).", "required": [ "anchorFrom", "anchorTo", "body" ], "properties": { "commentId": { "type": "string", "format": "uuid", "description": "Optional client-provided comment id (UUIDv7). Used as the database row id so the client list stays consistent." }, "anchorFrom": { "type": "integer", "minimum": 0, "maximum": 2000000000, "description": "Packed integer for the top-left of the anchored cell rectangle (non-negative, < 2,000,000,000)." }, "anchorTo": { "type": "integer", "minimum": 0, "maximum": 2000000000, "description": "Packed integer for the bottom-right of the anchored cell rectangle (non-negative, < 2,000,000,000)." }, "body": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Comment body text (1–5000 chars)." }, "authorName": { "type": "string", "maxLength": 200, "description": "Optional display name for the author (up to 200 chars)." } } }, "SheetsSlidesCollaboration_CreateCommentReplyRequest": { "type": "object", "additionalProperties": false, "description": "Request body for creating a reply to a cell comment. Unknown keys are rejected (strict schema).", "required": [ "body" ], "properties": { "replyId": { "type": "string", "format": "uuid", "description": "Optional client-provided reply id (UUIDv7). Used as the database row id." }, "body": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Reply body text (1–5000 chars)." }, "authorName": { "type": "string", "maxLength": 200, "description": "Optional display name for the reply author (up to 200 chars)." } } }, "SheetsSlidesCollaboration_ResolveCommentRequest": { "type": "object", "additionalProperties": false, "description": "Request body for resolving or reopening a cell comment. Only `resolved` is accepted (strict schema).", "required": [ "resolved" ], "properties": { "resolved": { "type": "boolean", "description": "`true` to resolve the comment thread; `false` to reopen it." } } }, "SheetsSlidesCollaboration_AssignCommentRequest": { "type": "object", "additionalProperties": false, "description": "Request body for assigning a cell comment to an org member. Unknown keys are rejected (strict schema).", "required": [ "assigneeUserId" ], "properties": { "assigneeUserId": { "type": "string", "format": "uuid", "description": "User id of the assignee (must be an active org member)." }, "assigneeName": { "type": "string", "maxLength": 200, "description": "Optional display name for the assignee (up to 200 chars)." } } }, "SheetsSlidesCollaboration_InternalAuditRequest": { "type": "object", "description": "Body for the signed DO→Worker cell-write audit callback.", "required": [ "op", "_audit" ], "properties": { "op": { "type": "string", "enum": [ "cell_write", "row_insert", "col_insert", "row_delete", "col_delete", "form_submit", "sheet_create", "sheet_rename", "sheet_delete", "sheet_reorder" ], "description": "The type of grid operation that was audited." }, "affected": { "type": "object", "additionalProperties": true, "description": "Optional map of affected cells/ranges and their values." }, "edit_count": { "type": "integer", "minimum": 0, "description": "Optional count of individual cell edits in this audit batch." }, "_audit": { "type": "object", "required": [ "persisted_by_user_id", "persisted_by_org_id" ], "description": "Audit identity captured by the DO from the JWT-validated WebSocket attachment.", "properties": { "persisted_by_user_id": { "type": "string", "format": "uuid", "description": "User who performed the operation." }, "persisted_by_org_id": { "type": "string", "format": "uuid", "description": "Organization of the user." } } } } }, "SheetsSlidesCollaboration_InternalGridOpRequest": { "type": "object", "description": "Body for the signed internal AI/MCP grid-op transport. Forwarded to the BbSheetGridDO verbatim.", "required": [ "op", "params", "_ctx" ], "properties": { "op": { "type": "string", "enum": [ "describe", "list_sheets", "read_range", "write_cells", "apply_style", "formula_get", "find", "export", "sheet_create", "sheet_rename", "sheet_delete", "sheet_reorder", "row_insert", "row_delete", "col_insert", "col_delete", "row_resize", "col_resize" ], "description": "Grid operation to execute." }, "params": { "type": "object", "additionalProperties": true, "description": "Operation-specific parameters. Validated precisely by the DO; kept as a passthrough here to avoid drift." }, "_ctx": { "type": "object", "required": [ "user_id", "org_id" ], "description": "Acting principal context, server-pinned by the tool handler from the verified JWT. Never model input.", "additionalProperties": false, "properties": { "user_id": { "type": "string", "format": "uuid", "description": "Acting user id." }, "org_id": { "type": "string", "format": "uuid", "description": "Acting organization id." }, "env_id": { "type": "string", "format": "uuid", "description": "Optional tenant environment id (W-ENV scoping). Absent falls back to the org's production env." } } } } }, "SheetsSlidesCollaboration_InternalCheckpointRequest": { "type": "object", "description": "Body for the signed DO→Worker CAS checkpoint commit callback.", "required": [ "new_etag", "sqlite_sha256", "_audit" ], "properties": { "prior_etag": { "type": [ "string", "null" ], "description": "The expected current R2 ETag (CAS precondition). `null` on the first checkpoint." }, "new_etag": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The new R2 ETag to set." }, "sqlite_sha256": { "type": "string", "minLength": 1, "maxLength": 128, "description": "SHA-256 hex digest of the SQLite snapshot." }, "schema_version": { "type": "integer", "minimum": 0, "description": "Optional grid schema version." }, "byte_length": { "type": "integer", "minimum": 0, "description": "Optional byte length of the SQLite snapshot." }, "_audit": { "type": "object", "required": [ "persisted_by_user_id", "persisted_by_org_id" ], "description": "Audit identity captured by the DO at WebSocket-upgrade time.", "properties": { "persisted_by_user_id": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "User who triggered the checkpoint (null for orphaned DOs with no active writer)." }, "persisted_by_org_id": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Organization of the persisting user." } } } } }, "SheetsSlidesCollaboration_CollaborationTicketRequest": { "type": "object", "description": "Optional request body for the collaboration ticket exchange. Scope is advisory.", "properties": { "scope": { "type": "string", "description": "Optional advisory scope string stored with the ticket. Not security-enforced; for client routing only.", "minLength": 1 } } }, "SheetsSlidesCollaboration_SyncResourceType": { "type": "string", "description": "An offline sync resource type.", "enum": [ "entities", "relationships", "documents", "tasks", "comments", "specs" ] }, "SheetsSlidesCollaboration_SyncConfig": { "type": "object", "description": "Organization-level offline sync configuration.", "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Organization identifier." }, "allowed_sync_types": { "type": "array", "items": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SyncResourceType" }, "description": "Resource types the organization permits for offline sync." }, "max_offline_size_mb": { "type": "integer", "minimum": 10, "maximum": 10000, "description": "Maximum total offline storage permitted (MB, 10–10000)." }, "sync_interval_seconds": { "type": "integer", "minimum": 30, "maximum": 86400, "description": "Minimum sync interval in seconds (30–86400)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional bounded metadata object." } } }, "SheetsSlidesCollaboration_UpdateSyncConfigRequest": { "type": "object", "description": "Request body for updating the organization offline sync configuration.", "required": [ "allowed_sync_types" ], "properties": { "allowed_sync_types": { "type": "array", "items": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SyncResourceType" }, "minItems": 0, "maxItems": 20, "description": "Resource types to allow for offline sync (0–20 items)." }, "max_offline_size_mb": { "type": "integer", "minimum": 10, "maximum": 10000, "description": "Optional maximum total offline storage (MB, 10–10000)." }, "sync_interval_seconds": { "type": "integer", "minimum": 30, "maximum": 86400, "description": "Optional minimum sync interval (seconds, 30–86400)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional bounded metadata object." } } }, "SheetsSlidesCollaboration_SyncPreferences": { "type": "object", "description": "User-level offline sync preferences.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "User identifier." }, "org_id": { "type": "string", "format": "uuid", "description": "Organization identifier." }, "enabled_sync_types": { "type": "array", "items": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SyncResourceType" }, "description": "Resource types the user has opted into syncing (must be a subset of the org's `allowed_sync_types`)." }, "auto_sync": { "type": "boolean", "description": "Whether automatic background sync is enabled." }, "sync_on_wifi_only": { "type": "boolean", "description": "Whether to sync only on Wi-Fi connections." }, "max_local_size_mb": { "type": "integer", "minimum": 10, "maximum": 5000, "description": "Maximum local storage the user allows for offline data (MB, 10–5000)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional bounded metadata object." } } }, "SheetsSlidesCollaboration_UpdateSyncPreferencesRequest": { "type": "object", "description": "Request body for updating user offline sync preferences.", "required": [ "enabled_sync_types" ], "properties": { "enabled_sync_types": { "type": "array", "items": { "$ref": "#/components/schemas/SheetsSlidesCollaboration_SyncResourceType" }, "minItems": 0, "maxItems": 20, "description": "Resource types to opt into syncing (must be allowed by the org config; 0–20 items)." }, "auto_sync": { "type": "boolean", "description": "Whether to enable automatic background sync." }, "sync_on_wifi_only": { "type": "boolean", "description": "Whether to restrict sync to Wi-Fi connections only." }, "max_local_size_mb": { "type": "integer", "minimum": 10, "maximum": 5000, "description": "Maximum local storage to allow for offline data (MB, 10–5000)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional bounded metadata object." } } }, "SheetsSlidesCollaboration_SyncPullResponse": { "type": "object", "description": "Response from the delta-sync pull endpoint.", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Records in this sync page. May include `_deleted: true` tombstones for deleted records." }, "hasMore": { "type": "boolean", "description": "Whether more records exist beyond this page." }, "nextCursor": { "type": "string", "description": "Keyset cursor for the next page in the format `:`. Absent when `hasMore` is false.", "pattern": "^[0-9]{1,18}:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "watermark": { "description": "Server-side high-water mark for use as `since` on the next incremental pull.", "oneOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] } } }, "SheetsSlidesCollaboration_OfflineSyncPreferencesSummary": { "type": "object", "description": "Simplified offline sync preferences returned by the client shortcut endpoint.", "properties": { "enabled": { "type": "boolean", "description": "Whether offline sync is enabled (`auto_sync`)." }, "max_items": { "type": "integer", "description": "Maximum items to sync (currently always 500)." }, "sync_on_reconnect": { "type": "boolean", "description": "Whether to sync automatically on reconnect (`auto_sync`)." }, "storage_limit_mb": { "type": "integer", "description": "Local storage limit in MB (`max_local_size_mb`, default 50)." } } }, "SheetsSlidesCollaboration_YjsInternalPersistRequest": { "type": "object", "description": "Body for the YjsDocDO persistence callback. Dispatches to entity update or BB Docs document save depending on `docKind`.", "required": [ "_audit" ], "properties": { "docKind": { "type": "string", "enum": [ "entity", "bbprove_document" ], "description": "Document kind. Defaults to `entity` when absent. `bbprove_document` is used for BB Docs and BB Slides." }, "title": { "type": "string", "description": "Entity title (entity kind only)." }, "description": { "type": "string", "description": "Entity description (entity kind only)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Arbitrary CRDT field map produced by the Yjs Y.Map (entity kind only)." }, "latex": { "type": "string", "maxLength": 10000000, "description": "LaTeX / ProseMirror source content (bbprove_document kind only, max 10 MB)." }, "layout_json": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "Optional layout JSON (bbprove_document kind only)." }, "project_id": { "type": "string", "format": "uuid", "description": "Body project id (bbprove_document kind only). **Ignored for routing** — the server re-resolves from the catalog to prevent spoofing (CRIT-PERSIST-002)." }, "path": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Project-relative file path (bbprove_document kind only). **Ignored for routing** — the server re-resolves from the catalog." }, "format": { "type": "string", "enum": [ "pf2", "amsthm" ], "description": "Document format (bbprove_document kind only)." }, "envId": { "type": "string", "format": "uuid", "description": "Optional tenant environment id forwarded by the DO from the writer's verified JWT (W-ENV scoping). Absent falls back to the org's production env." }, "_audit": { "type": "object", "required": [ "persisted_by_user_id", "persisted_by_org_id" ], "description": "Audit identity captured by the DO from the JWT-validated WebSocket attachment.", "properties": { "persisted_by_user_id": { "type": "string", "format": "uuid", "description": "User who triggered the persistence alarm." }, "persisted_by_org_id": { "type": "string", "format": "uuid", "description": "Organization of the persisting user." }, "connected_user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional list of users connected to the DO at the time of persistence." }, "persistence_timestamp": { "type": "string", "description": "Optional ISO 8601 timestamp of when the persistence alarm fired." }, "update_byte_length": { "type": "integer", "minimum": 0, "description": "Optional byte length of the Yjs update applied." } } } } }, "SSOSCIM_TokenExchangeResponse": { "type": "object", "description": "Auth tokens returned by the SSO token-exchange endpoint. Shape matches `POST /v1/auth/login`. `isNewUser` is intentionally omitted to prevent account enumeration.", "required": [ "success", "userId", "email", "orgId", "accessToken", "refreshToken", "expiresIn", "tokenType" ], "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true." }, "userId": { "type": "string", "format": "uuid", "description": "Authenticated user ID." }, "email": { "type": "string", "format": "email", "description": "User email address." }, "displayName": { "type": [ "string", "null" ], "description": "User display name." }, "orgId": { "type": "string", "format": "uuid", "description": "Organization the session is scoped to." }, "accessToken": { "type": "string", "description": "Short-lived JWT access token." }, "refreshToken": { "type": "string", "description": "Long-lived opaque refresh token." }, "expiresIn": { "type": "integer", "description": "Access token TTL in seconds (typically 900)." }, "tokenType": { "type": "string", "enum": [ "Bearer" ], "description": "Token type." } } }, "SSOSCIM_SamlAcsBody": { "type": "object", "description": "SAML ACS request body (application/x-www-form-urlencoded, HTTP-POST binding).", "required": [ "SAMLResponse", "RelayState" ], "properties": { "SAMLResponse": { "type": "string", "description": "Base64-encoded SAML Response XML from the IdP." }, "RelayState": { "type": "string", "description": "Opaque state value originally set by the SP during AuthnRequest (carries the flow state key)." } } }, "SSOSCIM_SamlSloBody": { "type": "object", "description": "SAML SLO request body (application/x-www-form-urlencoded, HTTP-POST binding).", "required": [ "SAMLRequest", "config_id" ], "properties": { "SAMLRequest": { "type": "string", "description": "Base64-encoded SAML LogoutRequest XML (plain or deflate-raw compressed) from the IdP." }, "config_id": { "type": "string", "format": "uuid", "description": "UUID of the SAML SSO configuration (scopes org resolution and signature verification)." } } }, "SSOSCIM_SsoConfig": { "type": "object", "description": "An SSO configuration record. Sensitive provider_config fields (client secrets, SP signing keys) are redacted; presence flags `has_client_secret` and `has_sp_signing_key` indicate whether they exist.", "required": [ "id", "org_id", "auth_method", "is_active", "is_default", "provider_config" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Configuration ID." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "auth_method": { "type": "string", "enum": [ "saml", "oidc" ], "description": "SSO protocol." }, "is_active": { "type": "boolean", "description": "Whether the configuration is enabled for login." }, "is_default": { "type": "boolean", "description": "Whether this is the default SSO config for the org." }, "provider_config": { "$ref": "#/components/schemas/SSOSCIM_ProviderConfigRedacted" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SSOSCIM_ProviderConfigRedacted": { "type": "object", "description": "Provider configuration with secrets redacted. Non-sensitive fields are returned; `has_client_secret` and `has_sp_signing_key` flags indicate secret presence.", "properties": { "issuer": { "type": "string", "description": "OIDC: issuer URL." }, "client_id": { "type": "string", "description": "OIDC: client ID." }, "authorization_endpoint": { "type": "string", "format": "uri" }, "token_endpoint": { "type": "string", "format": "uri" }, "userinfo_endpoint": { "type": "string", "format": "uri" }, "jwks_uri": { "type": "string", "format": "uri" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OIDC: OAuth scopes to request." }, "end_session_endpoint": { "type": "string", "format": "uri" }, "entity_id": { "type": "string", "description": "SAML: IdP entity ID." }, "sso_url": { "type": "string", "format": "uri", "description": "SAML: IdP SSO URL." }, "slo_url": { "type": "string", "format": "uri", "description": "SAML: IdP SLO URL." }, "metadata_url": { "type": "string", "format": "uri", "description": "SAML: IdP metadata URL." }, "sp_entity_id": { "type": "string", "description": "SAML: SP entity ID." }, "sp_acs_url": { "type": "string", "format": "uri", "description": "SAML: SP Assertion Consumer Service URL." }, "name_id_format": { "type": "string", "description": "SAML: NameID format URN." }, "sign_authn_requests": { "type": "boolean", "description": "SAML: whether the SP signs AuthnRequests." }, "sp_signing_cert": { "type": "string", "description": "SAML: SP signing certificate PEM (public cert only, not the key)." }, "require_destination": { "type": "boolean", "description": "SAML: whether strict Destination attribute checking is enabled." }, "display_name": { "type": "string", "description": "Human-readable name for this IdP configuration." }, "has_client_secret": { "type": "boolean", "description": "OIDC: true when an encrypted client secret is stored (the secret itself is never returned)." }, "has_sp_signing_key": { "type": "boolean", "description": "SAML: true when an encrypted SP signing key is stored." } }, "additionalProperties": false }, "SSOSCIM_CreateSsoConfigRequest": { "type": "object", "description": "Create SSO configuration request.", "required": [ "auth_method", "provider_config" ], "additionalProperties": false, "properties": { "auth_method": { "type": "string", "enum": [ "saml", "oidc" ], "description": "SSO protocol." }, "provider_config": { "type": "object", "description": "Protocol-specific configuration object. Only allowlisted keys are accepted (unknown keys cause a 400). Sensitive values (e.g., `client_secret_ref`, `sp_signing_key_ref`) must be pre-encrypted references.", "additionalProperties": true }, "is_active": { "type": "boolean", "description": "Whether to enable the config immediately (default true)." }, "is_default": { "type": "boolean", "description": "Whether to set this as the org default (default false)." } } }, "SSOSCIM_UpdateSsoConfigRequest": { "type": "object", "description": "Update SSO configuration request. All fields are optional.", "additionalProperties": false, "properties": { "auth_method": { "type": "string", "enum": [ "saml", "oidc" ], "description": "New SSO protocol." }, "provider_config": { "type": "object", "description": "Updated provider configuration. Only allowlisted keys are accepted.", "additionalProperties": true }, "is_active": { "type": "boolean", "description": "Enable or disable this config. Setting false force-revokes all active sessions." }, "is_default": { "type": "boolean", "description": "Set as org default." } } }, "SSOSCIM_ImportOidcRequest": { "type": "object", "description": "Import OIDC configuration from a discovery URL.", "required": [ "discovery_url", "client_id", "client_secret" ], "additionalProperties": false, "properties": { "discovery_url": { "type": "string", "format": "uri", "description": "OIDC issuer base URL. The endpoint `/.well-known/openid-configuration` is fetched. Must be a public HTTPS URL (SSRF blocklist enforced)." }, "client_id": { "type": "string", "minLength": 1, "maxLength": 500, "description": "OAuth 2.0 client ID registered with the IdP." }, "client_secret": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "OAuth 2.0 client secret. Encrypted at rest before storage; never returned in API responses." } } }, "SSOSCIM_ImportSamlRequest": { "type": "object", "description": "Import SAML configuration from an IdP metadata URL.", "required": [ "metadata_url" ], "additionalProperties": false, "properties": { "metadata_url": { "type": "string", "format": "uri", "description": "URL of the IdP SAML metadata XML document. Must be a public HTTPS URL (SSRF blocklist enforced)." } } }, "SSOSCIM_SsoTestResult": { "type": "object", "description": "SSO connectivity test result.", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok", "error" ], "description": "ok when all checks passed; error when any check failed." }, "message": { "type": "string", "description": "Human-readable status message (present on error)." }, "details": { "type": "object", "description": "Per-check detail map. For OIDC: `discovery_reachable`, `issuer`, `jwks_reachable`, `jwks_status`. For SAML: `metadata_reachable`, `metadata_valid`, `idp_entity_id`, `certificate_present`, `certificate_length`.", "additionalProperties": true } } }, "SSOSCIM_SsoIdentity": { "type": "object", "description": "A linked SSO identity record (IdP subject binding for a user).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identity record ID." }, "user_id": { "type": "string", "format": "uuid", "description": "Linked user ID." }, "org_id": { "type": "string", "format": "uuid", "description": "Owning organization." }, "provider": { "type": "string", "description": "Provider identifier (e.g., OIDC issuer URL or SAML entity ID)." }, "subject": { "type": "string", "description": "IdP subject identifier (sub claim or NameID). Stored as a hash for privacy." }, "config_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Associated SSO config ID." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SSOSCIM_CreateDomainRequest": { "type": "object", "description": "Create email domain mapping request.", "required": [ "domain", "auth_method" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Email domain to map (e.g., example.com). Normalized to Punycode. Public consumer domains (gmail.com, etc.) are rejected." }, "auth_method": { "type": "string", "enum": [ "saml", "oidc", "password", "google_sso", "magic_link" ], "description": "Authentication method to enforce for users with this email domain." }, "config_id": { "type": "string", "format": "uuid", "description": "Optional UUID of the associated SAML/OIDC SSO configuration." }, "auto_provision": { "type": "boolean", "description": "Whether to automatically provision new users during SSO login (default false)." } } }, "SSOSCIM_DomainMapping": { "type": "object", "description": "An email domain mapping record.", "properties": { "domain": { "type": "string", "description": "Normalized domain name (Punycode)." }, "org_id": { "type": "string", "format": "uuid" }, "auth_method": { "type": "string", "enum": [ "saml", "oidc", "password", "google_sso", "magic_link" ] }, "config_id": { "type": [ "string", "null" ], "format": "uuid" }, "auto_provision": { "type": "boolean" }, "is_verified": { "type": "boolean", "description": "Whether the domain has been verified via DNS TXT record." }, "verification_token": { "type": [ "string", "null" ], "description": "Token to publish as `_backbuild-verify.` TXT record value (present on create response)." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "SSOSCIM_DomainListPage": { "type": "object", "description": "Paginated list of domain mappings.", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/SSOSCIM_DomainMapping" } }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "SSOSCIM_DomainVerifyResult": { "type": "object", "description": "Domain verification result.", "required": [ "domain", "is_verified" ], "properties": { "domain": { "type": "string" }, "is_verified": { "type": "boolean" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "message": { "type": "string" } } }, "SSOSCIM_DomainTokenRotateResult": { "type": "object", "description": "Domain verification token rotation result.", "required": [ "domain", "verification_token", "is_verified" ], "properties": { "domain": { "type": "string" }, "verification_token": { "type": "string", "description": "New verification token. Publish as `_backbuild-verify.` TXT record value." }, "verification_started_at": { "type": "string", "format": "date-time" }, "is_verified": { "type": "boolean", "enum": [ false ], "description": "Always false after rotation — must re-verify." } } }, "SSOSCIM_ScimUserCreateRequest": { "type": "object", "description": "SCIM User create request body (RFC 7643 subset).", "required": [ "userName" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "description": "SCIM schema URNs (e.g., [\"urn:ietf:params:scim:schemas:core:2.0:User\"])." }, "userName": { "type": "string", "description": "User email address. Lowercased and trimmed before storage. Immutable after creation." }, "externalId": { "type": "string", "description": "IdP-assigned external identifier." }, "displayName": { "type": "string", "description": "User display name." }, "active": { "type": "boolean", "description": "Whether the user is active (default true)." }, "name": { "type": "object", "properties": { "givenName": { "type": "string" }, "familyName": { "type": "string" }, "formatted": { "type": "string" } } }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "format": "email" }, "primary": { "type": "boolean" }, "type": { "type": "string" } } }, "description": "Email addresses. The primary=true entry is used as the primary_email; falls back to userName. Must pass RFC 5321 validation." } } }, "SSOSCIM_ScimUserPutRequest": { "type": "object", "description": "SCIM User full-replace request body. `userName` is immutable and cannot be changed via PUT.", "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "displayName": { "type": "string" }, "active": { "type": "boolean", "description": "Setting false triggers session revocation." }, "name": { "type": "object", "properties": { "givenName": { "type": "string" }, "familyName": { "type": "string" }, "formatted": { "type": "string" } } }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "primary": { "type": "boolean" }, "type": { "type": "string" } } } } } }, "SSOSCIM_ScimPatchRequest": { "type": "object", "description": "SCIM PATCH request body (RFC 7644). Only op: replace is supported. Maximum 100 operations.", "required": [ "Operations" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "Operations": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Array of PATCH operations. Only op: replace is supported. Supported paths: active, displayName, name.givenName, name.familyName, emails[primary eq true].value (no-op).", "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string", "enum": [ "replace" ], "description": "Operation type (only replace is supported)." }, "path": { "type": "string", "description": "Attribute path (e.g., active, displayName, name.givenName)." }, "value": { "description": "New value for the attribute." } } } } } }, "SSOSCIM_ScimUser": { "type": "object", "description": "SCIM User resource (RFC 7643 subset as implemented by Backbuild).", "required": [ "schemas", "id", "userName" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "format": "uuid", "description": "Platform-assigned user UUID." }, "externalId": { "type": [ "string", "null" ], "description": "IdP-assigned external ID." }, "userName": { "type": "string", "description": "User email (lowercased). Immutable." }, "displayName": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "name": { "type": "object", "properties": { "givenName": { "type": [ "string", "null" ] }, "familyName": { "type": [ "string", "null" ] }, "formatted": { "type": [ "string", "null" ] } } }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "primary": { "type": "boolean" }, "type": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "resourceType": { "type": "string", "enum": [ "User" ] }, "created": { "type": "string", "format": "date-time" }, "lastModified": { "type": "string", "format": "date-time" }, "location": { "type": "string", "format": "uri" }, "version": { "type": "string" } } } } }, "SSOSCIM_ScimListResponse": { "type": "object", "description": "SCIM ListResponse envelope (RFC 7644).", "required": [ "schemas", "totalResults", "Resources" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "totalResults": { "type": "integer", "description": "Total records matching the query." }, "startIndex": { "type": "integer", "description": "1-based start index of this page." }, "itemsPerPage": { "type": "integer", "description": "Number of records in this response." }, "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/SSOSCIM_ScimUser" } } } }, "SSOSCIM_ScimError": { "type": "object", "description": "SCIM error envelope (RFC 7644). Response Content-Type is application/scim+json.", "required": [ "schemas", "status" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "scimType": { "type": "string", "enum": [ "invalidFilter", "tooMany", "uniqueness", "mutability", "invalidSyntax", "invalidPath", "noTarget", "invalidValue", "invalidVers", "sensitive" ], "description": "SCIM detail error type from RFC 7644." }, "detail": { "type": "string", "description": "Human-readable error description." }, "status": { "type": "string", "description": "HTTP status code as a string." } } }, "SSOSCIM_CreateScimTokenRequest": { "type": "object", "description": "Create SCIM token request.", "required": [ "display_name" ], "additionalProperties": false, "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Human-readable name for this token (e.g., Okta Provisioning Token)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional expiry timestamp (ISO-8601 with UTC offset). Must be in the future. Null for no expiry." } } }, "SSOSCIM_ScimTokenCreated": { "type": "object", "description": "SCIM token creation response. The `token` field contains the plaintext and is shown EXACTLY ONCE.", "required": [ "id", "token", "prefix", "display_name", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Token record UUID (used for revocation)." }, "token": { "type": "string", "description": "Plaintext SCIM bearer token (bbscim_<48 hex>). Shown once; not stored in plaintext." }, "prefix": { "type": "string", "description": "First 8 characters of the token for UI identification." }, "display_name": { "type": "string", "description": "Human-readable token name." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "SSOSCIM_ScimTokenRecord": { "type": "object", "description": "SCIM token record (no plaintext).", "required": [ "id", "prefix", "display_name", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "prefix": { "type": "string", "description": "First 8 characters of the token for identification." }, "display_name": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" } } } }, "responses": { "ValidationError": { "description": "400 Bad Request — a request parameter, body field, or the JSON body itself failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "One or more request parameters failed validation." } } } } }, "Unauthorized": { "description": "401 Unauthorized — missing, expired, malformed, or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "AUTH_REQUIRED", "message": "Authentication is required to access this resource." } } } } }, "Forbidden": { "description": "403 Forbidden — authenticated but lacking the required membership, role, permission, MFA step-up, or feature entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "PERMISSION_DENIED", "message": "You do not have permission to perform this action." } } } } }, "NotFound": { "description": "404 Not Found — the requested resource does not exist or is not visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "The requested resource was not found." } } } } }, "Conflict": { "description": "409 Conflict — the request conflicts with an existing resource or current state (unique constraint, optimistic-lock, duplicate).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "CONFLICT", "message": "A resource with the same unique constraint already exists." } } } } }, "RateLimited": { "description": "429 Too Many Requests — a rate limit or usage quota was exceeded. Retry after the indicated window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests. Please retry later." } } } } }, "ServerError": { "description": "500 Internal Server Error — an unexpected server-side error. The message is sanitized; the correlation id is logged server-side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred." } } } } } } } }