{ "openapi": "3.1.0", "info": { "title": "BuildVouch API", "version": "1.0.0", "description": "Release evidence and review API. No certification, raw credential storage or automatic deployment." }, "servers": [ { "url": "/api/v1" } ], "paths": { "/products/{id}/connect": { "get": { "operationId": "buildvouchOperation1", "summary": "GitHub App setup and connection status", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } }, "post": { "operationId": "buildvouchOperation2", "summary": "Guided GitHub App onboarding", "description": "Human organisation owner only. Start and disconnect require recent MFA. A single-use 15-minute actor/product-bound intent and PKCE protect OAuth; repository selection must come from the provider-authorized list. Detected workflows remain unmapped; the first report does not grant release PASS.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "start", "authorize", "detect", "connect", "disconnect" ] }, "intent": { "type": "string", "format": "uuid" }, "state": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "code": { "type": "string", "minLength": 1, "maxLength": 256 }, "repository_id": { "type": "integer" } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products/{id}/timeline": { "get": { "operationId": "buildvouchOperation3", "summary": "Read immutable change observations; optional before sequence cursor", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products/{id}/history": { "post": { "operationId": "buildvouchOperation4", "summary": "Import one oldest-first GitHub PR history page", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products/{id}/observations": { "post": { "operationId": "buildvouchOperation5", "summary": "Append an unverified adapter report", "description": "A product-scoped evidence:write token or an owner/editor session is required. Deployment reports identify the executor. Adapter identity claims remain unverified and cannot grant release approval.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repository": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$", "maxLength": 200 }, "environment": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$" }, "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "stage": { "type": "string", "enum": [ "lovable_sync", "deployment", "runtime", "migrations" ] }, "status": { "type": "string", "enum": [ "success", "failed", "unknown" ] }, "observed_at": { "type": "string", "format": "date-time" }, "request_key": { "type": "string", "minLength": 8, "maxLength": 160 }, "initiated_by": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "app_adapter" ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 200 }, "stable_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "enum": [ "human", "service", "unknown" ] }, "profile_url": { "type": "string", "format": "uri", "maxLength": 1000 } }, "required": [ "provider", "subject", "kind" ], "additionalProperties": false }, "executed_by": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "app_adapter" ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 200 }, "stable_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "enum": [ "human", "service", "unknown" ] }, "profile_url": { "type": "string", "format": "uri", "maxLength": 1000 } }, "required": [ "provider", "subject", "kind" ], "additionalProperties": false }, "approved_by": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "app_adapter" ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 200 }, "stable_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "enum": [ "human", "service", "unknown" ] }, "profile_url": { "type": "string", "format": "uri", "maxLength": 1000 } }, "required": [ "provider", "subject", "kind" ], "additionalProperties": false } }, "expected_migrations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "checksum": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "name", "checksum" ], "additionalProperties": false } }, "applied_migrations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "checksum": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "name", "checksum" ], "additionalProperties": false } } }, "required": [ "repository", "environment", "commit_sha", "stage", "status", "observed_at", "request_key" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/health": { "get": { "operationId": "buildvouchOperation6", "summary": "Service availability", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/organizations": { "get": { "operationId": "buildvouchOperation7", "summary": "List accessible organisations", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products": { "get": { "operationId": "buildvouchOperation8", "summary": "List organisation applications", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } }, "parameters": [ { "name": "org", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Organisation slug." } ] }, "post": { "operationId": "buildvouchOperation9", "summary": "Register an application", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "repository_url": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 1000 }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "org_id", "name", "slug" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products/{id}": { "get": { "operationId": "buildvouchOperation10", "summary": "Read an application", "description": "Session or product-bound read token.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products/{id}/assurance": { "get": { "operationId": "buildvouchOperation11", "summary": "Read recent evidence and security register", "description": "Session or product-bound read token. Returns up to 100 evidence records, 200 findings, 100 incidents, 50 releases and 200 matching exceptions. The release evaluator uses all database records.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products/{id}/evidence": { "post": { "operationId": "buildvouchOperation12", "summary": "Append an unverified evidence claim", "description": "Owner/editor session or product-bound evidence:write token. Caller-supplied verification fields are rejected. Idempotent by product and request_key.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$" }, "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "repository": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$", "maxLength": 200 }, "control_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, "result": { "type": "string", "enum": [ "passed", "failed", "unknown" ] }, "summary": { "type": "string", "maxLength": 2000 }, "source_url": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 1000 }, { "type": "null" } ] }, "request_key": { "type": "string", "minLength": 8, "maxLength": 160 } }, "required": [ "environment", "commit_sha", "repository", "control_key", "result", "request_key" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products/{id}/releases": { "post": { "operationId": "buildvouchOperation13", "summary": "Evaluate a release candidate", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "commit_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "environment": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$" }, "request_key": { "type": "string", "minLength": 8, "maxLength": 160 } }, "required": [ "commit_sha", "environment", "request_key" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products/{id}/sync": { "post": { "operationId": "buildvouchOperation14", "summary": "Fetch verified GitHub workflow metadata", "description": "Owner/editor. Requires server-configured selected repository and secret. Reads current default-branch SHA and up to 100 workflow runs. Does not deploy or write GitHub.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/products/{id}/tokens": { "get": { "operationId": "buildvouchOperation15", "summary": "List safe API token metadata", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } }, "post": { "operationId": "buildvouchOperation16", "summary": "Create or revoke a scoped token", "description": "Owner with recent MFA. Create requires name and scopes; revoke requires token_id. Token values are returned once.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "revoke" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "evidence:write" ] } }, "token_id": { "type": "string", "format": "uuid" } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/findings": { "post": { "operationId": "buildvouchOperation17", "summary": "Open a security finding", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "product_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$" }, "control_key": { "anyOf": [ { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" }, { "type": "null" } ] }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "maxLength": 4000 }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "owner_label": { "type": "string", "maxLength": 120 }, "due_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "org_id", "product_id", "title", "severity" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/findings/{id}": { "patch": { "operationId": "buildvouchOperation18", "summary": "Transition or assign a finding", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "triaged", "remediating", "fixed", "verified", "closed" ] }, "owner_label": { "type": "string", "maxLength": 120 }, "due_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "remediation": { "type": "string", "maxLength": 4000 }, "fix_sha": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{40}$" }, { "type": "null" } ] } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/findings/{id}/exception": { "post": { "operationId": "buildvouchOperation19", "summary": "Approve a time-bound noncritical exception", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 20, "maxLength": 2000 }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "reason", "expires_at" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/incidents": { "post": { "operationId": "buildvouchOperation20", "summary": "Open an incident", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "product_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$" }, "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "maxLength": 4000 }, "incident_type": { "type": "string", "enum": [ "credential", "access", "availability", "data", "other" ] }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "fingerprint": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "owner_label": { "type": "string", "maxLength": 120 } }, "required": [ "org_id", "product_id", "title", "incident_type", "severity" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/incidents/{id}": { "patch": { "operationId": "buildvouchOperation21", "summary": "Advance an incident", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "detected", "contained", "eradicated", "recovered", "postmortem_complete" ] }, "owner_label": { "type": "string", "maxLength": 120 }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "rotated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "postmortem_url": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/releases/{id}": { "get": { "operationId": "buildvouchOperation22", "summary": "Recheck current release evidence and approval", "description": "Session or product-bound read token. CI must require current=true and approval_valid=true, with exact commit_sha and environment.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/releases/{id}/approve": { "post": { "operationId": "buildvouchOperation23", "summary": "Approve deployment of the exact candidate", "description": "An independent owner with recent MFA. Approval is separate from deployment; no deployment is performed.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/releases/{id}/export": { "post": { "operationId": "buildvouchOperation24", "summary": "Download an audited Trust Pack", "description": "Organisation member with recent MFA. Returns the stored release, current validity and evidence metadata.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/requirements": { "post": { "operationId": "buildvouchOperation25", "summary": "Add a mandatory custom requirement", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "control_key": { "type": "string", "pattern": "^custom_[a-z0-9_]{1,56}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "maxLength": 2000 }, "freshness_hours": { "type": "integer" } }, "required": [ "org_id", "control_key", "title", "description", "freshness_hours" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/cms/access": { "get": { "operationId": "buildvouchOperation26", "summary": "Check platform content role", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/cms": { "get": { "operationId": "buildvouchOperation27", "summary": "List CMS drafts for content operators", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/cms/save": { "post": { "operationId": "buildvouchOperation28", "summary": "Save an immutable draft revision", "description": "A signed-in organisation member is required. Role and recent MFA requirements are enforced by the server and database.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,79}$" }, "kind": { "type": "string", "enum": [ "guide", "how-to", "reference", "changelog", "legal" ] }, "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "maxLength": 500 }, "body": { "type": "string", "minLength": 1 }, "base_revision_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "request_key": { "type": "string", "minLength": 8, "maxLength": 160 } }, "required": [ "slug", "kind", "title", "summary", "body", "base_revision_id", "request_key" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/cms/publish": { "post": { "operationId": "buildvouchOperation29", "summary": "publish content", "description": "Platform content role required. Publish and retire require publisher role and recent MFA. Publishing legal content additionally requires explicit review confirmation.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,79}$" }, "revision_id": { "type": "string", "format": "uuid" }, "legal_review_confirmed": { "type": "boolean" } }, "required": [ "slug" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/cms/retire": { "post": { "operationId": "buildvouchOperation30", "summary": "retire content", "description": "Platform content role required. Publish and retire require publisher role and recent MFA. Publishing legal content additionally requires explicit review confirmation.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,79}$" }, "revision_id": { "type": "string", "format": "uuid" }, "legal_review_confirmed": { "type": "boolean" } }, "required": [ "slug" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/cms/history": { "post": { "operationId": "buildvouchOperation31", "summary": "history content", "description": "Platform content role required. Publish and retire require publisher role and recent MFA. Publishing legal content additionally requires explicit review confirmation.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,79}$" }, "revision_id": { "type": "string", "format": "uuid" }, "legal_review_confirmed": { "type": "boolean" } }, "required": [ "slug" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/invitations/create": { "post": { "operationId": "buildvouchOperation32", "summary": "create invitation", "description": "Signed-in human required. Owner + recent MFA for create/revoke. List requires org_id and owner. Inspect/accept requires a single-use token and matching verified email. Owner invitation acceptance also requires recent MFA. No email is sent automatically.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ] }, "request_key": { "type": "string", "minLength": 8, "maxLength": 160 }, "token": { "type": "string", "pattern": "^bvi_[a-f0-9]{64}$" }, "id": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/invitations/list": { "post": { "operationId": "buildvouchOperation33", "summary": "list invitation", "description": "Signed-in human required. Owner + recent MFA for create/revoke. List requires org_id and owner. Inspect/accept requires a single-use token and matching verified email. Owner invitation acceptance also requires recent MFA. No email is sent automatically.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ] }, "request_key": { "type": "string", "minLength": 8, "maxLength": 160 }, "token": { "type": "string", "pattern": "^bvi_[a-f0-9]{64}$" }, "id": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/invitations/inspect": { "post": { "operationId": "buildvouchOperation34", "summary": "inspect invitation", "description": "Signed-in human required. Owner + recent MFA for create/revoke. List requires org_id and owner. Inspect/accept requires a single-use token and matching verified email. Owner invitation acceptance also requires recent MFA. No email is sent automatically.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ] }, "request_key": { "type": "string", "minLength": 8, "maxLength": 160 }, "token": { "type": "string", "pattern": "^bvi_[a-f0-9]{64}$" }, "id": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/invitations/accept": { "post": { "operationId": "buildvouchOperation35", "summary": "accept invitation", "description": "Signed-in human required. Owner + recent MFA for create/revoke. List requires org_id and owner. Inspect/accept requires a single-use token and matching verified email. Owner invitation acceptance also requires recent MFA. No email is sent automatically.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ] }, "request_key": { "type": "string", "minLength": 8, "maxLength": 160 }, "token": { "type": "string", "pattern": "^bvi_[a-f0-9]{64}$" }, "id": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } }, "/invitations/revoke": { "post": { "operationId": "buildvouchOperation36", "summary": "revoke invitation", "description": "Signed-in human required. Owner + recent MFA for create/revoke. List requires org_id and owner. Inspect/accept requires a single-use token and matching verified email. Owner invitation acceptance also requires recent MFA. No email is sent automatically.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ] }, "request_key": { "type": "string", "minLength": 8, "maxLength": 160 }, "token": { "type": "string", "pattern": "^bvi_[a-f0-9]{64}$" }, "id": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation, including the data payload and request ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid fields or state transition." }, "401": { "description": "Session or token required." }, "403": { "description": "Role, token scope, independent review or recent MFA requirement not met." }, "409": { "description": "Idempotency or revision conflict." }, "429": { "description": "Rate limit reached. Respect Retry-After." }, "503": { "description": "Backend, integration or deployment configuration unavailable." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Supabase user access token or BuildVouch product-scoped API token." } }, "schemas": { "Envelope": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": {}, "request_id": { "type": "string", "format": "uuid" } } } } } }