{ "openapi": "3.0.0", "info": { "title": "Isodora Public API", "version": "1.0.0", "description": "Unauthenticated public slice of the Isodora OpenAPI document — /api/v1 and /api/mcp only. Full internal catalog remains session-gated at /api/api-docs. Auth: Bearer personal API key (isk_u_*)." }, "servers": [ { "url": "https://app.isodora.se", "description": "EU production" }, { "url": "https://app.isodora.app", "description": "US production" } ], "tags": [ { "name": "Agents", "description": "LangGraph multi-agent system endpoints for intelligent compliance analysis and QMS management" }, { "name": "Platform", "description": "External automation API for platform operators. Authenticated with platform API keys. Used by AI agents (OpenClaw, Paperclip, n8n) to drive cross-org operations such as customer onboarding. Tools are also exposed as a remote MCP server at /api/mcp for agentic clients (Claude Desktop, Cursor, OpenClaw, Cline, n8n)." }, { "name": "Public API", "description": "Versioned public REST API (/api/v1). Stable contract for personal API keys (isk_u_*), platform keys, and Supabase JWTs. See PRD-047 and docs/api/public-api-v1.md." } ], "paths": { "/api/mcp": { "get": { "tags": [ "Agents" ], "summary": "Isodora Platform MCP server (Streamable HTTP transport)", "description": "Model Context Protocol endpoint for agentic clients (Claude Desktop, Cursor,\nOpenClaw, Cline, n8n). Implements the Streamable HTTP transport: tools and\nresponses are discovered/invoked over MCP, not described in this OpenAPI\ndocument. See the MCP discovery channel for the full tool catalog. Accepts\na personal API key (`isk_u_*`, PRD-047) or a platform API key (`isk_p_*`)\nas a Bearer token; scoped per-tool inside the handler.\n", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] } ], "responses": { "200": { "description": "MCP transport response (Server-Sent Events or JSON, per the MCP protocol).", "content": { "text/event-stream": {}, "application/json": {} } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "Agents" ], "summary": "Isodora Platform MCP server (Streamable HTTP transport)", "description": "MCP request/response channel. See the MCP discovery channel for the full tool catalog.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] } ], "responses": { "200": { "description": "MCP response payload (per the MCP protocol).", "content": { "application/json": {}, "text/event-stream": {} } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "delete": { "tags": [ "Agents" ], "summary": "Close an MCP session", "description": "Terminate the Streamable HTTP MCP session.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] } ], "responses": { "200": { "description": "Session closed" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/me": { "get": { "tags": [ "Public API" ], "summary": "Who am I", "description": "Returns the user the credential acts as, the organizations it can currently access, and — for personal keys — the key's name, scope, and expiry. Call this first to verify a key and discover organization ids.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Actor identity and effective organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/compliance/overview": { "get": { "tags": [ "Public API" ], "summary": "Compliance overview", "description": "Compliance percentage, assessment breakdown, gap and task counts for the organization or one project. Same numbers as the in-app dashboard.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "project_id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Overview metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/documents/search": { "get": { "tags": [ "Public API" ], "summary": "Semantic document search", "description": "Semantic (RAG) search across the organization's compliance documents. Returns matching text chunks with file names and relevance. Costs AI credits per call and is limited to 20 calls/min per key.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "q", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "project_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "number", "maximum": 20 } }, { "in": "query", "name": "document_type", "schema": { "type": "string" }, "description": "File-extension filter, e.g. \"pdf\"." } ], "responses": { "200": { "description": "Matching chunks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "429": { "description": "Rate limited (20/min per key for this endpoint)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/gaps/{gapId}": { "get": { "tags": [ "Public API" ], "summary": "Get a gap finding", "description": "One gap finding with severity, status, and linked requirement.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "gapId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The gap finding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } }, "patch": { "tags": [ "Public API" ], "summary": "Update a gap finding's status", "description": "Sets the status (and optional closure reason). Requires a read & write credential owned by a role that may write — auditor keys get forbidden_role. Audited with the key id.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "gapId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "in_progress", "resolved", "closed" ] }, "closure_reason": { "type": "string" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Updated gap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden (forbidden_role / forbidden_scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/gaps": { "get": { "tags": [ "Public API" ], "summary": "List gap findings", "description": "Compliance gap findings with severity, status, and linked requirement. Defaults to actionable gaps (open + in_progress) unless status or include_all is given. Cursor-paginated.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "project_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "open", "in_progress", "resolved", "closed" ] } }, { "in": "query", "name": "severity", "schema": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "number", "maximum": 200 } } ], "responses": { "200": { "description": "Gap findings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/projects/{projectId}/documents": { "get": { "tags": [ "Public API" ], "summary": "List project documents", "description": "The project's document library — uploaded files and Isodora-generated documents, newest first. Cursor-paginated.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "number", "maximum": 200 } } ], "responses": { "200": { "description": "Documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/projects": { "get": { "tags": [ "Public API" ], "summary": "List compliance projects", "description": "Lists projects in the organization the actor can access. Restricted projects are excluded unless the actor is an admin, assigned consultant, or explicit member.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "archived", "all" ] } }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Case-insensitive substring filter on project name." }, { "in": "query", "name": "limit", "schema": { "type": "number", "maximum": 100 } } ], "responses": { "200": { "description": "Projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden (forbidden_org / forbidden_role)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/requirements/{requirementId}/evidence": { "get": { "tags": [ "Public API" ], "summary": "List evidence for a requirement", "description": "Evidence items linked to one requirement in a project (titles, types, confidence). Useful for audit workpapers.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "requirementId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "project_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Evidence items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/requirements/search": { "get": { "tags": [ "Public API" ], "summary": "Search framework requirements", "description": "Search a project's framework requirements by ref code (e.g. \"A.5.1\") or text, with each requirement's assessment status in that project.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "q", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "project_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "number", "maximum": 50 } } ], "responses": { "200": { "description": "Matching requirements with assessment status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/risks": { "get": { "tags": [ "Public API" ], "summary": "List risks", "description": "The organization's risk register (inherent/residual scores, status, owner). Requires the QMS module — 403 forbidden_scope when unlicensed. Cursor-paginated.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "draft", "active", "treating", "accepted", "closed" ] } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "number", "maximum": 200 } } ], "responses": { "200": { "description": "Risks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden (incl. forbidden_scope when the QMS module is not licensed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/suppliers": { "get": { "tags": [ "Public API" ], "summary": "List suppliers", "description": "The organization's supplier register (criticality, data access level, approval status, review dates). Requires the QMS module — 403 forbidden_scope when unlicensed. Cursor-paginated.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pending", "active", "suspended", "terminated" ] } }, { "in": "query", "name": "criticality", "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "number", "maximum": 200 } } ], "responses": { "200": { "description": "Suppliers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden (incl. forbidden_scope when the QMS module is not licensed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/tasks/{taskId}": { "patch": { "tags": [ "Public API" ], "summary": "Update a remediation task's status", "description": "Sets a task's status. Requires a read & write credential owned by a role that may write — auditor keys get forbidden_role. Audited with the key id.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "in_progress", "resolved", "closed" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Updated task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden (forbidden_role / forbidden_scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations/{orgId}/tasks": { "get": { "tags": [ "Public API" ], "summary": "List remediation tasks", "description": "Remediation tasks with severity, status, due date, linked gap/requirement, and verification progress. Cursor-paginated.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "project_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "open", "in_progress", "resolved", "closed" ] } }, { "in": "query", "name": "severity", "schema": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] } }, { "in": "query", "name": "assignee", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by assigned user_profile id." }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "number", "maximum": 200 } } ], "responses": { "200": { "description": "Tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/organizations": { "get": { "tags": [ "Public API" ], "summary": "List accessible organizations", "description": "Lists the organizations the credential can currently act on. For personal keys this is the owner's live memberships/assignments intersected with the key's org allow-list.", "security": [ { "PersonalApiKey": [] }, { "PlatformApiKey": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Envelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } } } } }, "/api/v1/platform/organizations/provision": { "post": { "tags": [ "Platform" ], "summary": "Provision a new customer organization with a 7-day invitation link", "description": "Atomically creates a customer organization, sets up the onboarding journey, optionally pre-fills the simple-mode interview using AI-drafted answers from the supplied website, and creates a `customer_admin` invitation valid for 7 days. Returns the invitation URL ready to be sent in personalized outreach. Requires the `organizations:provision` scope.", "security": [ { "PlatformApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "primary_contact" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Acme AB" }, "org_number": { "type": "string", "maxLength": 50, "nullable": true, "example": "556677-1234" }, "website": { "type": "string", "format": "uri", "maxLength": 500, "nullable": true, "example": "https://acme.se" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "ui_mode": { "type": "string", "enum": [ "simple", "advanced" ], "default": "simple" }, "auto_draft_answers": { "type": "boolean", "default": true, "description": "When true and ui_mode is simple, the server analyzes the website and pre-fills the 10 simple-mode interview answers. Set false to skip AI work." }, "simple_mode_answers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional explicit answers keyed q1..q10. If provided, takes precedence over auto_draft_answers.", "example": { "q1": "We sell SaaS to enterprise clients", "q2": "50 employees in Stockholm" } }, "company_summary": { "type": "string", "maxLength": 5000, "nullable": true, "description": "Optional override for the AI-drafted company summary." }, "primary_contact": { "type": "object", "required": [ "email", "full_name" ], "properties": { "email": { "type": "string", "format": "email", "example": "ceo@acme.se" }, "full_name": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Anna Andersson" }, "title": { "type": "string", "maxLength": 200, "example": "CEO" }, "locale": { "type": "string", "enum": [ "en-US", "sv-SE", "de-DE", "pl-PL", "it-IT" ], "default": "en-US" } } } } }, "examples": { "AI-drafted (recommended for agent use)": { "value": { "name": "Acme AB", "website": "https://acme.se", "ui_mode": "simple", "auto_draft_answers": true, "primary_contact": { "email": "ceo@acme.se", "full_name": "Anna Andersson", "title": "CEO", "locale": "sv-SE" } } }, "Manual answers (no AI)": { "value": { "name": "Acme AB", "ui_mode": "simple", "auto_draft_answers": false, "simple_mode_answers": { "q1": "B2B SaaS", "q2": "50 employees" }, "primary_contact": { "email": "ceo@acme.se", "full_name": "Anna Andersson", "locale": "en-US" } } } } } } }, "responses": { "201": { "description": "Organization created. Invitation URL valid for 7 days.", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_via": { "type": "string", "enum": [ "admin_provisioned" ] } } }, "invitation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "description": "Personalized invitation URL. Valid for 7 days.", "example": "https://app.isodora.se/sv-SE/accept-invitation?token=8e1f9b1a-..." }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Validation error in request body." }, "401": { "description": "Missing, invalid, expired, or revoked API key." }, "403": { "description": "API key lacks the `organizations:provision` scope." }, "409": { "description": "A pending invitation already exists for this email." }, "429": { "description": "Rate limit exceeded for this API key. Retry-After header indicates seconds." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Supabase JWT token from authentication" }, "CookieAuth": { "type": "apiKey", "in": "cookie", "name": "sb-access-token", "description": "Session cookie authentication (used by web app)" }, "PlatformApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "isk_p_*", "description": "Platform API key for super-admin / platform-operator automation (e.g. AI agents onboarding new customer organizations). Mint via the platform-api-keys CLI (`pnpm tsx scripts/platform-api-keys.ts create ...`). Pass as `Authorization: Bearer isk_p_...`. Distinct from the supplier API key system (`x-api-key`)." }, "PersonalApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "isk_u_*", "description": "Personal API key (PRD-047). Created by any licensed-seat user under Profile → API keys in the customer portal. The key acts as its owner: every call is authorized against the owner's live role, org memberships, module licenses, and subscription. Pass as `Authorization: Bearer isk_u_...`. Accepted by `/api/v1/**` and `/api/mcp` only." } }, "schemas": { "UserApiKeyMetadata": { "type": "object", "description": "Personal API key metadata. The plaintext key is returned exactly once at creation and never stored.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 80 }, "key_prefix": { "type": "string", "description": "Display prefix, e.g. \"isk_u_ab12cd\"" }, "scope": { "type": "string", "enum": [ "read", "read_write" ] }, "allowed_org_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true, "description": "null = all organizations the owner belongs to at call time" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } } }, "V1Envelope": { "type": "object", "description": "Standard success envelope for /api/v1 responses.", "properties": { "data": { "description": "Endpoint-specific payload" }, "meta": { "type": "object", "properties": { "next_cursor": { "type": "string", "nullable": true }, "total": { "type": "number", "nullable": true } } }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "V1Error": { "type": "object", "description": "Standard error envelope for /api/v1 responses.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden_org", "forbidden_role", "forbidden_project", "forbidden_scope", "not_found", "validation", "rate_limited", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "nullable": true } }, "required": [ "code", "message" ] }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "string", "description": "Additional error details" }, "code": { "type": "string", "description": "Error code" } } }, "UserProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "auth_user_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "full_name": { "type": "string" }, "avatar_url": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "super_admin", "consultant", "auditor", "customer_admin", "customer_user" ] }, "preferences": { "type": "object" }, "preferred_language": { "type": "string", "enum": [ "en", "sv" ] }, "consultant_org_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "User": { "type": "object", "description": "Alias for UserProfile", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "full_name": { "type": "string" }, "role": { "type": "string", "enum": [ "super_admin", "consultant", "auditor", "customer_admin", "customer_user" ] }, "organization_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "org_number": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "subscription_status": { "type": "string", "enum": [ "trial", "active", "past_due", "canceled", "incomplete", "expired" ] }, "trial_ends_at": { "type": "string", "format": "date-time", "nullable": true }, "total_ai_cost_usd": { "type": "number" }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrgMember": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "org_role": { "type": "string", "enum": [ "customer_admin", "customer_user" ] }, "status": { "type": "string", "enum": [ "active", "pending", "suspended" ] }, "joined_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "stripe_customer_id": { "type": "string" }, "stripe_subscription_id": { "type": "string", "nullable": true }, "stripe_price_id": { "type": "string", "nullable": true }, "plan_type": { "type": "string", "enum": [ "one_time", "recurring" ] }, "status": { "type": "string", "enum": [ "incomplete", "incomplete_expired", "trialing", "active", "past_due", "canceled", "unpaid", "expired" ] }, "current_period_start": { "type": "string", "format": "date-time", "nullable": true }, "current_period_end": { "type": "string", "format": "date-time", "nullable": true }, "cancel_at_period_end": { "type": "boolean" }, "consultant_hours_remaining": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationCredits": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "credits_total": { "type": "integer" }, "credits_used": { "type": "integer" }, "credits_remaining": { "type": "integer", "description": "Computed: credits_total - credits_used" }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "standard_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "active", "on_hold", "completed", "archived" ] }, "target_completion_date": { "type": "string", "format": "date", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "IsoStandard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "description": "e.g., ISO 27001" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true }, "language_code": { "type": "string", "default": "sv-SE" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "IsoRequirement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "standard_id": { "type": "string", "format": "uuid" }, "ref_code": { "type": "string", "description": "e.g., A.5.1" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "level": { "type": "integer" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "RequirementAssessment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "requirement_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "not_assessed", "in_progress", "compliant", "non_compliant", "partially_compliant", "gap" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true }, "assessment_type": { "type": "string", "enum": [ "ai", "manual", "ai_analysis", "manual_override" ] }, "rationale": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "citations": { "type": "array", "items": { "type": "object" } }, "metadata": { "type": "object" }, "assessor_id": { "type": "string", "format": "uuid", "nullable": true }, "assessed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "GapFinding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "requirement_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "resolved", "closed" ] }, "citations": { "type": "array", "items": { "type": "object" } }, "metadata": { "type": "object" }, "ai_generated_document_id": { "type": "string", "format": "uuid", "nullable": true }, "closed_by": { "type": "string", "format": "uuid", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "closure_reason": { "type": "string", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RemediationTask": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "gap_id": { "type": "string", "format": "uuid", "nullable": true }, "requirement_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "resolved", "closed" ] }, "assigned_to": { "type": "string", "format": "uuid", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "completion_notes": { "type": "string", "nullable": true }, "ai_generated_document_id": { "type": "string", "format": "uuid", "nullable": true }, "metadata": { "type": "object" }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ComplianceAssessment": { "type": "object", "description": "Alias for RequirementAssessment", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "standard": { "type": "string" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "failed" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "findings": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" } } }, "EvidenceItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "evidence_type": { "type": "string", "enum": [ "document", "interview", "observation", "test", "certificate", "policy", "procedure" ] }, "source_uri": { "type": "string", "nullable": true }, "file_path": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "staleness_threshold_days": { "type": "integer", "default": 180 }, "last_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "verified_by": { "type": "string", "format": "uuid", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiAnalysisRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "standard_id": { "type": "string", "format": "uuid", "nullable": true }, "filespace_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "pending_review", "approved", "rejected" ] }, "review_status": { "type": "string", "enum": [ "pending", "approved", "rejected", "needs_revision" ] }, "reviewed_by": { "type": "string", "format": "uuid", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "review_notes": { "type": "string", "nullable": true }, "parameters": { "type": "object" }, "statistics": { "type": "object" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "AiAnalysisJob": { "type": "object", "properties": { "id": { "type": "string" }, "run_id": { "type": "string", "format": "uuid" }, "requirement_id": { "type": "string", "format": "uuid", "nullable": true }, "requirement_ref": { "type": "string" }, "requirement_title": { "type": "string" }, "job_type": { "type": "string", "enum": [ "requirement_analysis", "gap_reanalysis" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "priority": { "type": "integer" }, "retry_count": { "type": "integer" }, "max_retries": { "type": "integer" }, "error_message": { "type": "string", "nullable": true }, "result": { "type": "object", "nullable": true }, "parameters": { "type": "object" }, "logs": { "type": "array", "items": { "type": "object" } }, "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 } } }, "AiDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "storage_path": { "type": "string" }, "content": { "type": "string", "nullable": true, "description": "Lexical JSON state" }, "markdown_content": { "type": "string", "nullable": true }, "openai_file_id": { "type": "string", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiFile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "filespace_id": { "type": "string", "format": "uuid" }, "provider_file_id": { "type": "string" }, "file_name": { "type": "string" }, "mime_type": { "type": "string", "nullable": true }, "file_size_bytes": { "type": "integer", "nullable": true }, "provider_status": { "type": "string", "nullable": true }, "evidence_id": { "type": "string", "format": "uuid", "nullable": true }, "storage_path": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiFilespace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "provider_space_id": { "type": "string" }, "status": { "type": "string", "enum": [ "creating", "active", "deleting", "deleted" ] }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AiCostLog": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "run_id": { "type": "string", "format": "uuid", "nullable": true }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "component": { "type": "string", "enum": [ "file_search", "gpt4o", "gpt-4o", "gpt-4-turbo", "embeddings", "storage", "chat", "analysis", "other" ] }, "operation_type": { "type": "string", "nullable": true }, "model_name": { "type": "string", "nullable": true }, "unit": { "type": "string", "enum": [ "tokens", "requests", "files", "bytes" ] }, "quantity": { "type": "number" }, "unit_cost_usd": { "type": "number" }, "total_cost_usd": { "type": "number" }, "prompt_tokens": { "type": "integer", "nullable": true }, "completion_tokens": { "type": "integer", "nullable": true }, "total_tokens": { "type": "integer", "nullable": true }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } }, "ChatSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid", "nullable": true }, "user_id": { "type": "string", "format": "uuid", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string", "nullable": true }, "session_type": { "type": "string", "enum": [ "general", "onboarding", "compliance", "interview", "project" ] }, "status": { "type": "string", "enum": [ "active", "completed", "archived" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ChatMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string" }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } }, "InterviewSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "invited_email": { "type": "string", "nullable": true }, "participant_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled" ] }, "channel": { "type": "string", "enum": [ "web_chat", "bankid_chat", "email", "phone" ] }, "feature": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "InterviewQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "standard_id": { "type": "string", "format": "uuid", "nullable": true }, "requirement_id": { "type": "string", "format": "uuid", "nullable": true }, "text": { "type": "string" }, "question_type": { "type": "string", "enum": [ "text", "multiple_choice", "rating", "file_upload" ] }, "options": { "type": "object", "nullable": true }, "response_schema": { "type": "object", "nullable": true }, "language": { "type": "string", "enum": [ "sv", "en" ] }, "feature": { "type": "string" }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Invitation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "invited_role": { "type": "string", "enum": [ "consultant", "auditor", "customer_admin", "customer_user" ] }, "org_id": { "type": "string", "format": "uuid", "nullable": true }, "invited_by": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "invited", "accepted", "revoked", "expired" ] }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "AuditLog": { "type": "object", "properties": { "id": { "type": "integer" }, "actor_id": { "type": "string", "format": "uuid", "nullable": true }, "action": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string", "nullable": true }, "org_id": { "type": "string", "format": "uuid", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "ip_address": { "type": "string", "nullable": true }, "user_agent": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Risk": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "risk_domain": { "type": "string", "enum": [ "business", "quality", "environment", "work_environment", "information_security", "cybersecurity", "dora_operational", "ai_governance" ] }, "likelihood": { "type": "integer", "minimum": 1, "maximum": 5 }, "impact": { "type": "integer", "minimum": 1, "maximum": 5 }, "inherent_score": { "type": "integer", "description": "Computed: likelihood * impact" }, "residual_likelihood": { "type": "integer", "nullable": true }, "residual_impact": { "type": "integer", "nullable": true }, "residual_score": { "type": "integer", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "acceptance_status": { "type": "string", "enum": [ "not_accepted", "accepted", "conditionally_accepted" ] }, "acceptance_decision_date": { "type": "string", "format": "date", "nullable": true }, "acceptance_rationale": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "active", "treating", "accepted", "closed" ] }, "next_review_date": { "type": "string", "format": "date", "nullable": true }, "review_frequency_days": { "type": "integer", "default": 90 }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_by": { "type": "string", "format": "uuid", "nullable": true } } }, "RiskTreatment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "risk_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "treatment_type": { "type": "string", "enum": [ "mitigate", "transfer", "avoid", "accept" ] }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "completion_notes": { "type": "string", "nullable": true }, "task_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "case_type": { "type": "string", "enum": [ "deviation", "security_incident", "operational_incident", "ai_deviation", "improvement" ] }, "case_domain": { "type": "string", "enum": [ "quality", "environment", "security", "it", "process", "dora", "ai" ] }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "affected_area": { "type": "string", "nullable": true }, "detected_date": { "type": "string", "format": "date" }, "reported_date": { "type": "string", "format": "date" }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "open", "in_progress", "awaiting_verification", "closed", "cancelled" ] }, "rca_method": { "type": "string", "nullable": true }, "rca_conclusions": { "type": "string", "nullable": true }, "verification_required": { "type": "boolean" }, "verification_notes": { "type": "string", "nullable": true }, "verified_by": { "type": "string", "format": "uuid", "nullable": true }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_by": { "type": "string", "format": "uuid", "nullable": true } } }, "CaseAction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "action_type": { "type": "string", "enum": [ "corrective", "preventive", "containment" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "completion_notes": { "type": "string", "nullable": true }, "task_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Kpi": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "unit": { "type": "string", "nullable": true }, "target_value": { "type": "number", "nullable": true }, "target_direction": { "type": "string", "enum": [ "higher_is_better", "lower_is_better", "target_range" ] }, "target_min": { "type": "number", "nullable": true }, "target_max": { "type": "number", "nullable": true }, "measurement_frequency": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "annual", "custom" ] }, "next_measurement_due": { "type": "string", "format": "date", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "current_status": { "type": "string", "enum": [ "on_track", "at_risk", "off_track", "unknown" ] }, "is_active": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "KpiMeasurement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kpi_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "measured_value": { "type": "number" }, "measurement_date": { "type": "string", "format": "date" }, "notes": { "type": "string", "nullable": true }, "evidence_id": { "type": "string", "format": "uuid", "nullable": true }, "recorded_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "InternalAudit": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "program_id": { "type": "string", "format": "uuid", "nullable": true }, "org_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "audit_type": { "type": "string", "enum": [ "internal", "external", "surveillance" ] }, "planned_start_date": { "type": "string", "format": "date", "nullable": true }, "planned_end_date": { "type": "string", "format": "date", "nullable": true }, "actual_start_date": { "type": "string", "format": "date", "nullable": true }, "actual_end_date": { "type": "string", "format": "date", "nullable": true }, "lead_auditor_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "cancelled" ] }, "audit_summary": { "type": "string", "nullable": true }, "report_file_id": { "type": "string", "format": "uuid", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AuditFinding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "audit_id": { "type": "string", "format": "uuid" }, "checklist_item_id": { "type": "string", "format": "uuid", "nullable": true }, "org_id": { "type": "string", "format": "uuid" }, "finding_type": { "type": "string", "enum": [ "nonconformity", "observation", "opportunity_for_improvement" ] }, "severity": { "type": "string", "enum": [ "minor", "major", "critical" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "case_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "open", "in_progress", "closed" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SupplierEscalationConfig": { "type": "object", "description": "Per-risk-tier escalation configuration for supplier follow-ups (reminders, escalation thresholds, recipients).", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "risk_tier": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "reminder_interval_days": { "type": "integer" }, "max_reminders": { "type": "integer" }, "escalate_after_days": { "type": "integer" }, "escalation_recipients": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true } }, "required": [ "email" ] } }, "auto_create_assessment": { "type": "boolean" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Supplier": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "service_provided": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "criticality": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "data_access_level": { "type": "string", "enum": [ "none", "limited", "full", "sensitive" ] }, "status": { "type": "string", "enum": [ "pending", "active", "suspended", "terminated" ] }, "approval_status": { "type": "string", "enum": [ "pending", "approved", "rejected", "conditional" ] }, "approved_at": { "type": "string", "format": "date-time", "nullable": true }, "approved_by": { "type": "string", "format": "uuid", "nullable": true }, "next_review_date": { "type": "string", "format": "date", "nullable": true }, "review_frequency_months": { "type": "integer", "default": 12 }, "contact_name": { "type": "string", "nullable": true }, "contact_email": { "type": "string", "nullable": true }, "contact_phone": { "type": "string", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TrainingRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requirement_id": { "type": "string", "format": "uuid", "nullable": true }, "org_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "training_name": { "type": "string" }, "training_date": { "type": "string", "format": "date" }, "expiry_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "enum": [ "planned", "completed", "expired", "cancelled" ] }, "evidence_id": { "type": "string", "format": "uuid", "nullable": true }, "certificate_notes": { "type": "string", "nullable": true }, "recorded_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Pagination": { "type": "object", "description": "Cursor- or offset-based pagination envelope returned alongside list payloads.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query, ignoring limit/offset." }, "limit": { "type": "integer", "description": "Maximum number of records returned in this page." }, "offset": { "type": "integer", "description": "Zero-based offset of the first record in this page." }, "has_more": { "type": "boolean", "description": "True when more records exist beyond this page." }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor to pass back for the next page (cursor APIs only)." } } }, "ValidationError": { "type": "object", "description": "Field-level validation error envelope returned for 400-class failures (e.g. Zod parse failures).", "properties": { "error": { "type": "string" }, "details": { "type": "string", "nullable": true }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "code": { "type": "string", "nullable": true } } } } } }, "LibraryDocument": { "type": "object", "description": "A document in the per-organization library — either uploaded by a user or AI-generated.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "category": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "uploaded", "ai_generated", "user_written" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "file_size_bytes": { "type": "integer", "nullable": true }, "mime_type": { "type": "string", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "project_name": { "type": "string", "nullable": true }, "markdown_content": { "type": "string", "nullable": true, "description": "AI documents only." }, "storage_path": { "type": "string", "nullable": true }, "openai_file_id": { "type": "string", "nullable": true }, "filespace_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Uploaded files only." }, "provider_file_id": { "type": "string", "nullable": true }, "provider_status": { "type": "string", "nullable": true, "description": "'indexed' or 'active' = in the vector DB (AI files); 'pending' = not yet indexed." } } }, "InterviewTurn": { "type": "object", "description": "A single question/answer turn inside an interview session.", "properties": { "id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "question_id": { "type": "string", "format": "uuid", "nullable": true }, "turn_index": { "type": "integer" }, "role": { "type": "string", "enum": [ "interviewer", "participant", "system" ] }, "question_text": { "type": "string", "nullable": true }, "answer_text": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ConsultantAssignment": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "consultant_id": { "type": "string", "format": "uuid" }, "consultant_role": { "type": "string", "enum": [ "member", "reviewer", "approver" ] }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "responses": { "UnauthorizedError": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized", "details": "Valid authentication token required" } } } }, "ForbiddenError": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Forbidden", "details": "You do not have permission to access this resource" } } } }, "ConflictError": { "description": "Conflict — the resource already exists or is in a conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Conflict", "details": "A pending invitation already exists for this email." } } } }, "NotFoundError": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Not Found", "details": "The requested resource does not exist" } } } }, "ValidationError": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Validation Error", "details": "Invalid request parameters" } } } }, "BadRequestError": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Bad Request", "details": "Invalid request" } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Internal Server Error", "details": "An unexpected error occurred" } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Internal Server Error", "details": "An unexpected error occurred" } } } } } } }