{ "openapi": "3.1.0", "info": { "title": "SecBoost API", "version": "1.14.0", "description": "Project, organisation and Administration credentials select canonical application permissions independently of explicit read-only execution. Selected and current actor permissions, type/target boundaries and normal workflow all apply; every mutation requires mutation-enabled mode." }, "servers": [{ "url": "/api/v1" }], "security": [{ "bearerAuth": [] }], "paths": { "/projects/{project}/inputs": { "get": { "operationId": "getProjectInputs", "summary": "Read safe operational project inputs", "description": "Returns only the project identity, hierarchy references, ISM release, classification, lifecycle state and Essential Eight target. It does not disclose controls, evidence, assessment, scope or shared context data.", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Safe project input projection", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectInputs" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/artefacts/network-diagram/file": {"get": {"operationId": "downloadProjectDiagram", "summary": "Download the ready assessment network diagram", "description": "Streams only ready diagrams through the existing storage and safe file-response policy. Bound target, selected/live view-projects and current project-read policy apply. Read-only credentials are supported. Files are private and responses use no-store. Pending, failed or missing diagrams return 404.", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [{"$ref": "#/components/parameters/ProjectId"}], "responses": {"200": {"description": "Ready scanned diagram bytes. Verify SHA-256 against artefact discovery metadata.", "content": {"image/png": {"schema": {"type": "string", "format": "binary"}}, "image/jpeg": {"schema": {"type": "string", "format": "binary"}}, "image/webp": {"schema": {"type": "string", "format": "binary"}}}, "headers": {"Cache-Control": {"schema": {"type": "string"}, "description": "private, no-store"}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "503": {"description": "Storage temporarily unavailable."}}}}, "/projects/{project}/context": { "get": { "operationId": "getOperationalProjectContext", "summary": "Read canonical organisation/system context.", "description": "Read canonical organisation/system context. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "manage-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Read canonical organisation/system context.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectContext" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/scope": { "get": { "operationId": "getOperationalProjectScope", "summary": "Read saved assessment scope without provider-selection management metadata.", "description": "Read saved assessment scope without provider-selection management metadata. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "manage-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Read saved assessment scope without provider-selection management metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OperationalScope" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/engagement": { "get": { "operationId": "getOperationalProjectEngagement", "summary": "Read allowlisted engagement details.", "description": "Read allowlisted engagement details. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Read allowlisted engagement details.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OperationalEngagement" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/contacts": { "get": { "operationId": "listProjectSystemContacts", "summary": "Read active contacts in the project's system; shared writes are excluded.", "description": "Read active contacts in the project's system; shared writes are excluded. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-contacts", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Read active contacts in the project's system; shared writes are excluded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectContact" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "total": { "type": "integer" }, "current_page": { "type": "integer" }, "page_size": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/registers": { "get": { "operationId": "listProjectRegisterDefinitions", "summary": "Discover manual register manifests. Generated registers are Docsuite outputs only.", "description": "Discover manual register manifests. Generated registers are Docsuite outputs only. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Discover manual register manifests. Generated registers are Docsuite outputs only.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegisterDefinition" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/registers/{definition}/reviews": { "get": { "operationId": "listProjectRegisterReviews", "summary": "Read review history for this project and manual register definition.", "description": "Read project-context review assertions, newest reviewed time then ID. Requires selected/live view-registers and current access to the explicit bound project. System/organisation definitions remain project-context reviews; generated definitions return 404. No other project history or shared-owner certification is exposed.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": [ "project" ], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Paginated project-context register review history.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegisterReview" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "total": { "type": "integer" }, "current_page": { "type": "integer" }, "page_size": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "recordProjectRegisterReview", "summary": "Record an attributed project-context register review.", "description": "Append a user review assertion for a non-generated definition in an editable bound project. Requires selected/live view-registers and manage-registers plus mutation-enabled execution and normal actor authority. Only optional nullable notes are accepted; the server sets actor/time. This does not snapshot or approve contents, change register rows or certify a shared owner review. Matching token/action/target/notes retries replay for 24 hours after fresh authority checks; omitted notes and null are equivalent. After receipt expiry, read history before creating again. No If-Match is required for append-only creation.", "x-required-permission": "manage-registers", "x-execution-mode": "mutation-enabled", "x-token-types": [ "project" ], "x-side-effects": "project-context review record, existing REGISTER_REVIEWED audit and 24-hour creation receipt; no register-row mutation or queued work", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created review assertion, or matching authorised receipt replay.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RegisterReview" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "400": { "description": "Idempotency-Key missing, empty or over 255 characters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Idempotency-Key mismatch (token + operation + target + canonical payload); receipts retained 24 hours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterReviewCreate" } } } } } }, "/projects/{project}/registers/{definition}/rows": { "get": { "operationId": "listProjectRegisterRows", "summary": "Read project and same-system shared rows; organisation-owned rows are not in project context.", "description": "Read project and same-system shared rows; organisation-owned rows are not in project context. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Read project and same-system shared rows; organisation-owned rows are not in project context.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegisterRow" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "total": { "type": "integer" }, "current_page": { "type": "integer" }, "page_size": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createProjectRegisterRow", "summary": "Create a project-owned manual register row; requires view-registers and manage-registers.", "description": "Create a project-owned manual register row; requires view-registers and manage-registers. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "manage-registers", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "audited resource mutation", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Create a project-owned manual register row; requires view-registers and manage-registers.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RegisterRow" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "400": { "description": "Idempotency-Key missing, empty or over 255 characters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Idempotency-Key mismatch (token + operation + target + canonical payload); receipts retained 24 hours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRowWrite" } } } } } }, "/projects/{project}/registers/{definition}/rows/{row}": { "get": { "operationId": "getProjectRegisterRow", "summary": "Read one authorised register row.", "description": "Read one authorised register row. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/RowId" } ], "responses": { "200": { "description": "Read one authorised register row.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RegisterRow" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "ETag": { "description": "Strong representation/state hash. Retain for the next mutation.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateProjectRegisterRow", "summary": "Merge manifest fields into a project-owned manual row; shared/generated writes forbidden.", "description": "Merge manifest fields into a project-owned manual row; shared/generated writes forbidden. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "manage-registers", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "audited resource mutation", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/RowId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Merge manifest fields into a project-owned manual row; shared/generated writes forbidden.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RegisterRow" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "ETag": { "description": "Strong representation/state hash. Retain for the next mutation.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "description": "Stale ETag; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/RegisterRowWrite" } } } } } }, "/projects/{project}/document-owners": { "get": { "operationId": "listProjectDocumentOwners", "summary": "Discover active organisation team members by ID/name for library ownership.", "description": "Discover active organisation team members by ID/name for library ownership. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-controls", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Discover active organisation team members by ID/name for library ownership.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IdentifierName" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "total": { "type": "integer" }, "current_page": { "type": "integer" }, "page_size": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/library": { "get": { "operationId": "listProjectLibrary", "summary": "Read active definitions and working copies without creating placeholder records.", "description": "Read active definitions and working copies without creating placeholder records. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-controls", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Read active definitions and working copies without creating placeholder records.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectLibrary" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/library/{definition}": { "get": { "operationId": "getProjectLibraryDocument", "summary": "Read a working copy or an empty side-effect-free placeholder.", "description": "Read a working copy or an empty side-effect-free placeholder. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-controls", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DefinitionId" } ], "responses": { "200": { "description": "Read a working copy or an empty side-effect-free placeholder.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectLibrary" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "ETag": { "description": "Strong representation/state hash. Retain for the next mutation.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateProjectLibraryDocument", "summary": "Merge working-copy fields; requires view-controls and edit-control-implementation. Owner must be active organisation member; review_due cannot precede date_live. Normal drift/audit/version lifecycle applies.", "description": "Merge working-copy fields; requires view-controls and edit-control-implementation. Owner must be active organisation member; review_due cannot precede date_live. Normal drift/audit/version lifecycle applies. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "edit-control-implementation", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "audited resource mutation", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Merge working-copy fields; requires view-controls and edit-control-implementation. Owner must be active organisation member; review_due cannot precede date_live. Normal drift/audit/version lifecycle applies.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectLibrary" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "ETag": { "description": "Strong representation/state hash. Retain for the next mutation.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "description": "Stale ETag; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/LibraryPatch" } } } } } }, "/projects/{project}/documents": { "get": { "operationId": "listProjectDocuments", "summary": "Read the normal project Docsuite template catalogue, including generated-register outputs.", "description": "Read the normal project Docsuite template catalogue, including generated-register outputs. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-docsuite", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Read the normal project Docsuite template catalogue, including generated-register outputs.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentCatalogueEntry" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/documents/{document}": { "get": { "operationId": "getProjectDocument", "summary": "Read safe output metadata and normal dependency evaluation. document is the row ULID, not template key.", "description": "Read safe output metadata and normal dependency evaluation. document is the row ULID, not template key. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-docsuite", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DocumentId" } ], "responses": { "200": { "description": "Read safe output metadata and normal dependency evaluation. document is the row ULID, not template key.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectDocument" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/documents/{document}/download": { "get": { "operationId": "downloadProjectDocument", "summary": "Download an existing draft/final normal workflow output. Storage paths and raw metadata/errors are never returned.", "description": "Download an existing draft/final normal workflow output. Storage paths and raw metadata/errors are never returned. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-docsuite", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DocumentId" } ], "responses": { "200": { "description": "Streamed output with private/no-store caching.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Temporary storage unavailability.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/projects/{project}/documents/{document}/generation": { "post": { "operationId": "generateProjectDocument", "summary": "Queue one normal document generation. Requires view-docsuite and generate-docsuite; rejects archived projects and non-generatable states. Final output requires explicit approval; dependencies/status remain normal workflow rules. Jobs recheck token expiry/revocation, binding, abilities and live permissions before durable work.", "description": "Queue one normal document generation. Requires view-docsuite and generate-docsuite; rejects archived projects and non-generatable states. Final output requires explicit approval; dependencies/status remain normal workflow rules. Jobs recheck token expiry/revocation, binding, abilities and live permissions before durable work. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "generate-docsuite", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "project generation lease, audit, queued normal document rendering/storage/versioning", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DocumentId" } ], "responses": { "202": { "description": "Queue one normal document generation. Requires view-docsuite and generate-docsuite; rejects archived projects and non-generatable states. Final output requires explicit approval; dependencies/status remain normal workflow rules. Jobs recheck token expiry/revocation, binding, abilities and live permissions before durable work.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectDocument" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "Location": { "description": "Poll this generation status URL.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Dependencies incomplete or another generation holds the project lease.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentGeneration" } } } } }, "get": { "operationId": "getProjectDocumentGeneration", "summary": "Poll safe document status and dependencies; draft/final output becomes downloadable.", "description": "Poll safe document status and dependencies; draft/final output becomes downloadable. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-docsuite", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/DocumentId" } ], "responses": { "200": { "description": "Poll safe document status and dependencies; draft/final output becomes downloadable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectDocument" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/tasks": { "get": { "operationId": "listProjectTasks", "summary": "Read explicitly project-owned tasks visible through the normal assignment/team rules.", "description": "Read explicitly project-owned tasks visible through the normal assignment/team rules. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-tasks", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Read explicitly project-owned tasks visible through the normal assignment/team rules.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTask" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "total": { "type": "integer" }, "current_page": { "type": "integer" }, "page_size": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/tasks/{task}": { "get": { "operationId": "getProjectTask", "summary": "Read a task; related control must belong to the same project.", "description": "Read a task; related control must belong to the same project. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-tasks", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "description": "Read a task; related control must belong to the same project.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectTask" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "ETag": { "description": "Strong representation/state hash. Retain for the next mutation.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/tasks/{task}/claim": { "post": { "operationId": "claimProjectTask", "summary": "Claim a team task for the current actor; team membership or manage-tasks required.", "description": "Claim a team task for the current actor; team membership or manage-tasks required. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-tasks", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "audited resource mutation", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/TaskId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Claim a team task for the current actor; team membership or manage-tasks required.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectTask" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "ETag": { "description": "Strong representation/state hash. Retain for the next mutation.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "description": "Stale ETag; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyTaskAction" } } } } } }, "/projects/{project}/tasks/{task}/release": { "post": { "operationId": "releaseProjectTask", "summary": "Release a team task; current assignee or manage-tasks required.", "description": "Release a team task; current assignee or manage-tasks required. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-tasks", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "audited resource mutation", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/TaskId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Release a team task; current assignee or manage-tasks required.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectTask" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "ETag": { "description": "Strong representation/state hash. Retain for the next mutation.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "description": "Stale ETag; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyTaskAction" } } } } } }, "/projects/{project}/tasks/{task}/comments": { "post": { "operationId": "createProjectTaskComment", "summary": "Add a bounded comment to a visible task; requires view-tasks. No arbitrary assignment/status writes.", "description": "Add a bounded comment to a visible task; requires view-tasks. No arbitrary assignment/status writes. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-tasks", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "audited resource mutation", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/TaskId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Add a bounded comment to a visible task; requires view-tasks. No arbitrary assignment/status writes.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TaskComment" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "400": { "description": "Idempotency-Key missing, empty or over 255 characters.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Idempotency-Key mismatch (token + operation + target + canonical payload); receipts retained 24 hours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCommentWrite" } } } } }, "get": { "operationId": "listProjectTaskComments", "summary": "Read a bounded page of task comments without raw activity metadata.", "description": "Read a bounded page of task comments without raw activity metadata. Explicit target within the credential boundary; live permissions and access are rechecked. The selected UI project is never authority.", "x-required-permission": "view-tasks", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/TaskId" }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Read a bounded page of task comments without raw activity metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskComment" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "total": { "type": "integer" }, "current_page": { "type": "integer" }, "page_size": { "type": "integer" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/documents/generation": { "post": { "operationId": "generateProjectDocumentTemplate", "summary": "Generate a catalogue template without a prior UI-created output slot.", "description": "Accept document_key from the project catalogue. Under the project lock, initialise its normal output slot if absent and queue generation through the same lease/status/dependency/final-approval rules. Catalogue GET remains side-effect free. After a lost response, reconcile /documents before retrying; the active project lease prevents duplicate generation.", "x-required-permission": "generate-docsuite", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "project generation lease, audit, queued normal document rendering/storage/versioning", "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "202": { "description": "Queue one normal document generation. Requires view-docsuite and generate-docsuite; rejects archived projects and non-generatable states. Final output requires explicit approval; dependencies/status remain normal workflow rules. Jobs recheck token expiry/revocation, binding, abilities and live permissions before durable work.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProjectDocument" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } }, "required": [ "data" ] } } }, "headers": { "Location": { "description": "Poll this generation status URL.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Dependencies incomplete or another generation holds the project lease.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTemplateGeneration" } } } } } }, "/organisations/{organisation}": { "get": { "operationId": "getOrganisation", "summary": "Read an authorised organisation identity", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": [ "organisation", "administration" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Read an authorised organisation identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrganisationIdentity" } }, "required": [ "data" ] } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Read the authorised organisation identity. Organisation keys require manage-org-hierarchy within their fixed binding; Administration keys require manage-org-hierarchy. Current organisation access is checked. No context, logo, system or project access is granted by manage-org-hierarchy.", "x-side-effects": "none", "x-required-permissions-by-token-type": { "organisation": "manage-org-hierarchy", "administration": "manage-org-hierarchy" } }, "patch": { "operationId": "updateOrganisation", "summary": "Edit organisation identity", "description": "Allowlisted identity/contact fields only; no status, ownership, membership or permission administration. Requires current manage-org-hierarchy authority and active organisation. Locked persisted-state If-Match; omitted fields remain unchanged.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": [ "organisation" ], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Update allowlisted organisation identity fields", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrganisationIdentity" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "412": { "description": "Stale state; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/OrganisationPatch" } } } } } }, "/organisations/{organisation}/systems": {"get": {"operationId": "listOrganisationSystems", "summary": "List prepared systems in the bound organisation", "x-permission-alternatives": [["manage-org-hierarchy"], ["view-projects", "manage-projects"]], "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}], "responses": {"200": {"description": "List prepared systems in the bound organisation", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"type": "object", "properties": {"id": {"$ref": "#/components/schemas/Ulid"}, "organisation_id": {"$ref": "#/components/schemas/Ulid"}, "name": {"type": "string", "maxLength": 255}, "short_code": {"type": ["string", "null"], "maxLength": 255}, "description": {"type": ["string", "null"], "maxLength": 5000}}}}}, "required": ["data"]}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "description": "List prepared systems in the bound organisation. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "none"}, "post": { "operationId": "createOrganisationSystem", "summary": "Create a system in the bound organisation", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection. Creation receipts last 24 hours; exact retries replay before uniqueness checks.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Create a system in the bound organisation", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemIdentity" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "description": "Missing or invalid Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Key reused with a different target or canonical payload.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemCreate" } } } } }}, "/organisations/{organisation}/systems/{system}/projects": {"get": {"operationId": "listOrganisationProjects", "summary": "List project setup records in a prepared system", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}], "responses": {"200": {"description": "List project setup records in a prepared system", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"type": "object", "description": "ProjectResource setup record."}}}, "required": ["data"]}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "description": "List project setup records in a prepared system. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "none"}, "post": {"operationId": "createOrganisationProject", "summary": "Create a Setup project", "description": "Creates one project in the named prepared system. Idempotency-Key is required; matching retries replay the original response for 24 hours and changed payload reuse returns 409.", "x-required-permission": "manage-projects", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/IdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectSetupCreate"}}}}, "responses": {"201": {"description": "Create a Setup project", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/ProjectSetup"}}, "required": ["data"]}}}, "headers": {"Idempotency-Replayed": {"schema": {"type": "string", "enum": ["true", "false"]}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "415": {"$ref": "#/components/responses/UnsupportedMediaType"}, "422": {"$ref": "#/components/responses/ValidationFailed"}, "409": {"description": "Idempotency key reused with different target system or payload.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}, "400": {"description": "Missing or invalid Idempotency-Key.", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}}, "x-side-effects": "Updates project setup using the existing application services and audit trail."}}, "/organisations/{organisation}/systems/{system}/projects/{project}": {"get": {"operationId": "getOrganisationProject", "summary": "Read project setup", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}], "responses": {"200": {"description": "Read project setup", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/ProjectSetup"}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "description": "Read project setup. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "none"}, "patch": {"operationId": "updateOrganisationProject", "summary": "Update allowlisted project setup fields", "x-required-permission": "manage-projects", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}, {"$ref": "#/components/parameters/SetupIfMatch"}], "responses": {"200": {"description": "Update allowlisted project setup fields", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/ProjectSetup"}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "415": {"$ref": "#/components/responses/UnsupportedMediaType"}, "422": {"$ref": "#/components/responses/ValidationFailed"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "428": {"$ref": "#/components/responses/PreconditionRequired"}}, "description": "Update allowlisted project setup fields. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "Updates project setup using the existing application services and audit trail.", "requestBody": {"required": true, "content": {"application/merge-patch+json": {"schema": {"$ref": "#/components/schemas/ProjectSetupPatch"}}}}}}, "/organisations/{organisation}/systems/{system}/projects/{project}/scope": {"get": {"operationId": "getProjectScope", "summary": "Read assessment scope", "x-required-permission": "manage-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "responses": {"200": {"description": "Read assessment scope", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": ["object", "null"], "description": "Saved assessment scope profile, including its data and scope version."}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}], "description": "Read assessment scope. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "none"}, "patch": {"operationId": "updateProjectScope", "summary": "Update assessment scope", "description": "Scope and provider-selection changes use manage-projects and the current project-update policy. Published release and service/region validation remain required.", "x-required-permission": "manage-projects", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "responses": {"200": {"description": "Update assessment scope", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": ["object", "null"], "description": "Saved assessment scope profile, including its data and scope version."}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "415": {"$ref": "#/components/responses/UnsupportedMediaType"}, "422": {"$ref": "#/components/responses/ValidationFailed"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "428": {"$ref": "#/components/responses/PreconditionRequired"}}, "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}, {"$ref": "#/components/parameters/SetupIfMatch"}], "x-side-effects": "Updates project setup using the existing application services and audit trail.", "requestBody": {"required": true, "content": {"application/merge-patch+json": {"schema": {"$ref": "#/components/schemas/ProjectScopeUpdate"}}}}}}, "/organisations/{organisation}/systems/{system}/projects/{project}/engagement": {"get": {"operationId": "getProjectEngagement", "summary": "Read assessment engagement", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "responses": {"200": {"description": "Read assessment engagement", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": ["object", "array"], "description": "Saved non-empty engagement details; [] when absent."}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}], "description": "Read assessment engagement. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "none"}, "patch": {"operationId": "updateProjectEngagement", "summary": "Update assessment engagement", "x-required-permission": "manage-projects", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "responses": {"200": {"description": "Update assessment engagement", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": ["object", "array"], "description": "Saved non-empty engagement details; [] when absent."}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "415": {"$ref": "#/components/responses/UnsupportedMediaType"}, "422": {"$ref": "#/components/responses/ValidationFailed"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "428": {"$ref": "#/components/responses/PreconditionRequired"}}, "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}, {"$ref": "#/components/parameters/SetupIfMatch"}], "description": "Update assessment engagement. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "Updates project setup using the existing application services and audit trail.", "requestBody": {"required": true, "content": {"application/merge-patch+json": {"schema": {"$ref": "#/components/schemas/ProjectEngagementUpdate"}}}}}}, "/organisations/{organisation}/systems/{system}/projects/{project}/population": {"get": {"operationId": "getProjectPopulation", "summary": "Read control-matrix population status", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "responses": {"200": {"description": "Read control-matrix population status", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "additionalProperties": false, "properties": {"project_id": {"type": "string"}, "run_id": {"type": ["string", "null"], "description": "Current context run ULID; null for legacy runs or after progress cleanup."}, "status": {"type": ["string", "null"], "enum": ["pending", "running", "failed", "completed", null]}, "phase": {"type": ["string", "null"]}, "total_controls": {"type": "integer", "minimum": 0}, "processed_controls": {"type": "integer", "minimum": 0}}, "required": ["project_id", "run_id", "status", "phase", "total_controls", "processed_controls"]}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}, "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}], "description": "Reads the current population run ID and progress with its setup ETag. Completed records are cleaned up after a short delay; read project lifecycle state too. Run changes invalidate setup ETags even within the same second.", "x-side-effects": "none"}, "post": {"operationId": "startProjectPopulation", "summary": "Start or retry context population", "x-required-permission": "manage-projects", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "responses": {"202": {"description": "Start control-matrix population", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "additionalProperties": false, "properties": {"project_id": {"type": "string"}, "run_id": {"type": ["string", "null"], "description": "Current context run ULID; null for legacy runs or after progress cleanup."}, "status": {"type": ["string", "null"], "enum": ["pending", "running", "failed", "completed", null]}, "phase": {"type": ["string", "null"]}, "total_controls": {"type": "integer", "minimum": 0}, "processed_controls": {"type": "integer", "minimum": 0}}, "required": ["project_id", "run_id", "status", "phase", "total_controls", "processed_controls"]}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "415": {"$ref": "#/components/responses/UnsupportedMediaType"}, "422": {"$ref": "#/components/responses/ValidationFailed"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "428": {"$ref": "#/components/responses/PreconditionRequired"}}, "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}, {"$ref": "#/components/parameters/SetupIfMatch"}], "description": "Starts a fresh context run for an empty Setup project or a new run for failed context population on an unarchived Initialising project. Requires selected/live manage-projects and view-projects, mutation-enabled execution, current setup If-Match and normal readiness. Existing controls, recommendations and documents are retained; missing entries use current context. Import/copy recovery and legacy failed runs without known context provenance are excluded. Old jobs keep their original credential and cannot mutate the replacement run. On an uncertain response, read project/population state and refresh the ETag before retrying; this is not creation-receipt replay.", "x-side-effects": "Queues a new attributed context run. Serialises recovery and execution on the project; atomically commits new controls, recommendations, documents and completion. Safe audits retain failed-run attribution. No automatic archiving on context failure.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "maxProperties": 0}}}}}}, "/organisations/{organisation}/setup-options": {"get": {"operationId": "getOrganisationSetupOptions", "summary": "Discover project setup choices", "x-required-permission": "manage-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}], "description": "Discover project setup choices. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "none", "responses": {"200": {"description": "Discover project setup choices", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/ProjectSetupOptions"}}, "required": ["data"]}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}}}, "/organisations/{organisation}/systems/{system}/projects/{project}/artefacts": {"get": {"operationId": "listProjectSetupArtefacts", "summary": "Read project setup artefacts", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}], "description": "Read project setup artefacts. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "none", "responses": {"200": {"description": "Read project setup artefacts", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": ["array", "object", "null"], "description": "Existing artefact registry payload: key, readiness, content/download links and safe upload status."}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}}}, "/organisations/{organisation}/systems/{system}/projects/{project}/artefacts/network-diagram": {"post": {"operationId": "uploadProjectSetupDiagram", "summary": "Upload the assessment network diagram", "x-required-permission": "manage-projects", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}, {"$ref": "#/components/parameters/SetupIfMatch"}], "description": "Upload the assessment network diagram. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "Updates project setup using the existing application services and audit trail.", "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"$ref": "#/components/schemas/ProjectDiagramUpload"}}}}, "responses": {"202": {"description": "Upload the assessment network diagram", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": ["array", "object", "null"], "description": "Existing artefact registry payload: key, readiness, content/download links and safe upload status."}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "415": {"$ref": "#/components/responses/UnsupportedMediaType"}, "422": {"$ref": "#/components/responses/ValidationFailed"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "428": {"$ref": "#/components/responses/PreconditionRequired"}}}}, "/organisations/{organisation}/systems/{system}/projects/{project}/artefacts/network-diagram/file": {"get": {"operationId": "downloadProjectSetupDiagram", "summary": "Download the ready assessment network diagram", "description": "Streams only ready diagrams through the existing storage and safe file-response policy. Bound target, selected/live view-projects and current project-read policy apply. Read-only credentials are supported. Files are private and responses use no-store. Pending, failed or missing diagrams return 404.", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}], "responses": {"200": {"description": "Ready scanned diagram bytes. Verify SHA-256 against artefact discovery metadata.", "content": {"image/png": {"schema": {"type": "string", "format": "binary"}}, "image/jpeg": {"schema": {"type": "string", "format": "binary"}}, "image/webp": {"schema": {"type": "string", "format": "binary"}}}, "headers": {"Cache-Control": {"schema": {"type": "string"}, "description": "private, no-store"}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "503": {"description": "Storage temporarily unavailable."}}}}, "/organisations/{organisation}/systems/{system}/projects/{project}/artefacts/narrative": {"put": {"operationId": "updateProjectSetupNarrative", "summary": "Save the assessment scope narrative", "x-required-permission": "manage-projects", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}, {"$ref": "#/components/parameters/SetupIfMatch"}], "description": "Save the assessment scope narrative. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "Updates project setup using the existing application services and audit trail.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectNarrativeUpdate"}}}}, "responses": {"200": {"description": "Save the assessment scope narrative", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": ["array", "object", "null"], "description": "Existing artefact registry payload: key, readiness, content/download links and safe upload status."}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "415": {"$ref": "#/components/responses/UnsupportedMediaType"}, "422": {"$ref": "#/components/responses/ValidationFailed"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "428": {"$ref": "#/components/responses/PreconditionRequired"}}}}, "/organisations/{organisation}/systems/{system}/projects/{project}/artefacts/narrative/generate": {"post": {"operationId": "generateProjectSetupNarrative", "summary": "Generate the narrative from the saved scope", "x-required-permission": "manage-projects", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "parameters": [{"$ref": "#/components/parameters/OrganisationId"}, {"$ref": "#/components/parameters/SystemId"}, {"$ref": "#/components/parameters/ProjectId"}, {"$ref": "#/components/parameters/SetupIfMatch"}], "description": "Generate the narrative from the saved scope. Requires an organisation key and the issuing user's current permissions and target access.", "x-side-effects": "Updates project setup using the existing application services and audit trail.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "maxProperties": 0}}}}, "responses": {"200": {"description": "Generate the narrative from the saved scope", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": ["array", "object", "null"], "description": "Existing artefact registry payload: key, readiness, content/download links and safe upload status."}}, "required": ["data"]}}}, "headers": {"ETag": {"schema": {"type": "string"}, "description": "Strong setup ETag for subsequent If-Match mutations."}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "415": {"$ref": "#/components/responses/UnsupportedMediaType"}, "422": {"$ref": "#/components/responses/ValidationFailed"}, "412": {"$ref": "#/components/responses/PreconditionFailed"}, "428": {"$ref": "#/components/responses/PreconditionRequired"}}}}, "/projects": { "get": { "operationId": "listProjects", "summary": "Discover the token-bound project", "description": "Returns the single bound project. Requires view-controls and view-controls; selected UI context is never authority.", "x-required-permission": "view-projects", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "responses": { "200": { "description": "The currently accessible bound project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/controls": { "get": { "operationId": "listProjectControls", "summary": "List controls in the token-bound project", "description": "Requires view-controls. Assessment properties require view-control-assessment and the user's assessment-view permission. This operation has no side effects.", "x-required-permission": "view-controls", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "name": "filter[search]", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "filter[workflow_state]", "in": "query", "schema": { "$ref": "#/components/schemas/WorkflowState" } }, { "name": "filter[applicability]", "in": "query", "schema": { "$ref": "#/components/schemas/Applicability" } }, { "name": "filter[implementation_status]", "in": "query", "schema": { "$ref": "#/components/schemas/ImplementationStatus" } }, { "name": "filter[assessed_implementation_status]", "in": "query", "description": "Requires assessment-read authority.", "schema": { "$ref": "#/components/schemas/AssessedImplementationStatus" } }, { "name": "filter[applicability_attention]", "in": "query", "schema": { "type": "string", "enum": ["conflicts", "suggested_exclusions"] } }, { "name": "filter[requires_review]", "in": "query", "schema": { "type": "boolean" } }, { "name": "filter[essential_eight]", "in": "query", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["control_id", "-control_id", "description", "-description", "workflow_state", "-workflow_state", "applicability", "-applicability", "implementation_status", "-implementation_status", "assessed_implementation_status", "-assessed_implementation_status", "requires_review", "-requires_review"] } }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "A deterministic page of controls.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/controls/{control}": { "get": { "operationId": "getProjectControl", "summary": "Inspect a control and its current capabilities", "description": "Requires view-controls. Retain the strong ETag for a later mutation. allowed_actions and allowed_transitions are planning hints and are re-authorised at mutation time. This operation has no side effects.", "x-required-permission": "view-controls", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "$ref": "#/components/parameters/IfNoneMatch" }], "responses": { "200": { "$ref": "#/components/responses/ControlDetail" }, "304": { "description": "The representation has not changed." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/controls/{control}/evidence/{evidence}/content": { "get": { "operationId": "getControlEvidenceContent", "summary": "Read authorised live evidence content", "description": "Requires selected/live view-controls and source permissions. Register content additionally requires selected/live view-registers. Returns library Markdown, a deterministic register page, or UTF-8 Bitbucket text. Bitbucket directory and oversized representations return 409 with an authorised download link; provider timeout, temporary failure and other upstream failures return 504, 503 and 502. This operation has no evidence-record side effects.", "x-required-permission": "view-controls", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-conditional-permissions": { "view-registers": "Required for register evidence content." }, "x-side-effects": "none", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "name": "evidence", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }], "responses": { "200": { "description": "Current live evidence content.", "headers": { "Cache-Control": { "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/projects/{project}/controls/{control}/evidence/{evidence}": { "get": { "operationId": "getControlEvidenceMetadata", "summary": "Read stored evidence association metadata and its item ETag.", "description": "Requires selected/live view-controls, current bound-project access and normal item view authority. Returns stored association metadata for all source kinds, without source bytes, credentials or paths. Register evidence additionally requires selected/live view-registers. Invalid or foreign source parents return 404; library view authority applies. Pending/rejected uploaded sources and unavailable repository bytes do not prevent metadata reads. The ETag covers complete association state, not a source content version.", "x-required-permission": "view-controls", "x-execution-mode": "read-only-compatible", "x-token-types": [ "project" ], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "name": "evidence", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stored evidence association metadata and current item ETag.", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "example": "private, no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ControlEvidenceMetadata" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-conditional-permissions": { "view-registers": "Required as selected and live authority when source_kind is register." } }, "patch": { "operationId": "updateControlEvidenceMetadata", "summary": "Edit stored evidence association metadata with a current item ETag.", "description": "Requires selected/live view-controls and edit-control-implementation, mutation-enabled execution, editable project and normal item update authority (Editing control workflow). Register evidence also requires selected/live view-registers; source boundaries and library view authority are rechecked. Only the nine nullable metadata fields are accepted; omission preserves and null clears. At least one field is required. Status/verification/currency claims, UI aliases, source identity, actors, paths and processing fields are rejected. Use this item GET ETag in If-Match, not the control/content ETag. Original credential, project, control and item are locked and authority/source/ETag rechecked before mutation. No source retrieval, file/upload mutation, workflow/claim changes or snapshot rewriting occurs. UI metadata authority and aliases remain unchanged.", "x-required-permission": "edit-control-implementation", "x-execution-mode": "mutation-enabled", "x-token-types": [ "project" ], "x-side-effects": "association metadata update, normal model audit and existing evidence drift refresh; no source retrieval or queued work", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "name": "evidence", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/ControlEvidenceMetadataPatch" } } } }, "responses": { "200": { "description": "Stored evidence association metadata and current item ETag.", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "example": "private, no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ControlEvidenceMetadata" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-conditional-permissions": { "view-registers": "Required as selected and live authority when source_kind is register." } }, "delete": { "operationId": "removeControlEvidence", "summary": "Remove an evidence association with a current item ETag.", "description": "Requires selected/live view-controls and edit-control-implementation, mutation-enabled execution, editable project and normal item deletion authority (Editing control). Register evidence additionally requires selected/live view-registers; normal source boundaries and library view authority apply. Use the evidence metadata GET ETag in If-Match. No request properties are accepted. Operation locks precede credential/project/control/item/file locks; live authority, source binding, ETag and processing state are rechecked before writes. Removal preserves snapshot facts, marks assessment drift before clearing the live snapshot link, retains shared/snapshot files and never deletes a canonical register, document or Bitbucket source. Unreferenced pending uploads are durably rejected and quarantine cleanup is queued; orphan storage deletion runs after commit. Processing files referenced by another item or snapshot return 409. The association is retired immediately. There is no creation receipt; retries return 404. After an uncertain response, read the original item before retrying. Ordinary UI authority and response semantics are retained.", "x-required-permission": "edit-control-implementation", "x-execution-mode": "mutation-enabled", "x-token-types": [ "project" ], "x-side-effects": "association removal, assessment drift and normal deletion audit; orphan file cleanup after commit; pending upload rejection and queued quarantine cleanup", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "name": "evidence", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Association removed. Read-back of the original item returns 404.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "deleted" ], "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-conditional-permissions": { "view-registers": "Required as selected and live authority when source_kind is register." } } }, "/projects/{project}/controls/{control}/evidence/{evidence}/download": { "get": { "operationId": "downloadControlEvidence", "summary": "Download authorised uploaded or Bitbucket evidence", "description": "Requires view-controls and source permission. Returned bytes are not cached; Bitbucket responses include the resolved commit and SHA-256 headers. Provider timeout, temporary failure and other upstream failures return 504, 503 and 502.", "x-required-permission": "view-controls", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "name": "evidence", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Evidence bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/projects/{project}/controls/{control}/implementation": { "patch": { "operationId": "updateControlImplementation", "summary": "Update eligible control implementation properties", "description": "Requires edit-control-implementation and current user/policy authority. Uses JSON Merge Patch and requires the current strong ETag in If-Match. Omitted properties are unchanged; explicit null clears nullable properties. Users may select normal applicable/not-applicable values; classification exclusion is server-owned and cannot be set or overridden. Side effect: updates the control and audit trail. Human approval is not performed.", "x-required-permission": "edit-control-implementation", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "updates control implementation fields and audit metadata", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "$ref": "#/components/parameters/IfMatch" }], "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/ImplementationPatch" } } } }, "responses": { "200": { "$ref": "#/components/responses/ControlDetail" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/controls/{control}/evidence/link-options": { "get": { "operationId": "listControlEvidenceLinkOptions", "summary": "Discover permitted evidence link targets", "description": "Requires view-controls and current source-view permissions. This operation has no side effects and never creates library documents.", "x-required-permission": "view-controls", "x-execution-mode": "read-only-compatible", "x-token-types": ["project"], "x-side-effects": "none", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }], "responses": { "200": { "description": "Permitted register, library document and Bitbucket connection identities.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/projects/{project}/controls/{control}/evidence/uploads": { "post": { "operationId": "uploadControlEvidence", "summary": "Upload evidence for a control", "description": "Requires edit-control-implementation and live implementation-edit authority. A 201 records pending evidence; poll control detail for file processing status. This operation does not require If-Match and is not idempotent.", "x-required-permission": "edit-control-implementation", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "creates an evidence association and asynchronous upload-security operation", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary" }, "title": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created evidence item." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/projects/{project}/controls/{control}/evidence/references": { "post": { "operationId": "createControlEvidenceReference", "summary": "Create external or text reference evidence", "description": "Requires edit-control-implementation and live implementation-edit authority. This operation is not idempotent.", "x-required-permission": "edit-control-implementation", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "creates an evidence association", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Created evidence item." }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/projects/{project}/controls/{control}/evidence/links": { "post": { "operationId": "linkControlEvidence", "summary": "Link an existing evidence source", "description": "Requires edit-control-implementation and current access to the source. Repeating an existing destination/source link returns 200 with already_linked true and preserves its metadata.", "x-required-permission": "edit-control-implementation", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "creates an evidence association when absent", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Existing link." }, "201": { "description": "Created evidence link." }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/projects/{project}/controls/{control}/evidence/{evidence}/replacement": { "post": { "operationId": "replaceControlEvidence", "summary": "Replace uploaded-file evidence through the normal quarantine pipeline.", "description": "Requires selected/live view-controls and edit-control-implementation, mutation-enabled execution, editable bound project and Editing control workflow. Uploaded-file associations only; non-file sources and processing uploads return 409. Supply the current metadata item ETag in If-Match. Accepts only multipart file (20 MiB maximum, normal file rules) and optional nullable description; omission/null preserves the old description. Creates a new processing file/item, carries existing metadata/user assertions, retires the old association immediately and preserves snapshot/shared-file references. Carried assertions do not verify new bytes. No creation receipt: retired-target retries return 404. After an uncertain response, read control evidence before retrying. Poll control detail for new file status; metadata GET supplies its next item ETag. Original token/actor/project/control/item authority is rechecked under locks before release. Reissue cannot adopt old work. Rejected bytes are unavailable and unpublished final objects are cleaned.", "x-required-permission": "edit-control-implementation", "x-execution-mode": "mutation-enabled", "x-token-types": [ "project" ], "x-side-effects": "new processing file/evidence item and original-credential upload operation; retires old association, normal orphan cleanup/drift/model and replacement audits; asynchronous scan/validation/deduplication release", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "name": "evidence", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ControlEvidenceReplacement" } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "202": { "description": "Replacement accepted as a new processing item; this is not successful content release." }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } } } }, "/projects/{project}/controls/{control}/assessment": { "patch": { "operationId": "updateControlAssessment", "summary": "Update eligible control assessment properties", "description": "Requires edit-control-assessment and current user/policy authority. Uses JSON Merge Patch and requires the current strong ETag in If-Match. Omitted properties are unchanged; explicit null clears nullable properties. Side effect: updates the control and audit trail. Human approval is not performed.", "x-required-permission": "edit-control-assessment", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-side-effects": "updates control assessment fields and audit metadata", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "$ref": "#/components/parameters/IfMatch" }], "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/AssessmentPatch" } } } }, "responses": { "200": { "$ref": "#/components/responses/ControlDetail" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{project}/controls/{control}/transitions": { "post": { "operationId": "transitionProjectControl", "summary": "Perform an eligible workflow transition", "description": "Requires view-controls, the action-specific implementation/assessment update or approval ability, and the current strong ETag in If-Match. Use an ID from allowed_transitions. Assessment workflow actions also require view-control-assessment. Implementation approval/rejection additionally requires approve-edits; assessment approval/rejection additionally requires approve-assessments. The server re-evaluates token authority, user policy, workflow configuration, state, domain requirements and gates atomically. A non-blank comment is required and persisted for every approval/rejection decision; comments are rejected for other transitions. Completion transitions may acknowledge evidence that cannot be captured immutably. Side effect: updates workflow state and related domain/audit records.", "x-required-permission": "view-controls", "x-execution-mode": "mutation-enabled", "x-token-types": ["project"], "x-conditional-permissions": { "edit-control-implementation": ["new_to_editing", "editing_to_approving_edit", "editing_to_ready_for_assessment", "ready_for_assessment_to_editing"], "edit-control-assessment": ["new_to_assessing", "ready_for_assessment_to_assessing", "assessing_to_editing", "assessing_to_approving_assessment", "assessing_to_assessed", "assessed_to_assessing"], "approve-edits": ["approving_edit_to_ready_for_assessment", "approving_edit_to_editing"], "approve-assessments": ["approving_assessment_to_assessed", "approving_assessment_to_assessing"] }, "x-side-effects": "updates workflow state, related domain records and audit metadata", "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "$ref": "#/components/parameters/IfMatch" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ControlDetail" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/TransitionUnavailable" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/organisations/{organisation}/systems/{system}": { "get": { "operationId": "getOrganisationSystem", "summary": "Read system identity and its current ETag", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" } ], "responses": { "200": { "description": "Read system identity and its current ETag", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemIdentity" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateOrganisationSystem", "summary": "Update allowlisted system identity fields", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection. If-Match is checked under locks. Omitted fields remain unchanged; null clears nullable fields.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Update allowlisted system identity fields", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemIdentity" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "412": { "description": "Stale state; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/SystemPatch" } } } } } }, "/organisations/{organisation}/systems/{system}/context": { "get": { "operationId": "getSystemContext", "summary": "Read canonical system context and its definition", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" } ], "responses": { "200": { "description": "Read canonical system context and its definition", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemContext" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateSystemContext", "summary": "Merge canonical system context fields", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection. If-Match is checked under locks. Omitted fields remain unchanged; null clears nullable fields.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Merge canonical system context fields", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemContext" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "412": { "description": "Stale state; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/SystemContextPatch" } } } } } }, "/organisations/{organisation}/systems/{system}/contacts": { "get": { "operationId": "listSystemContacts", "summary": "List active contacts owned by this system", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection.", "x-required-permission": "view-contacts", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "List active contacts owned by this system", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SystemContact" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createSystemContact", "summary": "Create a contact owned by this system", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection. Creation receipts last 24 hours; exact retries replay before uniqueness checks.", "x-required-permission": "manage-contacts", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Create a contact owned by this system", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemContact" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "description": "Missing or invalid Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Key reused with a different target or canonical payload.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemContactCreate" } } } } } }, "/organisations/{organisation}/systems/{system}/contacts/{contact}": { "get": { "operationId": "getSystemContact", "summary": "Read a system contact and its current ETag", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection.", "x-required-permission": "view-contacts", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "$ref": "#/components/parameters/ContactId" } ], "responses": { "200": { "description": "Read a system contact and its current ETag", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemContact" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateSystemContact", "summary": "Update allowlisted system contact fields", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection. If-Match is checked under locks. Omitted fields remain unchanged; null clears nullable fields.", "x-required-permission": "manage-contacts", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "$ref": "#/components/parameters/ContactId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Update allowlisted system contact fields", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemContact" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "412": { "description": "Stale state; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/SystemContactPatch" } } } } } }, "/organisations/{organisation}/systems/{system}/registers": { "get": { "operationId": "listSystemRegisterDefinitions", "summary": "Discover system-owned manual register definitions", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" } ], "responses": { "200": { "description": "Discover system-owned manual register definitions", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegisterDefinition" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/organisations/{organisation}/systems/{system}/registers/{definition}/rows": { "get": { "operationId": "listSystemRegisterRows", "summary": "List system-owned manual register rows", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "List system-owned manual register rows", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SystemRegisterRow" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createSystemRegisterRow", "summary": "Create a system-owned manual register row", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection. Creation receipts last 24 hours; exact retries replay before uniqueness checks.", "x-required-permission": "manage-registers", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Create a system-owned manual register row", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemRegisterRow" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "description": "Missing or invalid Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Key reused with a different target or canonical payload.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRowWrite" } } } } } }, "/organisations/{organisation}/systems/{system}/registers/{definition}/rows/{row}": { "get": { "operationId": "getSystemRegisterRow", "summary": "Read a system-owned row and its current ETag", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/RowId" } ], "responses": { "200": { "description": "Read a system-owned row and its current ETag", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemRegisterRow" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateSystemRegisterRow", "summary": "Merge manifest fields into a system-owned manual row", "description": "Bound organisation credential; live permissions, explicit system ownership and current account/access are checked independently of UI selection. If-Match is checked under locks. Omitted fields remain unchanged; null clears nullable fields.", "x-required-permission": "manage-registers", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/SystemId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/RowId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Merge manifest fields into a system-owned manual row", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemRegisterRow" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "412": { "description": "Stale state; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/RegisterRowWrite" } } } } } }, "/organisations/{organisation}/context": { "get": { "operationId": "getOrganisationContext", "summary": "Read canonical organisation context and its definition", "description": "Bound organisation credential; live permissions, explicit organisation binding and current account/access are checked independently of UI selection.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Read canonical organisation context and its definition", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrganisationContext" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateOrganisationContext", "summary": "Merge canonical organisation context fields", "description": "Bound organisation credential; live permissions, explicit organisation binding and current account/access are checked independently of UI selection. If-Match is checked under locks. Omitted fields remain unchanged; null clears nullable fields.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Merge canonical organisation context fields", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrganisationContext" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "412": { "description": "Stale state; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/OrganisationContextPatch" } } } } } }, "/organisations/{organisation}/registers": { "get": { "operationId": "listOrganisationRegisterDefinitions", "summary": "Discover organisation-owned manual register definitions", "description": "Bound organisation credential; live permissions, explicit organisation binding and current account/access are checked independently of UI selection.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Discover organisation-owned manual register definitions", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegisterDefinition" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/organisations/{organisation}/registers/{definition}/rows": { "get": { "operationId": "listOrganisationRegisterRows", "summary": "List organisation-owned manual register rows", "description": "Bound organisation credential; live permissions, explicit organisation binding and current account/access are checked independently of UI selection.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "name": "page[size]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "page[number]", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "List organisation-owned manual register rows", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganisationRegisterRow" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createOrganisationRegisterRow", "summary": "Create a organisation-owned manual register row", "description": "Bound organisation credential; live permissions, explicit organisation binding and current account/access are checked independently of UI selection. Creation receipts last 24 hours; exact retries replay before uniqueness checks.", "x-required-permission": "manage-registers", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Create a organisation-owned manual register row", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrganisationRegisterRow" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "description": "Missing or invalid Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Key reused with a different target or canonical payload.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRowWrite" } } } } } }, "/organisations/{organisation}/registers/{definition}/rows/{row}": { "get": { "operationId": "getOrganisationRegisterRow", "summary": "Read a organisation-owned row and its current ETag", "description": "Bound organisation credential; live permissions, explicit organisation binding and current account/access are checked independently of UI selection.", "x-required-permission": "view-registers", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/RowId" } ], "responses": { "200": { "description": "Read a organisation-owned row and its current ETag", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrganisationRegisterRow" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateOrganisationRegisterRow", "summary": "Merge manifest fields into a organisation-owned manual row", "description": "Bound organisation credential; live permissions, explicit organisation binding and current account/access are checked independently of UI selection. If-Match is checked under locks. Omitted fields remain unchanged; null clears nullable fields.", "x-required-permission": "manage-registers", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/DefinitionId" }, { "$ref": "#/components/parameters/RowId" }, { "$ref": "#/components/parameters/OperationalIfMatch" } ], "responses": { "200": { "description": "Merge manifest fields into a organisation-owned manual row", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrganisationRegisterRow" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "412": { "description": "Stale state; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/RegisterRowWrite" } } } } } }, "/organisations/{organisation}/logo": { "get": { "operationId": "getOrganisationLogo", "summary": "Read organisation logo metadata and upload status", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Read an authorised organisation identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrganisationLogo" } }, "required": [ "data" ] } } }, "headers": { "ETag": { "description": "Strong persisted-state hash; use for If-Match.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Hierarchy discovery returns bounded logo metadata and a protected API download URL for ready files. Never returns storage paths or scan internals.", "x-side-effects": "none" }, "post": { "operationId": "uploadOrganisationLogo", "summary": "Upload or replace the organisation logo", "description": "The organisation identity ability also covers logos under the same live hierarchy permission. Requires If-Match from GET /logo and Idempotency-Key. A 201 receipt means the quarantined upload was accepted; poll GET /logo for readiness. Exact file/name/type/size retries replay for 24 hours before stale If-Match checks. Initiating token/access is rechecked before release. Concurrent processing uploads are rejected; no delete/cancel API.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["organisation"], "x-side-effects": "Audited resource mutation through existing domain services.", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" }, { "$ref": "#/components/parameters/OperationalIfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Create a organisation-owned manual register row", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrganisationLogo" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } }, "headers": { "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "description": "Missing or invalid Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Key reused with a different target or canonical payload.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "412": { "description": "Stale state; read again and reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "If-Match required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OrganisationLogoUpload" } } } } } }, "/organisations/{organisation}/logo/download": { "get": { "operationId": "downloadOrganisationLogo", "summary": "Download the ready organisation logo", "description": "Only ready, scanned organisation logos. Current bound organisation access and manage-org-hierarchy are rechecked. Uses safe image headers and private no-store caching.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["organisation"], "x-side-effects": "none", "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Streamed output with private/no-store caching.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Temporary storage unavailability.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/organisations": { "get": { "operationId": "listOrganisations", "summary": "Discover authorised organisations", "description": "Administration only. Live account, selected abilities and current target access apply. Paginated (50 per page) identity discovery.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": [ "administration" ], "x-side-effects": "none", "responses": { "200": { "description": "Authorised organisation identities", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganisationIdentity" } }, "meta": { "type": "object" }, "links": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ] }, "post": { "operationId": "createOrganisation", "summary": "Create an organisation with normal bootstrap", "description": "Administration only. Requires current manage-org-hierarchy authority and manage-org-hierarchy. Active status and product-tier Members-team bootstrap are server controlled; no membership/role fields. Idempotency-Key receipts last 24 hours; payload mismatch is 409, and an expired receipt permits a new create. Licence checks and slug allocation are serialised across UI/API creation. Continue setup with an organisation-bound key issued through the authenticated UI.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": [ "administration" ], "x-side-effects": "organisation creation and normal product-tier bootstrap membership", "responses": { "201": { "description": "Created organisation or retained receipt replay", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrganisationIdentity" }, "meta": { "type": "object" }, "links": { "type": "object" } } } } }, "headers": { "ETag": { "description": "Strong ETag for the returned identity. GET again before editing after a replay.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "400": { "description": "Missing idempotency key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Payload conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid payload or organisation licence limit reached", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationCreate" } } } } } }, "/external-providers": { "get": { "operationId": "providerIndex", "summary": "index provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["administration"], "x-side-effects": "none", "parameters": [{"name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1}}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/ExternalProvider"}}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}} }, "post": { "operationId": "providerStore", "summary": "store provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Matching retries replay the original result for 24 hours; after expiry discover before creating again.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}], "responses": {"201": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ExternalProvider"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "400": {"description": "Idempotency-Key required"}, "409": {"description": "Receipt target/payload conflict"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalProviderCreate"}}}} } }, "/external-providers/options": { "get": { "operationId": "providerOptions", "summary": "options provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["administration"], "x-side-effects": "none", "parameters": [{"name": "ism_version_id", "in": "query", "schema": {"$ref": "#/components/schemas/Ulid"}, "description": "Include source-control reference discovery for this installed ISM version."}, {"name": "control_id", "in": "query", "schema": {"type": "string", "maxLength": 255}, "description": "Optional exact catalogue control identifier filter."}, {"name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1}}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderOptions"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}} } }, "/external-providers/{provider}": { "get": { "operationId": "providerShow", "summary": "show provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["administration"], "x-side-effects": "none", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ExternalProvider"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}} }, "patch": { "operationId": "providerUpdate", "summary": "update provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ExternalProvider"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}}, "requestBody": {"required": true, "content": {"application/merge-patch+json": {"schema": {"$ref": "#/components/schemas/ExternalProviderPatch"}}}} }, "delete": { "operationId": "providerDestroy", "summary": "destroy provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderDeleted"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}} } }, "/external-providers/{provider}/assurance-releases": { "get": { "operationId": "providerReleases", "summary": "releases provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["administration"], "x-side-effects": "none", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1}}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/ProviderRelease"}}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}} }, "post": { "operationId": "providerStoreRelease", "summary": "storeRelease provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Also requires current publish-provider-assurance-packages. Matching retries replay the original result for 24 hours; after expiry discover before creating again.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "responses": {"201": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderRelease"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "400": {"description": "Idempotency-Key required"}, "409": {"description": "Receipt target/payload conflict"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderReleaseCreate"}}}} } }, "/external-providers/{provider}/assurance-releases/{package}": { "get": { "operationId": "providerRelease", "summary": "release provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["administration"], "x-side-effects": "none", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "package", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderRelease"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}} }, "patch": { "operationId": "providerUpdateRelease", "summary": "updateRelease provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Also requires current publish-provider-assurance-packages.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "package", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderRelease"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}}, "requestBody": {"required": true, "content": {"application/merge-patch+json": {"schema": {"$ref": "#/components/schemas/ProviderReleasePatch"}}}} }, "delete": { "operationId": "providerDestroyRelease", "summary": "destroyRelease provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Also requires current publish-provider-assurance-packages. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "package", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderDeleted"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}} } }, "/external-providers/{provider}/assurance-releases/{package}/publish": { "post": { "operationId": "providerPublish", "summary": "publish provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Also requires current publish-provider-assurance-packages. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "publish-provider-assurance-packages", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "package", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderRelease"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderEmptyAction"}}}} } }, "/external-providers/{provider}/assurance-releases/{package}/artefacts": { "post": { "operationId": "providerStoreBulkArtefacts", "summary": "storeBulkArtefacts provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Restricted creation additionally requires upload-restricted-provider-artefacts; no arbitrary URL fetching. Upload-only callers receive a minimal receipt for restricted artefacts. Matching retries replay the original result for 24 hours; after expiry discover before creating again.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "package", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/IdempotencyKey"}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"201": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/ProviderArtefact"}}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "400": {"description": "Idempotency-Key required"}, "409": {"description": "Receipt target/payload conflict"}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}}, "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"$ref": "#/components/schemas/ProviderBulkUpload"}}}} } }, "/external-providers/{provider}/artefacts": { "get": { "operationId": "providerArtefacts", "summary": "artefacts provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["administration"], "x-side-effects": "none", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1}}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/ProviderArtefact"}}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}} }, "post": { "operationId": "providerStoreArtefact", "summary": "storeArtefact provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Restricted creation additionally requires upload-restricted-provider-artefacts; no arbitrary URL fetching. Upload-only callers receive a minimal receipt for restricted artefacts. Matching retries replay the original result for 24 hours; after expiry discover before creating again.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/IdempotencyKey"}], "responses": {"201": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderArtefact"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "400": {"description": "Idempotency-Key required"}, "409": {"description": "Receipt target/payload conflict"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderArtefactCreate"}}, "multipart/form-data": {"schema": {"$ref": "#/components/schemas/ProviderArtefactCreate"}}}} } }, "/external-providers/{provider}/artefacts/{artefact}": { "get": { "operationId": "providerArtefact", "summary": "artefact provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["administration"], "x-side-effects": "none", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "artefact", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderArtefact"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}} }, "delete": { "operationId": "providerDestroyArtefact", "summary": "destroyArtefact provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "artefact", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderDeleted"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}} } }, "/external-providers/{provider}/artefacts/{artefact}/file": { "get": { "operationId": "providerFile", "summary": "file provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["administration"], "x-side-effects": "none", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "artefact", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}], "responses": {"200": {"description": "Ready protected file; no external URL fetch", "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}} } }, "/external-providers/{provider}/artefacts/{artefact}/import": { "post": { "operationId": "providerImport", "summary": "import provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "artefact", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"202": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderArtefact"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderImport"}}}} } }, "/external-providers/{provider}/artefacts/{artefact}/use-as-ccm": { "post": { "operationId": "providerUseAsCcm", "summary": "useAsCcm provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "artefact", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"202": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderArtefact"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderImport"}}}} } }, "/external-providers/{provider}/artefacts/{artefact}/assertions": { "get": { "operationId": "providerAssertions", "summary": "assertions provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "manage-org-hierarchy", "x-execution-mode": "read-only-compatible", "x-token-types": ["administration"], "x-side-effects": "none", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "artefact", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1}}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/ProviderAssertion"}}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}} } }, "/external-providers/{provider}/artefacts/{artefact}/assertions/confirm-exact": { "post": { "operationId": "providerConfirmExact", "summary": "confirmExact provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Also requires current publish-provider-assurance-packages. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "publish-provider-assurance-packages", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "artefact", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderExactReview"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderEmptyAction"}}}} } }, "/external-providers/{provider}/artefacts/{artefact}/assertions/{assertion}/confirm": { "post": { "operationId": "providerConfirmAssertion", "summary": "confirmAssertion provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Also requires current publish-provider-assurance-packages. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "publish-provider-assurance-packages", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "artefact", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "assertion", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderAssertion"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderAssertionConfirm"}}}} } }, "/external-providers/{provider}/artefacts/{artefact}/assertions/{assertion}/reject": { "post": { "operationId": "providerRejectAssertion", "summary": "rejectAssertion provider resources", "description": "Installation-owned provider operation. Requires current manage-org-hierarchy; selected UI context does not confer authority. Also requires current publish-provider-assurance-packages. Restricted artefact access additionally requires view-restricted-provider-artefacts.", "x-required-permission": "publish-provider-assurance-packages", "x-execution-mode": "mutation-enabled", "x-token-types": ["administration"], "x-side-effects": "Normal provider domain mutation; actor/token/request audit attribution.", "parameters": [{"name": "provider", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "artefact", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"name": "assertion", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}}, {"$ref": "#/components/parameters/OperationalIfMatch"}], "responses": {"200": {"description": "Successful provider operation", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/ProviderAssertion"}, "meta": {"type": "object"}, "links": {"type": "object"}}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "422": {"description": "Invalid fields, references, parser choices, workflow or dependency state."}, "412": {"description": "Stale ETag; read again"}, "428": {"description": "If-Match required"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderAssertionReject"}}}} } }, "/projects/{project}/controls/{control}/evidence/{evidence}/cancel-processing": { "post": { "operationId": "cancelControlEvidenceProcessing", "summary": "Cancel processing evidence and remove its association.", "description": "Requires selected/live view-controls and edit-control-implementation, mutation-enabled execution, editable project and normal item deletion authority (Editing control). Register evidence additionally requires selected/live view-registers; normal source boundaries and library view authority apply. Use the evidence metadata GET ETag in If-Match. No request properties are accepted. Operation locks precede credential/project/control/item/file locks; live authority, source binding, ETag and processing state are rechecked before writes. Removal preserves snapshot facts, marks assessment drift before clearing the live snapshot link, retains shared/snapshot files and never deletes a canonical register, document or Bitbucket source. Unreferenced pending uploads are durably rejected and quarantine cleanup is queued; orphan storage deletion runs after commit. Processing files referenced by another item or snapshot return 409. Cancellation accepts only processing uploaded-file evidence; other sources or ready/error files return 409. The association is retired immediately. There is no creation receipt; retries return 404. After an uncertain response, read the original item before retrying. Ordinary UI authority and response semantics are retained.", "x-required-permission": "edit-control-implementation", "x-execution-mode": "mutation-enabled", "x-token-types": [ "project" ], "x-side-effects": "association removal, assessment drift and normal deletion audit; orphan file cleanup after commit; pending upload rejection and queued quarantine cleanup", "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ControlId" }, { "name": "evidence", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Association removed. Read-back of the original item returns 404.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "cancelled" ], "properties": { "id": { "type": "string" }, "cancelled": { "type": "boolean", "const": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-conditional-permissions": { "view-registers": "Required as selected and live authority when source_kind is register." }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Sanctum personal access token", "description": "UI-issued scoped credential with selected application Permissions in abilities and an explicit read_only mode (default true). All required/conditional permissions must be selected and currently held. Retired, mixed, wildcard or unsupported grants and missing mode fail closed. Bearer credentials cannot issue credentials; type/target boundaries and expiry remain enforced." } }, "parameters": { "OperationalIfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "Exact strong ETag from latest row, library or task detail. Compared under the write lock.", "schema": { "type": "string" } }, "DefinitionId": { "name": "definition", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "RowId": { "name": "row", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "DocumentId": { "name": "document", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "TaskId": { "name": "task", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "SetupIfMatch": {"name": "If-Match", "in": "header", "required": true, "description": "Strong ETag from the latest project setup, scope, engagement, population or artefact response.", "schema": {"type": "string", "pattern": "^\"[^\"]+\"$"}}, "ProjectId": { "name": "project", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "OrganisationId": { "name": "organisation", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "SystemId": { "name": "system", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "ControlId": { "name": "control", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "Strong ETag from the latest control detail response.", "schema": { "type": "string", "pattern": "^\"[^\"]+\"$" } }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" } } ,"IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, "ContactId": { "name": "contact", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } } }, "responses": { "ControlDetail": { "description": "The refreshed control. The ETag is required by later mutations.", "headers": { "ETag": { "required": true, "schema": { "type": "string" } }, "X-Request-ID": { "schema": { "$ref": "#/components/schemas/Ulid" } }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlDetailEnvelope" } } } }, "Unauthenticated": { "description": "Bearer authentication failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "The known resource or operation is not permitted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "The project/control combination is outside effective scope or does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "The evidence source is unavailable, not ready, unsupported, exceeds a configured limit, or needs its project Bitbucket credential configured. Missing credentials use code bitbucket_credential_not_configured; a Bitbucket 401/403 uses bitbucket_credential_invalid_or_expired. Oversized or unsupported Bitbucket JSON representations include links.download, an authorised download hint that does not guarantee download success. Neither response exposes credential material.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "BadGateway": { "description": "The upstream evidence provider returned an unexpected failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ServiceUnavailable": { "description": "The upstream evidence provider is temporarily unavailable or throttled.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "GatewayTimeout": { "description": "The upstream evidence provider timed out.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ValidationFailed": { "description": "One or more request properties are invalid, unknown or prohibited.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "PreconditionRequired": { "description": "If-Match was omitted. Retrieve detail and retry with its ETag.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PreconditionFailed": { "description": "The ETag is stale. Retrieve detail, reconcile, and retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UnsupportedMediaType": { "description": "Use the documented Content-Type.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TransitionUnavailable": { "description": "The transition is no longer executable or a prerequisite is missing. Retrieve detail before recovery.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "RateLimited": { "description": "Wait for Retry-After before retrying.", "headers": { "Retry-After": { "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "ProjectInputs": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": [ "string", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "organisation": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": [ "string", "null" ] } } }, "system": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": [ "string", "null" ] } } }, "classification": { "type": [ "string", "null" ] }, "ism_version": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": [ "string", "null" ] } } }, "project_status": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "essential_eight_target_maturity": { "type": [ "string", "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "assessment_scope_artefacts": { "type": "object", "description": "Assessment artefacts with ready diagram URLs authorised for this credential type. File retrieval requires selected/live view-projects and bound project access." }, "health": { "$ref": "#/components/schemas/ProjectHealth" } }, "required": [ "id", "organisation", "system", "archived" ] }, "ProjectContext": { "type": "object", "additionalProperties": false, "properties": { "organisation": { "type": "object", "description": "Normalised canonical organisation context fields; not organisation identity or administrative metadata." }, "system": { "type": "object", "description": "Normalised canonical system context fields." }, "source": { "type": "string", "enum": [ "canonical", "empty" ] } }, "required": [ "organisation", "system", "source" ] }, "OperationalScope": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "assessment_type": { "type": "string", "enum": [ "self_assessed", "internally_validated", "independently_assessed", "not_assessed" ] }, "assessment_boundary_summary": { "type": [ "string", "null" ] }, "scope_version": { "type": "integer" }, "data": { "oneOf": [ { "type": "object", "properties": { "environments_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "operating_systems_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "identity_services_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "cloud_services_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "communications_infrastructure_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "physical_infrastructure_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "media_handling_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "software_development_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "user_populations_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "locations_in_scope": { "type": "array", "items": { "type": "string", "maxLength": 100 } }, "components_in_scope": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 255 } }, "interconnections_in_scope": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 255 } }, "backup_logging_services_in_scope": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 255 } }, "remote_access_in_scope": { "type": "boolean" }, "explicit_exclusions_reviewed": { "type": "boolean" }, "explicit_exclusions": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": [ "string", "null" ], "maxLength": 100 }, "component": { "type": [ "string", "null" ], "maxLength": 255 }, "reason": { "type": [ "string", "null" ], "maxLength": 1000 }, "risk_accepted_by": { "type": [ "string", "null" ], "maxLength": 255 }, "review_due_date": { "type": [ "string", "null" ], "format": "date" } } } }, "supplier_dependencies": { "type": "array", "items": { "type": "object", "properties": { "supplier": { "type": [ "string", "null" ], "maxLength": 255 }, "service": { "type": [ "string", "null" ], "maxLength": 255 }, "included": { "type": "boolean" }, "assurance_required": { "type": [ "string", "null" ], "maxLength": 1000 }, "review_due_date": { "type": [ "string", "null" ], "format": "date" } } } }, "assumptions": { "type": "array", "items": { "type": [ "string", "null" ], "maxLength": 1000 } }, "notes": { "type": [ "string", "null" ], "maxLength": 5000 } } }, { "type": "array", "maxItems": 0 } ] }, "last_reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_due_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "OperationalEngagement": { "type": "object", "additionalProperties": false, "properties": { "assessor_name": { "type": [ "string", "null" ] }, "assessor_registration_number": { "type": [ "string", "null" ] }, "assessor_organisation": { "type": [ "string", "null" ] }, "assessment_report_number": { "type": [ "string", "null" ] }, "assessment_start_date": { "type": [ "string", "null" ], "format": "date" }, "assessment_end_date": { "type": [ "string", "null" ], "format": "date" } } }, "ProjectContact": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "organisation": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone_number": { "type": [ "string", "null" ] }, "phone_formatted": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "RegisterColumn": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "text", "integer", "decimal", "boolean", "date", "datetime", "enum", "enum_multi", "tags", "contact", "contact_multi", "relation_single", "relation_multi" ] }, "required": { "type": "boolean" }, "label": { "type": "string" }, "enum": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } } } } }, "relation": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "controls", "documents" ] } } } }, "description": "Manifest metadata. Use only documented column IDs and enum value IDs. Other configuration is discovery-only." }, "RegisterDefinition": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "key": { "type": "string" }, "title": { "type": "string" }, "canonical_scope": { "type": "string", "enum": [ "project", "system", "organisation" ] }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/RegisterColumn" } }, "writable": { "type": "boolean" } }, "required": [ "id", "key", "canonical_scope", "columns", "writable" ] }, "ControlEvidenceReplacement": { "type": "object", "additionalProperties": false, "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Normal control-evidence allowed file types; maximum 20 MiB." }, "description": { "type": [ "string", "null" ], "maxLength": 5000, "description": "Omission/null preserves the old description; metadata PATCH supports clearing." } } }, "ControlEvidenceMetadata": { "type": "object", "additionalProperties": false, "required": [ "id", "control_id", "source_kind", "title", "description", "evidence_type", "classification", "source_system", "external_reference", "external_access_instructions", "collected_on", "review_due", "updated_at" ], "properties": { "id": { "type": "string" }, "control_id": { "type": "string" }, "source_kind": { "type": "string", "enum": [ "text_reference", "external_reference", "uploaded_file", "register", "library_document", "bitbucket_file" ] }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "evidence_type": { "type": [ "string", "null" ], "maxLength": 64 }, "classification": { "type": [ "string", "null" ], "maxLength": 64 }, "source_system": { "type": [ "string", "null" ], "maxLength": 255 }, "external_reference": { "type": [ "string", "null" ], "maxLength": 2048 }, "external_access_instructions": { "type": [ "string", "null" ], "maxLength": 5000 }, "collected_on": { "type": [ "string", "null" ], "format": "date" }, "review_due": { "type": [ "string", "null" ], "format": "date" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ControlEvidenceMetadataPatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "evidence_type": { "type": [ "string", "null" ], "maxLength": 64 }, "classification": { "type": [ "string", "null" ], "maxLength": 64 }, "source_system": { "type": [ "string", "null" ], "maxLength": 255 }, "external_reference": { "type": [ "string", "null" ], "maxLength": 2048 }, "external_access_instructions": { "type": [ "string", "null" ], "maxLength": 5000 }, "collected_on": { "type": [ "string", "null" ], "format": "date" }, "review_due": { "type": [ "string", "null" ], "format": "date" } } }, "RegisterReview": { "type": "object", "additionalProperties": false, "required": [ "id", "project_id", "register_reference_id", "reviewed_at", "reviewed_by", "notes" ], "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "register_reference_id": { "type": "string" }, "reviewed_at": { "type": "string", "format": "date-time" }, "reviewed_by": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ], "maxLength": 5000 } } }, "RegisterReviewCreate": { "type": "object", "additionalProperties": false, "properties": { "notes": { "type": [ "string", "null" ], "maxLength": 5000 } } }, "RegisterRow": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "definition_id": { "$ref": "#/components/schemas/Ulid" }, "owner_scope": { "type": "string", "enum": [ "project", "system", "organisation" ] }, "data": { "type": "object", "description": "Manifest values. Source references require their source read ability and live permission; unavailable/foreign references are omitted or filtered." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "redacted_fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "definition_id", "owner_scope", "data", "redacted_fields" ] }, "RegisterRowWrite": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "minProperties": 1, "maxProperties": 100, "description": "Only manifest columns. Required columns, declared types/enums and logical-key uniqueness apply. Contact IDs must be active in the project's system. Control references are same-project ULIDs or control reference codes. Document references are template keys in /documents. Arrays max 100; string max 255; text max 65535. Omitted PATCH columns are preserved; null clears nullable columns." } }, "required": [ "data" ] }, "LibraryPatch": { "type": "object", "additionalProperties": false, "properties": { "content_markdown": { "type": [ "string", "null" ], "maxLength": 500000 }, "owner_user_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "classification": { "type": [ "string", "null" ], "enum": [ "NC", "OS", "P", "S", "TS", null ] }, "date_live": { "type": [ "string", "null" ], "format": "date" }, "review_due": { "type": [ "string", "null" ], "format": "date" } } }, "ProjectLibrary": { "type": "object", "additionalProperties": false, "properties": { "definition_id": { "$ref": "#/components/schemas/Ulid" }, "key": { "type": "string" }, "title": { "type": "string" }, "instructions": { "type": [ "string", "null" ] }, "instruction_version": { "type": "integer" }, "id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "content_markdown": { "type": "string" }, "owner_user_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "classification": { "type": [ "string", "null" ] }, "date_live": { "type": [ "string", "null" ], "format": "date" }, "review_due": { "type": [ "string", "null" ], "format": "date" }, "content_hash": { "type": "string" }, "has_unversioned_changes": { "type": "boolean" }, "last_versioned_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProjectDocument": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "document_key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "empty", "generating", "error", "draft", "final" ] }, "version": { "type": "integer" }, "mime_type": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "checksum": { "type": [ "string", "null" ] }, "date_generated": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "dependencies": { "type": "object", "description": "Normal document dependency evaluation: can_generate and current prerequisites. Final generation re-evaluates with final-document rules." } } }, "DocumentCatalogueEntry": { "type": "object", "additionalProperties": false, "properties": { "document_key": { "type": "string" }, "title": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/ProjectDocument" }, { "type": "null" } ] } } }, "DocumentGeneration": { "type": "object", "additionalProperties": false, "properties": { "generation_options": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "draft_watermark": { "type": [ "boolean", "null" ], "default": true }, "show_implementation_notes": { "type": [ "boolean", "null" ] }, "show_assessor_notes": { "type": [ "boolean", "null" ] } } }, "approval_confirmed": { "type": [ "boolean", "null" ], "description": "Must be true when draft_watermark is false. SecBoost creates the approval snapshot; callers cannot supply approver or maturity overrides." } } }, "ProjectTask": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": [ "integer", "string", "null" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "assigned_to_user_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "assigned_to_team_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "related_control_id": { "anyOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ], "description": "Omitted without view-controls and live view-controls." } } }, "TaskComment": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "comment": { "type": "string" }, "user_id": { "$ref": "#/components/schemas/Ulid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TaskCommentWrite": { "type": "object", "additionalProperties": false, "properties": { "comment": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "comment" ] }, "EmptyTaskAction": { "type": "object", "additionalProperties": false, "properties": {} }, "DocumentTemplateGeneration": { "type": "object", "additionalProperties": false, "properties": { "generation_options": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "draft_watermark": { "type": [ "boolean", "null" ], "default": true }, "show_implementation_notes": { "type": [ "boolean", "null" ] }, "show_assessor_notes": { "type": [ "boolean", "null" ] } } }, "approval_confirmed": { "type": [ "boolean", "null" ], "description": "Must be true when draft_watermark is false. SecBoost creates the approval snapshot; callers cannot supply approver or maturity overrides." }, "document_key": { "type": "string", "maxLength": 255, "description": "Template document_key from GET /documents, not output row ULID." } }, "required": [ "document_key" ] }, "Ulid": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "ProjectSetupCreate": { "type": "object", "additionalProperties": false, "required": ["name", "classification_level", "ism_version_id", "authorising_officer", "system_owner", "ciso", "system_manager", "itsa"], "properties": { "name": { "type": "string", "maxLength": 255 }, "classification_level": { "type": "string" }, "ism_version_id": { "$ref": "#/components/schemas/Ulid" }, "authorising_officer": { "type": "string" }, "system_owner": { "type": "string" }, "ciso": { "type": "string" }, "system_manager": { "type": "string" }, "itsa": { "type": "string" }, "e8_target_maturity_level": { "type": ["string", "null"], "enum": ["ML1", "ML2", "ML3", null] } } }, "ProjectSetupPatch": {"type": "object", "additionalProperties": false, "required": [], "properties": {"name": {"type": "string", "maxLength": 255}, "authorising_officer": {"type": "string", "maxLength": 255}, "system_owner": {"type": "string", "maxLength": 255}, "ciso": {"type": "string", "maxLength": 255}, "system_manager": {"type": "string", "maxLength": 255}, "itsa": {"type": "string", "maxLength": 255}, "e8_target_maturity_level": {"type": ["string", "null"], "enum": ["ML1", "ML2", "ML3", null]}, "project_edit_reason": {"type": ["string", "null"], "maxLength": 1000}}, "description": "Only these setup fields are writable. A project_edit_reason is required when changing e8_target_maturity_level. Omitted fields are preserved."}, "ProjectScopeUpdate": {"type": "object", "properties": {"assessment_type": {"type": "string", "enum": ["self_assessed", "internally_validated", "independently_assessed", "not_assessed"]}, "assessment_boundary_summary": {"type": ["string", "null"], "maxLength": 5000}, "last_reviewed_at": {"type": ["string", "null"], "format": "date"}, "review_due_at": {"type": ["string", "null"], "format": "date"}, "edit_reason": {"type": "string", "minLength": 5, "maxLength": 1000}, "data": {"oneOf": [{"type": "object", "properties": {"environments_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "operating_systems_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "identity_services_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "cloud_services_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "communications_infrastructure_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "physical_infrastructure_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "media_handling_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "software_development_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "user_populations_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "locations_in_scope": {"type": "array", "items": {"type": "string", "maxLength": 100}}, "components_in_scope": {"type": "array", "items": {"type": ["string", "null"], "maxLength": 255}}, "interconnections_in_scope": {"type": "array", "items": {"type": ["string", "null"], "maxLength": 255}}, "backup_logging_services_in_scope": {"type": "array", "items": {"type": ["string", "null"], "maxLength": 255}}, "remote_access_in_scope": {"type": "boolean"}, "explicit_exclusions_reviewed": {"type": "boolean"}, "explicit_exclusions": {"type": "array", "items": {"type": "object", "properties": {"category": {"type": ["string", "null"], "maxLength": 100}, "component": {"type": ["string", "null"], "maxLength": 255}, "reason": {"type": ["string", "null"], "maxLength": 1000}, "risk_accepted_by": {"type": ["string", "null"], "maxLength": 255}, "risk_acceptance_date": {"type": ["string", "null"], "format": "date"}}}}, "supplier_dependencies": {"type": "array", "items": {"type": "object", "properties": {"supplier": {"type": ["string", "null"], "maxLength": 255}, "service": {"type": ["string", "null"], "maxLength": 255}, "included": {"type": "boolean"}, "assurance_required": {"type": ["string", "null"], "maxLength": 1000}, "review_due_date": {"type": ["string", "null"], "format": "date"}}}}, "assumptions": {"type": "array", "items": {"type": ["string", "null"], "maxLength": 1000}}, "notes": {"type": ["string", "null"], "maxLength": 5000}}}, {"type": "array", "maxItems": 0}]}, "provider_assurance_selections": {"type": "array", "items": {"type": "object", "properties": {"assurance_package_id": {"$ref": "#/components/schemas/Ulid"}, "services": {"type": "array", "items": {"type": "string", "maxLength": 255}, "minItems": 1}, "regions": {"type": "array", "items": {"type": "string", "maxLength": 255}, "minItems": 1}, "account_references": {"type": "array", "items": {"type": "string", "maxLength": 255}}, "qualifications": {"type": ["object", "array"]}}, "required": ["assurance_package_id", "services", "regions"]}}}, "required": ["assessment_type", "edit_reason", "data"], "description": "Uses the existing scope-save rules: data replaces the scope data, not a sparse nested merge. Omitted provider_assurance_selections preserves the current selection; [] clears it. Obtain permitted choices from setup-options."}, "ProjectEngagementUpdate": {"type": "object", "properties": {"irap_assessment_engagement": {"type": "object", "properties": {"assessor_name": {"type": ["string", "null"], "maxLength": 255}, "assessor_registration_number": {"type": ["string", "null"], "maxLength": 100}, "assessor_organisation": {"type": ["string", "null"], "maxLength": 255}, "assessment_report_number": {"type": ["string", "null"], "maxLength": 100}, "assessment_start_date": {"type": ["string", "null"], "format": "date"}, "assessment_end_date": {"type": ["string", "null"], "format": "date"}}}}, "required": ["irap_assessment_engagement"], "description": "Replaces engagement details. End date must be on or after start date. Null and blank fields are removed."}, "ProjectNarrativeUpdate": {"type": "object", "properties": {"content": {"type": ["string", "null"], "maxLength": 100000}}, "required": ["content"], "additionalProperties": false}, "ProjectDiagramUpload": {"type": "object", "properties": {"file": {"type": "string", "format": "binary", "description": "PNG, JPEG or WebP, maximum 10 MiB. The upload uses the existing secure ingestion pipeline."}}, "required": ["file"]}, "ProjectSetup": {"type": "object", "properties": {"health": {"$ref": "#/components/schemas/ProjectHealth"}, "name": {"type": ["string", "null"], "maxLength": 255}, "project_code": {"type": ["string", "null"], "maxLength": 255}, "classification_level": {"type": ["string", "null"], "maxLength": 255}, "authorising_officer": {"type": ["string", "null"], "maxLength": 255}, "system_owner": {"type": ["string", "null"], "maxLength": 255}, "ciso": {"type": ["string", "null"], "maxLength": 255}, "system_manager": {"type": ["string", "null"], "maxLength": 255}, "itsa": {"type": ["string", "null"], "maxLength": 255}, "e8_target_maturity_level": {"type": ["string", "null"], "maxLength": 255}, "project_status": {"type": ["string", "null"], "maxLength": 255}, "id": {"$ref": "#/components/schemas/Ulid"}, "organisation_id": {"$ref": "#/components/schemas/Ulid"}, "system_id": {"$ref": "#/components/schemas/Ulid"}, "ism_version_id": {"$ref": "#/components/schemas/Ulid"}, "assessment_scope_profile": {"type": ["object", "null"]}, "readiness": {"type": "object", "properties": {"status": {"type": "string", "maxLength": 255}, "can_create_matrix": {"type": "boolean"}, "missing_blocking_facts": {"type": "array", "items": {"type": "object"}}, "warnings": {"type": "array", "items": {"type": "object"}}, "counts": {"type": "object"}}}, "provider_assurance_selections": {"type": "array", "items": {"type": "object", "properties": {"assurance_package_id": {"$ref": "#/components/schemas/Ulid"}, "services": {"type": "array", "items": {"type": "string", "maxLength": 255}, "minItems": 1}, "regions": {"type": "array", "items": {"type": "string", "maxLength": 255}, "minItems": 1}, "account_references": {"type": "array", "items": {"type": "string", "maxLength": 255}}, "qualifications": {"type": ["object", "array"]}}, "required": ["assurance_package_id", "services", "regions"]}}, "assessment_scope_artefacts": {"type": "object", "description": "Assessment artefacts with ready diagram URLs authorised for this credential type. File retrieval requires selected/live view-projects and bound project access."}}, "required": ["id", "name", "assessment_scope_profile", "health"], "description": "Project identity and shared permission-redacted health. readiness and provider_assurance_selections are present only with selected and live setup authority; assessment_scope_profile is null without it."}, "ProjectSetupOptions": {"type": "object", "properties": {"ism_versions": {"type": "array", "items": {"type": "object", "properties": {"id": {"$ref": "#/components/schemas/Ulid"}, "name": {"type": "string", "maxLength": 255}, "label": {"type": ["string", "null"], "maxLength": 255}}}}, "classifications": {"type": "array", "items": {"type": "string", "maxLength": 255}}, "e8_target_maturity_levels": {"type": "array", "items": {"type": "string", "maxLength": 255}}, "scope_options": {"type": "object"}, "provider_geographies": {"type": "array", "items": {"type": "object"}}, "provider_assurance_releases": {"type": "array", "items": {"type": "object", "properties": {"id": {"$ref": "#/components/schemas/Ulid"}, "provider_name": {"type": ["string", "null"], "maxLength": 255}, "title": {"type": "string", "maxLength": 255}, "offering_name": {"type": ["string", "null"], "maxLength": 255}, "services": {"type": "array", "items": {"type": "string", "maxLength": 255}}, "regions": {"type": "array", "items": {"type": "string", "maxLength": 255}}, "source_ism_version_id": {"$ref": "#/components/schemas/Ulid"}}}}}}, "ProjectPopulationStatus": {"type": "object", "properties": {"project_id": {"$ref": "#/components/schemas/Ulid"}, "status": {"type": ["string", "null"], "maxLength": 255}, "phase": {"type": ["string", "null"], "maxLength": 255}, "total_controls": {"type": "integer"}, "processed_controls": {"type": "integer"}}}, "WorkflowState": { "type": "string", "enum": ["New", "Editing", "Approving Edit", "Ready for Assessment", "Assessing", "Approving Assessment", "Assessed"] }, "Applicability": { "type": "string", "enum": ["ec", "n", "y"] }, "UserApplicability": { "type": "string", "enum": ["n", "y"], "description": "A user-selectable applicability decision. Classification exclusion (ec) is server-owned." }, "ImplementationStatus": { "type": "string", "enum": ["Not Assessed", "Effective", "Alternate Control", "Common Control", "Ineffective", "No Visibility", "Not Implemented", "Not Applicable"] }, "AssessedImplementationStatus": { "type": "string", "enum": ["Not Assessed", "Effective", "Alternate Control", "Ineffective", "No Visibility", "Not Implemented", "Not Applicable"] }, "SspAssessedImplementationStatus": { "type": "string", "enum": ["Not Assessed", "Effective", "Alternate Control", "Common Control", "Ineffective", "No Visibility", "Not Implemented", "Not Applicable"] }, "SspResponsibility": { "type": ["string", "null"], "enum": ["not_assessed", "board_of_directors_or_executive_committee", "chief_information_security_officer", "system_owner", "system_manager", "internal_service_provider", "outsourced_service_provider", "shared_responsibility", "not_applicable", null] }, "FindingSeverity": { "type": "string", "enum": ["Critical", "High", "Medium", "Low", "Informational", "Not Assessed"] }, "ConsumerRequirement": { "type": ["string", "null"], "enum": ["not_assessed", "yes", "no", "not_possible", "not_applicable", null] }, "ProviderGuidanceWarning": { "type": "object", "additionalProperties": false, "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "ProviderGuidanceScope": { "type": "object", "additionalProperties": false, "required": ["id", "revision", "services", "regions", "accounts", "qualifications"], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "revision": { "type": "integer", "minimum": 1 }, "checksum": { "type": ["string", "null"] }, "services": { "type": "array", "items": { "type": "string" } }, "regions": { "type": "array", "items": { "type": "string" } }, "accounts": { "type": "array", "items": { "type": "string" } }, "qualifications": { "type": "array", "items": { "type": "string" } } } }, "ProviderGuidanceAssertion": { "type": "object", "additionalProperties": false, "required": ["id", "checksum", "provider_name", "package_id", "package_title", "package_recommended_review_at", "package_review_overdue", "source_ism_version", "source_identifier", "source_sheet", "source_row", "coverage_classification", "upstream_provider_responsibility", "upstream_provider_implementation_status", "upstream_provider_comments", "upstream_consumer_responsibility", "upstream_consumer_implementation_required", "upstream_consumer_configuration_required", "upstream_consumer_comments", "evidence_references", "assessment_references"], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "checksum": { "type": ["string", "null"] }, "provider_name": { "type": ["string", "null"] }, "package_id": { "$ref": "#/components/schemas/Ulid" }, "package_title": { "type": "string" }, "package_checksum": { "type": ["string", "null"] }, "package_recommended_review_at": { "type": ["string", "null"], "format": "date" }, "package_review_overdue": { "type": "boolean" }, "source_ism_version": { "oneOf": [{ "$ref": "#/components/schemas/IdentifierName" }, { "type": "null" }] }, "source_identifier": { "type": "string" }, "source_sheet": { "type": "string" }, "source_row": { "type": "integer", "minimum": 1 }, "coverage_classification": { "type": ["string", "null"] }, "upstream_provider_responsibility": { "type": ["string", "null"] }, "upstream_provider_implementation_status": { "type": ["string", "null"] }, "upstream_provider_comments": { "type": ["string", "null"] }, "upstream_consumer_responsibility": { "type": ["string", "null"] }, "upstream_consumer_implementation_required": { "type": ["string", "null"] }, "upstream_consumer_configuration_required": { "type": ["string", "null"] }, "upstream_consumer_comments": { "type": ["string", "null"] }, "evidence_references": { "type": "array" }, "assessment_references": { "type": "array" } } }, "ProviderGuidance": { "type": "object", "additionalProperties": false, "required": ["guidance_id", "currently_available", "availability_reason_codes", "warnings", "scope", "provider_assertion"], "properties": { "guidance_id": { "type": "string" }, "currently_available": { "type": "boolean" }, "availability_reason_codes": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderGuidanceWarning" } }, "scope": { "$ref": "#/components/schemas/ProviderGuidanceScope" }, "provider_assertion": { "$ref": "#/components/schemas/ProviderGuidanceAssertion" } } }, "ControlEvidenceItem": { "type": "object", "additionalProperties": false, "required": ["id", "source_kind", "content_representation", "title", "description", "evidence_type", "evidence_status", "verification_status", "currency_status", "classification", "source_system", "external_reference", "external_access_instructions", "collected_on", "review_due", "sort_order", "created_at", "updated_at", "file", "register", "library_document", "bitbucket"], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "source_kind": { "type": "string", "enum": ["uploaded_file", "external_reference", "text_reference", "register", "library_document", "bitbucket_file"] }, "content_representation": { "type": "string", "enum": ["inline", "external_access", "content_endpoint", "download_endpoint", "content_and_download", "unavailable"], "description": "How to consume this evidence item: inline means read description; external_access means use external_reference and/or external_access_instructions with no SecBoost content endpoint; content_endpoint means links.content is present; download_endpoint means links.download is present; content_and_download means both links are present; unavailable means neither link is present and no inline/external representation is available." }, "title": { "type": "string" }, "description": { "type": ["string", "null"] }, "evidence_type": { "type": ["string", "null"] }, "evidence_status": { "type": ["string", "null"] }, "verification_status": { "type": ["string", "null"] }, "currency_status": { "type": ["string", "null"] }, "classification": { "type": ["string", "null"] }, "source_system": { "type": ["string", "null"] }, "external_reference": { "type": ["string", "null"] }, "external_access_instructions": { "type": ["string", "null"] }, "collected_on": { "type": ["string", "null"], "format": "date" }, "review_due": { "type": ["string", "null"], "format": "date" }, "sort_order": { "type": ["integer", "null"] }, "created_at": { "type": ["string", "null"], "format": "date-time" }, "updated_at": { "type": ["string", "null"], "format": "date-time" }, "links": { "type": "object", "additionalProperties": false, "properties": { "content": { "type": "string", "format": "uri" }, "download": { "type": "string", "format": "uri" } }, "description": "Advertised read-only evidence API links. content_endpoint has content; download_endpoint has download; content_and_download has both. inline, external_access, and unavailable have neither." }, "file": { "type": ["object", "null"] }, "register": { "type": ["object", "null"] }, "library_document": { "type": ["object", "null"] }, "bitbucket": { "type": ["object", "null"] } } }, "ControlApplicabilityContext": {"type": "object", "additionalProperties": false, "required": ["origin", "decision", "recommendation", "recommendation_is_current", "conflict", "suggested_exclusion"], "properties": {"version": {"type": "string", "description": "Opaque applicability context version for UI concurrency checks."}, "origin": {"type": "string", "enum": ["default", "recommendation", "user", "classification", "unknown"]}, "decision": {"type": ["object", "null"], "description": "Recorded decision origin and, for explicit choices, actor, rationale, time and evaluated recommendation/fact identifiers. Unknown historical provenance is not inferred from comments.", "properties": {"origin": {"type": "string"}, "applicability": {"type": "string", "enum": ["y", "n"]}, "reason": {"type": ["string", "null"]}, "user_id": {"type": ["string", "null"]}, "decided_at": {"type": "string", "format": "date-time"}, "recommendation_id": {"type": ["string", "null"]}, "source_fingerprint": {"type": ["string", "null"]}, "rule_set_id": {"type": ["string", "null"]}, "recommended_applicability": {"type": ["string", "null"]}}}, "recommendation": {"type": ["object", "null"], "properties": {"id": {"type": "string"}, "state": {"type": ["string", "null"]}, "recommended_applicability": {"type": ["string", "null"], "enum": ["y", "n", "ec", null]}, "confidence": {"type": ["string", "null"], "enum": ["weak", "moderate", "strong", null]}, "rule_set_id": {"type": ["string", "null"]}, "evaluated_at": {"type": ["string", "null"], "format": "date-time"}, "explanation": {"type": "object"}}}, "recommendation_is_current": {"type": "boolean"}, "conflict": {"type": "boolean", "description": "A current supported recommendation disagrees with stored applicability and has not been acknowledged for the same structured facts and rule set."}, "suggested_exclusion": {"type": "boolean", "description": "An unresolved supported conflict recommending n."}}}, "ProjectHealth": {"type": "object", "description": "Ongoing project health, distinct from matrix-creation readiness. Applicability counts and recalculation are omitted without selected and live view-controls authority. Health does not disclose raw context, evidence or assessment data.", "properties": {"status": {"type": "string", "enum": ["clear", "warning"]}, "summary": {"type": "string"}, "description": {"type": "string"}, "warning_count": {"type": "integer"}, "warnings": {"type": "array", "description": "Stable issue keys; warning_count counts issues, not affected controls. API issues omit UI URLs.", "items": {"type": "object", "properties": {"key": {"type": "string"}, "category": {"type": "string"}, "label": {"type": "string"}, "message": {"type": "string"}, "severity": {"type": "string"}, "action_label": {"type": "string"}}}}, "applicability_summary": {"type": "object", "properties": {"total_controls": {"type": "integer", "minimum": 0}, "not_applicable": {"type": "integer", "minimum": 0}, "excluded_by_classification": {"type": "integer", "minimum": 0}, "review_required": {"type": "integer", "minimum": 0}, "default_included": {"type": "integer", "minimum": 0}, "stale_recommendations": {"type": "integer", "minimum": 0}, "applicable": {"type": "integer", "minimum": 0, "description": "All controls with applicability y, including controls with unresolved supported conflicts. Do not add review_required to applicability totals."}}, "description": "applicable/not_applicable/excluded_by_classification totals are mutually exclusive. review_required is an overlapping supported-conflict count, excluding assessor/ISM review tasks."}, "recalculation": {"type": "object", "properties": {"id": {"type": ["string", "null"]}, "status": {"type": "string", "enum": ["not_run", "queued", "running", "completed", "failed", "cancelled"]}, "completed_at": {"type": ["string", "null"], "format": "date-time"}, "failed": {"type": "boolean"}, "processed_controls": {"type": "integer", "minimum": 0, "description": "Distinct controls evaluated for this project in the latest run."}, "total_controls": {"type": "integer", "minimum": 0, "description": "Current project controls eligible for evaluation."}}, "description": "Latest relevant run. Inspect stale_recommendations too: a completed run does not prove that every latest recommendation matches current facts."}}}, "Project": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "project_code", "organisation", "system", "classification", "ism_version", "project_status", "health", "archived", "essential_eight_target_maturity", "created_at", "updated_at" ], "properties": { "health": { "$ref": "#/components/schemas/ProjectHealth" }, "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string" }, "project_code": { "type": [ "string", "null" ] }, "organisation": { "$ref": "#/components/schemas/IdentifierName" }, "system": { "$ref": "#/components/schemas/IdentifierName" }, "classification": { "type": "string", "enum": [ "NC", "OS", "P", "S", "TS" ] }, "ism_version": { "$ref": "#/components/schemas/IdentifierName" }, "project_status": { "type": "string", "enum": [ "Setup", "Initialising", "Draft", "Final" ] }, "archived": { "type": "boolean" }, "essential_eight_target_maturity": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "assessment_scope_artefacts": { "type": "object", "description": "Assessment artefacts with ready diagram URLs authorised for this credential type. File retrieval requires selected/live view-projects and bound project access." } } }, "IdentifierName": { "type": "object", "additionalProperties": false, "required": ["id", "name"], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": ["string", "null"] } } }, "ProjectCollection": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/Project" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "RequestMeta": { "type": "object", "required": ["request_id"], "properties": { "request_id": { "$ref": "#/components/schemas/Ulid" } } }, "ControlReference": { "type": ["object", "null"], "additionalProperties": false, "required": ["id", "control_id", "title", "description", "group_path", "ism_version", "ism_revision", "ism_updated_date", "essential_eight"], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "control_id": { "type": "string" }, "title": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "group_path": { "type": "array", "items": { "type": "string" } }, "ism_version": { "oneOf": [{ "$ref": "#/components/schemas/IdentifierName" }, { "type": "null" }] }, "ism_revision": { "type": ["integer", "null"] }, "ism_updated_date": { "type": ["string", "null"], "format": "date" }, "essential_eight": { "type": "object", "additionalProperties": false, "required": ["strategy_ids", "maturity_levels"], "properties": { "strategy_ids": { "type": "array", "items": { "type": "string" } }, "maturity_levels": { "type": "array", "items": { "type": "string", "enum": ["ML1", "ML2", "ML3"] } } } } } }, "ControlList": { "type": "object", "required": ["id", "project_id", "workflow_state", "lock_version", "internal_control_owner", "applicability", "implementation_status", "date_implemented", "requires_review", "control_reference", "created_at", "updated_at"], "properties": { "applicability_context": { "$ref": "#/components/schemas/ControlApplicabilityContext" }, "id": { "$ref": "#/components/schemas/Ulid" }, "project_id": { "$ref": "#/components/schemas/Ulid" }, "workflow_state": { "$ref": "#/components/schemas/WorkflowState" }, "lock_version": { "type": "integer", "minimum": 1 }, "internal_control_owner": { "type": ["string", "null"], "maxLength": 255 }, "applicability": { "$ref": "#/components/schemas/Applicability" }, "implementation_status": { "$ref": "#/components/schemas/ImplementationStatus" }, "date_implemented": { "type": ["string", "null"], "format": "date" }, "requires_review": { "type": "boolean" }, "control_reference": { "$ref": "#/components/schemas/ControlReference" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "assessed_implementation_status": { "$ref": "#/components/schemas/AssessedImplementationStatus" }, "finding_severity": { "$ref": "#/components/schemas/FindingSeverity" }, "date_assessed": { "type": ["string", "null"], "format": "date" }, "ssp_assessed_implementation_status": { "$ref": "#/components/schemas/SspAssessedImplementationStatus" }, "ccm_assessed_implementation_status": { "$ref": "#/components/schemas/AssessedImplementationStatus" } } }, "ControlDetail": { "allOf": [ { "$ref": "#/components/schemas/ControlList" }, { "type": "object", "required": ["applicability_comment", "implementation_description", "implementation_summary", "provider_guidance", "evidence_items", "assessment_preparation_readiness", "allowed_actions", "allowed_transitions"], "properties": { "applicability_comment": { "type": ["string", "null"] }, "implementation_description": { "type": ["string", "null"] }, "implementation_summary": { "type": ["string", "null"], "maxLength": 500 }, "ssp_proposed_responsibility": { "$ref": "#/components/schemas/SspResponsibility" }, "ccm_proposed_provider_responsibility": { "type": ["string", "null"], "maxLength": 5000 }, "ccm_proposed_consumer_responsibility": { "type": ["string", "null"], "maxLength": 65535 }, "ccm_proposed_consumer_implementation_required": { "$ref": "#/components/schemas/ConsumerRequirement" }, "ccm_proposed_consumer_configuration_required": { "$ref": "#/components/schemas/ConsumerRequirement" }, "ccm_proposed_consumer_guidance": { "type": ["string", "null"], "maxLength": 65535 }, "provider_guidance": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderGuidance" }, "description": "Read-only provider assurance guidance derived from the project's confirmed provider scope. It is not an assessed-system claim or assessor conclusion." }, "evidence_items": { "type": "array", "items": { "$ref": "#/components/schemas/ControlEvidenceItem" }, "description": "Current live evidence context shown on the control screen. Linked source hashes and timestamps participate in the control ETag." }, "assessment_preparation_readiness": { "$ref": "#/components/schemas/AssessmentPreparationReadiness" }, "assessment_matrix_completeness": { "$ref": "#/components/schemas/AssessmentMatrixCompleteness", "description": "Present only with assessment-read authority. Not Assessed values count as incomplete." }, "assessed_implementation_comments": { "type": ["string", "null"] }, "remediation_recommendation": { "type": ["string", "null"] }, "ssp_assessed_responsibility": { "$ref": "#/components/schemas/SspResponsibility" }, "ssp_assessed_comments": { "type": ["string", "null"], "maxLength": 65535 }, "ccm_assessed_provider_responsibility": { "type": ["string", "null"], "maxLength": 5000 }, "ccm_assessed_provider_comments": { "type": ["string", "null"], "maxLength": 65535 }, "ccm_assessed_consumer_responsibility": { "type": ["string", "null"], "maxLength": 65535 }, "ccm_assessed_consumer_implementation_required": { "$ref": "#/components/schemas/ConsumerRequirement" }, "ccm_assessed_consumer_configuration_required": { "$ref": "#/components/schemas/ConsumerRequirement" }, "ccm_assessed_consumer_guidance": { "type": ["string", "null"], "maxLength": 65535 }, "allowed_actions": { "$ref": "#/components/schemas/AllowedActions" }, "allowed_transitions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedTransition" } } } } ] }, "AllowedActions": { "type": "object", "additionalProperties": false, "required": ["update_implementation", "update_assessment", "transition"], "properties": { "update_implementation": { "type": "boolean" }, "update_assessment": { "type": "boolean" }, "transition": { "type": "boolean" } } }, "AllowedTransition": { "type": "object", "additionalProperties": false, "required": ["id", "from_state", "to_state", "label", "comment", "evidence_warning_acknowledgement"], "properties": { "id": { "$ref": "#/components/schemas/ControlTransition" }, "from_state": { "$ref": "#/components/schemas/WorkflowState" }, "to_state": { "$ref": "#/components/schemas/WorkflowState" }, "label": { "type": "string" }, "comment": { "type": "string", "enum": ["unsupported", "required"] }, "evidence_warning_acknowledgement": { "type": "string", "enum": ["unsupported", "required_if_unverifiable"] } } }, "ControlTransition": { "type": "string", "enum": ["new_to_editing", "new_to_assessing", "editing_to_approving_edit", "editing_to_ready_for_assessment", "approving_edit_to_ready_for_assessment", "approving_edit_to_editing", "ready_for_assessment_to_editing", "ready_for_assessment_to_assessing", "assessing_to_editing", "assessing_to_approving_assessment", "assessing_to_assessed", "approving_assessment_to_assessed", "approving_assessment_to_assessing", "assessed_to_assessing"] }, "ControlCollection": { "type": "object", "additionalProperties": false, "required": ["data", "links", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ControlList" } }, "links": { "type": "object", "additionalProperties": false, "required": ["self", "next", "previous"], "properties": { "self": { "type": "string", "format": "uri" }, "next": { "type": ["string", "null"], "format": "uri" }, "previous": { "type": ["string", "null"], "format": "uri" } } }, "meta": { "type": "object", "additionalProperties": false, "required": ["request_id", "current_page", "page_size", "total"], "properties": { "request_id": { "$ref": "#/components/schemas/Ulid" }, "current_page": { "type": "integer", "minimum": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } } } }, "ControlDetailEnvelope": { "type": "object", "additionalProperties": false, "required": ["data", "meta"], "properties": { "data": { "$ref": "#/components/schemas/ControlDetail" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "ImplementationPatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "internal_control_owner": { "type": ["string", "null"], "maxLength": 255 }, "applicability": { "$ref": "#/components/schemas/UserApplicability" }, "applicability_comment": { "type": ["string", "null"], "maxLength": 65535 }, "implementation_status": { "$ref": "#/components/schemas/ImplementationStatus" }, "implementation_description": { "type": ["string", "null"], "maxLength": 65535 }, "implementation_summary": { "type": ["string", "null"], "maxLength": 500 }, "date_implemented": { "type": ["string", "null"], "format": "date" }, "ssp_proposed_responsibility": { "$ref": "#/components/schemas/SspResponsibility" }, "ccm_proposed_provider_responsibility": { "type": ["string", "null"], "maxLength": 5000 }, "ccm_proposed_consumer_responsibility": { "type": ["string", "null"], "maxLength": 65535 }, "ccm_proposed_consumer_implementation_required": { "$ref": "#/components/schemas/ConsumerRequirement" }, "ccm_proposed_consumer_configuration_required": { "$ref": "#/components/schemas/ConsumerRequirement" }, "ccm_proposed_consumer_guidance": { "type": ["string", "null"], "maxLength": 65535 } } }, "AssessmentPatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Assessment conclusions. Common Control is invalid for SSP principle rows. Ineffective, No Visibility and Not Implemented overall outcomes require a Critical, High, Medium or Low finding severity.", "properties": { "assessed_implementation_status": { "$ref": "#/components/schemas/AssessedImplementationStatus" }, "assessed_implementation_comments": { "type": ["string", "null"], "maxLength": 65535 }, "finding_severity": { "$ref": "#/components/schemas/FindingSeverity" }, "date_assessed": { "type": ["string", "null"], "format": "date" }, "remediation_recommendation": { "type": ["string", "null"], "maxLength": 65535 }, "ssp_assessed_responsibility": { "$ref": "#/components/schemas/SspResponsibility" }, "ssp_assessed_implementation_status": { "$ref": "#/components/schemas/SspAssessedImplementationStatus" }, "ssp_assessed_comments": { "type": ["string", "null"], "maxLength": 65535 }, "ccm_assessed_provider_responsibility": { "type": ["string", "null"], "maxLength": 5000 }, "ccm_assessed_implementation_status": { "$ref": "#/components/schemas/AssessedImplementationStatus" }, "ccm_assessed_provider_comments": { "type": ["string", "null"], "maxLength": 65535 }, "ccm_assessed_consumer_responsibility": { "type": ["string", "null"], "maxLength": 65535 }, "ccm_assessed_consumer_implementation_required": { "$ref": "#/components/schemas/ConsumerRequirement" }, "ccm_assessed_consumer_configuration_required": { "$ref": "#/components/schemas/ConsumerRequirement" }, "ccm_assessed_consumer_guidance": { "type": ["string", "null"], "maxLength": 65535 } } }, "AssessmentPreparationSection": { "type": "object", "additionalProperties": false, "required": ["state", "warning_codes"], "properties": { "state": { "type": "string", "enum": ["ready", "needs_input", "not_applicable"] }, "warning_codes": { "type": "array", "items": { "type": "string" } } } }, "AssessmentPreparationReadiness": { "type": "object", "additionalProperties": false, "required": ["ssp", "ccm", "warning_count"], "properties": { "ssp": { "$ref": "#/components/schemas/AssessmentPreparationSection" }, "ccm": { "$ref": "#/components/schemas/AssessmentPreparationSection" }, "warning_count": { "type": "integer", "minimum": 0 } } }, "MissingAssessmentField": { "type": "object", "additionalProperties": false, "required": ["field", "label", "matrix"], "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "matrix": { "type": "string", "enum": ["ssp", "ccm"] } } }, "AssessmentMatrixSection": { "type": "object", "additionalProperties": false, "required": ["applicable", "complete", "missing_count", "missing_fields"], "properties": { "applicable": { "type": "boolean" }, "complete": { "type": "boolean" }, "missing_count": { "type": "integer", "minimum": 0 }, "missing_fields": { "type": "array", "items": { "$ref": "#/components/schemas/MissingAssessmentField" } } } }, "AssessmentMatrixCompleteness": { "type": "object", "additionalProperties": false, "required": ["complete", "missing_count", "missing_fields", "ssp", "ccm"], "properties": { "complete": { "type": "boolean" }, "missing_count": { "type": "integer", "minimum": 0 }, "missing_fields": { "type": "array", "items": { "$ref": "#/components/schemas/MissingAssessmentField" } }, "ssp": { "$ref": "#/components/schemas/AssessmentMatrixSection" }, "ccm": { "$ref": "#/components/schemas/AssessmentMatrixSection" } } }, "TransitionRequest": { "type": "object", "additionalProperties": false, "required": ["transition"], "properties": { "transition": { "$ref": "#/components/schemas/ControlTransition" }, "comment": { "type": "string", "minLength": 1, "maxLength": 65535, "description": "Conditionally required and non-blank for the four approval/rejection decision transitions; rejected for every other transition." }, "acknowledge_evidence_warnings": { "type": "boolean", "default": false, "description": "For a transition into Assessed, confirms that unverifiable or unavailable evidence may be recorded as an acknowledged warning. Do not set automatically; inspect the evidence context first." } } }, "Problem": { "type": "object", "additionalProperties": false, "required": ["type", "title", "status", "detail", "instance", "code"], "properties": { "type": { "type": "string", "format": "uri-reference" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri-reference" }, "code": { "type": "string" } } }, "ValidationProblem": { "allOf": [{ "$ref": "#/components/schemas/Problem" }, { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["pointer", "code", "detail"], "properties": { "pointer": { "type": "string" }, "code": { "type": "string" }, "detail": { "type": "string" } } } } } }] }, "SystemCreate": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "short_code": { "type": [ "string", "null" ], "maxLength": 10 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "contact_name": { "type": [ "string", "null" ], "maxLength": 255 }, "contact_email": { "type": [ "string", "null" ], "maxLength": 255, "format": "email" }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 25 } } }, "SystemPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "short_code": { "type": [ "string", "null" ], "maxLength": 10 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "contact_name": { "type": [ "string", "null" ], "maxLength": 255 }, "contact_email": { "type": [ "string", "null" ], "maxLength": 255, "format": "email" }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 25 } } }, "SystemIdentity": { "type": "object", "additionalProperties": false, "required": [ "id", "organisation_id", "name", "archived" ], "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "organisation_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "short_code": { "type": [ "string", "null" ], "maxLength": 10 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "contact_name": { "type": [ "string", "null" ], "maxLength": 255 }, "contact_email": { "type": [ "string", "null" ], "maxLength": 255, "format": "email" }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 25 }, "archived": { "type": "boolean" } } }, "SystemContactCreate": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": [ "string", "null" ], "maxLength": 50 }, "role": { "type": [ "string", "null" ], "maxLength": 255 }, "organisation": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "maxLength": 255, "format": "email" }, "phone_number": { "type": [ "string", "null" ], "maxLength": 20 }, "address_street": { "type": [ "string", "null" ], "maxLength": 255 }, "address_suburb": { "type": [ "string", "null" ], "maxLength": 100 }, "address_state": { "type": [ "string", "null" ], "maxLength": 100 }, "address_postcode": { "type": [ "string", "null" ], "maxLength": 20 }, "address_country": { "type": [ "string", "null" ], "maxLength": 100 }, "notes": { "type": [ "string", "null" ], "maxLength": 65535 } } }, "SystemContactPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": [ "string", "null" ], "maxLength": 50 }, "role": { "type": [ "string", "null" ], "maxLength": 255 }, "organisation": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "maxLength": 255, "format": "email" }, "phone_number": { "type": [ "string", "null" ], "maxLength": 20 }, "address_street": { "type": [ "string", "null" ], "maxLength": 255 }, "address_suburb": { "type": [ "string", "null" ], "maxLength": 100 }, "address_state": { "type": [ "string", "null" ], "maxLength": 100 }, "address_postcode": { "type": [ "string", "null" ], "maxLength": 20 }, "address_country": { "type": [ "string", "null" ], "maxLength": 100 }, "notes": { "type": [ "string", "null" ], "maxLength": 65535 } } }, "SystemContact": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "system_id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": [ "string", "null" ], "maxLength": 50 }, "role": { "type": [ "string", "null" ], "maxLength": 255 }, "organisation": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "maxLength": 255, "format": "email" }, "phone_number": { "type": [ "string", "null" ], "maxLength": 20 }, "address_street": { "type": [ "string", "null" ], "maxLength": 255 }, "address_suburb": { "type": [ "string", "null" ], "maxLength": 100 }, "address_state": { "type": [ "string", "null" ], "maxLength": 100 }, "address_postcode": { "type": [ "string", "null" ], "maxLength": 20 }, "address_country": { "type": [ "string", "null" ], "maxLength": 100 }, "notes": { "type": [ "string", "null" ], "maxLength": 65535 } } }, "SystemContextPatch": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "hosting_model": { "type": [ "string", "null" ], "enum": [ "public_cloud_hosted", "private_cloud_hosted", "on_premises", "hybrid", "saas_only", null ] }, "cloud_providers": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "aws", "azure", "gcp", "cloudflare", "oracle", "other_cloud", "none" ] } }, "key_saas_platforms": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "m365", "google_workspace", "github", "gitlab", "bitbucket", "jira_confluence", "slack", "salesforce", "servicenow", "other_saas" ] } }, "identity_provider": { "type": [ "string", "null" ], "enum": [ "entra_id", "okta", "google_workspace", "adfs_active_directory", "other_idp", "none", null ] }, "communications_infrastructure_posture": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "none", "structured_cabling", "telephony", "video_ip_telephony", "fax_mfd", "radio_wireless", "other_communications" ] } }, "email_service_posture": { "type": [ "string", "null" ], "enum": [ "none", "external_saas_email", "managed_email_service", "self_managed_email", "hybrid_email", null ] }, "data_types_handled": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "pii", "financial", "health", "government", "source_code_ip", "credentials_secrets", "operational_data" ] } }, "internet_facing_services": { "type": [ "string", "null" ], "enum": [ "yes", "no", null ] }, "third_party_privileged_access": { "type": [ "string", "null" ], "enum": [ "yes", "no", null ] }, "criticality_tier": { "type": [ "string", "null" ], "enum": [ "supporting", "important", "mission_critical", "safety_or_regulatory", null ] }, "resilience_posture": { "type": [ "string", "null" ], "enum": [ "standard_recovery", "business_critical_recovery", "high_availability", "formal_dr_required", "safety_or_regulatory_availability", null ] }, "cryptographic_posture": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "none", "standard_platform_crypto", "managed_tls_certificates", "customer_managed_keys", "pki_certificate_authority", "hsm_or_kms", "digital_signing", "custom_crypto_implementation" ] } }, "media_handling_posture": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "none", "removable_media", "backup_media", "physical_transfer_media", "portable_storage", "media_sanitisation_disposal", "classified_or_sensitive_media" ] } }, "software_development_maturity": { "type": [ "string", "null" ], "enum": [ "no_internal_development", "ad_hoc", "structured_ci_cd", "platform_engineering", null ] }, "ai_usage_mode": { "type": [ "string", "null" ], "enum": [ "no_ai_use", "staff_use_general_tools", "ai_embedded_in_product", "self_hosted_models", "fine_tuning_or_training", null ] } }, "description": "Merge individual fields; omitted fields remain, null clears a field. Arrays replace the entire selection. GET definition supplies the current option labels and version." }, "last_reviewed_at": { "type": [ "string", "null" ], "format": "date" }, "review_due_at": { "type": [ "string", "null" ], "format": "date" }, "edit_reason": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "SystemContext": { "type": "object", "additionalProperties": false, "properties": { "system_id": { "$ref": "#/components/schemas/Ulid" }, "definition": { "type": "object", "description": "Canonical system context field definitions, option values and schema version. Yes/no fields are single_select with string options yes and no; JSON booleans are not accepted. PATCH null clears a field." }, "profile": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "data": { "oneOf": [ { "type": "object" }, { "type": "array", "maxItems": 0 } ] }, "last_reviewed_at": { "type": [ "string", "null" ], "format": "date" }, "review_due_at": { "type": [ "string", "null" ], "format": "date" }, "edit_reason": { "type": [ "string", "null" ], "maxLength": 1000 }, "reviewed_by": { "type": [ "string", "null" ] }, "profile_version": { "type": "integer" } } }, "completion": { "type": "object" } } }, "SystemRegisterRow": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "definition_id": { "$ref": "#/components/schemas/Ulid" }, "owner_scope": { "type": "string", "const": "system" }, "data": { "type": "object", "description": "Manifest values. Source references require their source read ability and live permission; unavailable/foreign references are omitted or filtered." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "redacted_fields": { "type": "array", "items": { "type": "string" } }, "system_id": { "$ref": "#/components/schemas/Ulid" } }, "required": [ "id", "definition_id", "owner_scope", "data", "redacted_fields" ] }, "OrganisationContext": { "type": "object", "additionalProperties": false, "properties": { "definition": { "type": "object", "description": "Canonical organisation context field definitions, option values and schema version. Yes/no fields are single_select with string options yes and no; JSON booleans are not accepted. PATCH null clears a field." }, "profile": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "data": { "oneOf": [ { "type": "object" }, { "type": "array", "maxItems": 0 } ] }, "last_reviewed_at": { "type": [ "string", "null" ], "format": "date" }, "review_due_at": { "type": [ "string", "null" ], "format": "date" }, "edit_reason": { "type": [ "string", "null" ], "maxLength": 1000 }, "reviewed_by": { "type": [ "string", "null" ] }, "profile_version": { "type": "integer" } } }, "completion": { "type": "object" }, "organisation_id": { "$ref": "#/components/schemas/Ulid" } } }, "OrganisationContextPatch": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "company_size_band": { "type": [ "string", "null" ], "enum": [ "micro", "small", "medium", "large", "enterprise", null ] }, "industry_sector": { "type": [ "string", "null" ], "enum": [ "technology_saas", "professional_services", "government_supplier", "financial_services", "healthcare", "education", "critical_infrastructure", "manufacturing", "retail_ecommerce", "other", null ] }, "geographic_footprint": { "type": [ "string", "null" ], "enum": [ "australia_only", "anz", "apac", "global", null ] }, "regulated_customer_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "government", "defence", "healthcare", "financial_services", "critical_infrastructure", "education" ] } }, "internal_security_capability": { "type": [ "string", "null" ], "enum": [ "none_dedicated", "shared_it_function", "small_security_team", "mature_security_function", null ] }, "incident_response_maturity": { "type": [ "string", "null" ], "enum": [ "basic_it_support", "documented_process", "formal_incident_response_plan", "dedicated_security_response", "soc_or_mssp_supported", null ] }, "incident_reporting_obligations": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "none", "internal_only", "customer_contractual", "regulatory", "government_reporting", "privacy_breach_reporting" ] } }, "it_equipment_lifecycle_governance": { "type": [ "string", "null" ], "enum": [ "mostly_vendor_managed", "informal", "asset_register_only", "formal_lifecycle_process", "secure_disposal_and_sanitisation", null ] }, "remote_workforce_percentage": { "type": [ "string", "null" ], "enum": [ "none", "minority", "mixed", "mostly_remote", null ] }, "additional_frameworks": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "iso_27001", "soc_2", "essential_eight", "nist_csf", "cps_234", "pci_dss", "privacy_act_apps", "disp" ] } }, "change_management_maturity": { "type": [ "string", "null" ], "enum": [ "informal", "ticketed", "risk_based", "fully_integrated", null ] }, "outsourced_delivery": { "type": [ "string", "null" ], "enum": [ "yes", "no", null ] } }, "description": "Merge individual fields; omitted fields remain, null clears a field. Arrays replace the entire selection. GET definition supplies the current option labels and version." }, "last_reviewed_at": { "type": [ "string", "null" ], "format": "date" }, "review_due_at": { "type": [ "string", "null" ], "format": "date" }, "edit_reason": { "type": [ "string", "null" ], "maxLength": 1000 } }, "description": "Merge individual organisation context fields using the definition returned by GET. Omitted fields remain; null clears nullable fields. data:null is rejected." }, "OrganisationRegisterRow": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "definition_id": { "$ref": "#/components/schemas/Ulid" }, "owner_scope": { "type": "string", "const": "organisation" }, "data": { "type": "object", "description": "Manifest values. Source references require their source read ability and live permission; unavailable/foreign references are omitted or filtered." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "redacted_fields": { "type": "array", "items": { "type": "string" } }, "organisation_id": { "$ref": "#/components/schemas/Ulid" } }, "required": [ "id", "definition_id", "owner_scope", "data", "redacted_fields" ], "description": "Organisation-owned manual register row. Contact, control and document reference fields are always redacted; new selections are rejected." }, "OrganisationCreate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": [ "string", "null" ], "maxLength": 255, "description": "Normalised using the existing UI slug allocator. Null regenerates from the current or supplied name." }, "timezone": { "type": "string", "description": "IANA timezone identifier." }, "primary_contact_name": { "type": [ "string", "null" ], "maxLength": 255 }, "primary_contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "primary_contact_phone": { "type": [ "string", "null" ], "maxLength": 50 }, "notes": { "type": [ "string", "null" ], "maxLength": 65535 } }, "required": [ "name", "timezone" ] }, "OrganisationPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": [ "string", "null" ], "maxLength": 255, "description": "Normalised using the existing UI slug allocator. Null regenerates from the current or supplied name." }, "timezone": { "type": "string", "description": "IANA timezone identifier." }, "primary_contact_name": { "type": [ "string", "null" ], "maxLength": 255 }, "primary_contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "primary_contact_phone": { "type": [ "string", "null" ], "maxLength": 50 }, "notes": { "type": [ "string", "null" ], "maxLength": 65535 } } }, "OrganisationIdentity": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Ulid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "maxLength": 255, "description": "Normalised using the existing UI slug allocator. Null regenerates from the current or supplied name." }, "timezone": { "type": "string", "description": "IANA timezone identifier." }, "primary_contact_name": { "type": [ "string", "null" ], "maxLength": 255 }, "primary_contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "primary_contact_phone": { "type": [ "string", "null" ], "maxLength": 50 }, "notes": { "type": [ "string", "null" ], "maxLength": 65535 }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] } }, "required": [ "id", "name", "slug", "timezone", "status" ] }, "OrganisationLogo": { "type": "object", "required": [ "organisation_id", "logo" ], "properties": { "organisation_id": { "$ref": "#/components/schemas/Ulid" }, "logo": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "url": { "type": [ "string", "null" ] }, "original_filename": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "checksum": { "type": [ "string", "null" ] }, "checksum_algorithm": { "type": [ "string", "null" ] }, "uploaded_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "uploaded_by": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "dimensions": { "type": [ "object", "null" ] }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "processing", "error", "ready" ] }, "processing": { "type": "boolean" }, "error": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "type": { "type": "string" } } } } } } }, "OrganisationLogoUpload": { "type": "object", "additionalProperties": false, "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "JPEG, PNG, GIF or WebP; maximum 10 MB. Quarantined, scanned and content-validated before release." } } }, "ExternalProviderCreate": { "type": "object", "additionalProperties": false, "properties": {"name": {"type": "string", "maxLength": 255}, "provider_type": {"type": "string", "enum": ["cloud_provider", "saas_provider", "managed_service_provider", "data_centre_provider", "other_supplier"]}, "status": {"type": "string", "enum": ["active", "inactive"]}}, "required": ["name", "provider_type"] }, "ExternalProviderPatch": { "type": "object", "additionalProperties": false, "properties": {"name": {"type": "string", "maxLength": 255}, "provider_type": {"type": "string", "enum": ["cloud_provider", "saas_provider", "managed_service_provider", "data_centre_provider", "other_supplier"]}, "status": {"type": "string", "enum": ["active", "inactive"]}} }, "ExternalProvider": { "type": "object", "additionalProperties": false, "properties": {"id": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}, "provider_key": {"type": "string"}, "name": {"type": "string", "maxLength": 255}, "provider_type": {"type": "string", "enum": ["cloud_provider", "saas_provider", "managed_service_provider", "data_centre_provider", "other_supplier"]}, "status": {"type": "string", "enum": ["active", "inactive"]}} }, "ProviderReleaseCreate": { "type": "object", "additionalProperties": false, "properties": {"title": {"type": "string", "maxLength": 255}, "assessed_offering_name": {"type": "string", "maxLength": 255}, "source_ism_version_id": {"type": ["string", "null"]}, "classification_level": {"type": ["string", "null"], "maxLength": 32}, "recommended_review_at": {"type": ["string", "null"], "format": "date"}, "assessed_services": {"type": "array", "minItems": 1, "maxItems": 1000, "items": {"type": "string", "maxLength": 255}}, "assessed_regions": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "string", "enum": ["australia", "global", "aws:ap-southeast-2", "aws:ap-southeast-4", "azure:australiaeast", "azure:australiasoutheast", "azure:australiacentral", "azure:australiacentral2", "gcp:australia-southeast1", "gcp:australia-southeast2"]}}, "qualifications": {"type": ["array", "null"], "maxItems": 1000, "items": {}}}, "required": ["title", "assessed_offering_name", "assessed_services", "assessed_regions"] }, "ProviderReleasePatch": { "type": "object", "additionalProperties": false, "properties": {"title": {"type": "string", "maxLength": 255}, "assessed_offering_name": {"type": "string", "maxLength": 255}, "source_ism_version_id": {"type": ["string", "null"]}, "classification_level": {"type": ["string", "null"], "maxLength": 32}, "recommended_review_at": {"type": ["string", "null"], "format": "date"}, "assessed_services": {"type": "array", "minItems": 1, "maxItems": 1000, "items": {"type": "string", "maxLength": 255}}, "assessed_regions": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "string", "enum": ["australia", "global", "aws:ap-southeast-2", "aws:ap-southeast-4", "azure:australiaeast", "azure:australiasoutheast", "azure:australiacentral", "azure:australiacentral2", "gcp:australia-southeast1", "gcp:australia-southeast2"]}}, "qualifications": {"type": ["array", "null"], "maxItems": 1000, "items": {}}} }, "ProviderRelease": { "type": "object", "additionalProperties": false, "properties": {"id": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}, "external_control_provider_id": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}, "title": {"type": "string", "maxLength": 255}, "assessed_offering_name": {"type": "string", "maxLength": 255}, "source_ism_version_id": {"type": ["string", "null"]}, "classification_level": {"type": ["string", "null"], "maxLength": 32}, "recommended_review_at": {"type": ["string", "null"], "format": "date"}, "assessed_services": {"type": "array", "minItems": 1, "maxItems": 1000, "items": {"type": "string", "maxLength": 255}}, "assessed_regions": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "string", "enum": ["australia", "global", "aws:ap-southeast-2", "aws:ap-southeast-4", "azure:australiaeast", "azure:australiasoutheast", "azure:australiacentral", "azure:australiacentral2", "gcp:australia-southeast1", "gcp:australia-southeast2"]}}, "qualifications": {"type": ["array", "null"], "maxItems": 1000, "items": {}}, "status": {"type": "string"}, "package_identifier": {"type": "string"}, "assessment_programme": {"type": "string"}, "published_by": {"type": ["string", "null"]}, "published_at": {"type": ["string", "null"], "format": "date-time"}, "checksum": {"type": ["string", "null"]}, "import_validation_summary": {"type": ["object", "array", "null"], "description": "Omitted when the release contains restricted material and the actor lacks restricted read."}} }, "ProviderArtefactCreate": { "type": "object", "additionalProperties": false, "properties": {"title": {"type": "string", "maxLength": 255}, "artefact_type": {"type": "string", "enum": ["irap_report", "soc_2_report", "iso_27001_certificate", "csa_caiq", "contract_clause", "shared_responsibility_matrix", "security_whitepaper", "other"]}, "external_provider_assurance_package_id": {"type": ["string", "null"]}, "document_role": {"type": ["string", "null"], "enum": ["ccm", "assessment_letter", "report", "consumer_guide", "addendum", null]}, "access_restricted": {"type": "boolean"}, "issue_date": {"type": ["string", "null"], "format": "date"}, "expiry_date": {"type": ["string", "null"], "format": "date"}, "external_url": {"type": ["string", "null"], "format": "uri", "maxLength": 2048}, "file": {"type": "string", "format": "binary", "description": "At most 50 MiB; PDF, CSV, XLSX, DOCX or TXT; quarantined and scanned."}, "notes": {"type": ["string", "null"], "maxLength": 5000}}, "required": ["title", "artefact_type"], "oneOf": [{"required": ["external_url"], "not": {"required": ["file"]}}, {"required": ["file"], "not": {"required": ["external_url"]}}] }, "ProviderBulkUpload": { "type": "object", "additionalProperties": false, "properties": {"files": {"type": "array", "minItems": 1, "maxItems": 25, "items": {"type": "string", "format": "binary", "description": "At most 50 MiB; PDF, CSV, XLSX, DOCX or TXT; quarantined and scanned."}}, "access_restricted": {"type": "boolean"}, "notes": {"type": ["string", "null"], "maxLength": 5000}}, "required": ["files"] }, "ProviderImport": { "type": "object", "additionalProperties": false, "properties": {"ism_version_id": {"type": ["string", "null"]}, "source_title": {"type": ["string", "null"], "maxLength": 255}} }, "ProviderAssertionConfirm": { "type": "object", "additionalProperties": false, "properties": {"control_reference_id": {"type": ["string", "null"]}, "review_comments": {"type": ["string", "null"], "maxLength": 10000}} }, "ProviderAssertionReject": { "type": "object", "additionalProperties": false, "properties": {"reason": {"type": ["string", "null"], "maxLength": 5000}} }, "ProviderEmptyAction": { "type": "object", "additionalProperties": false, "properties": {} }, "ProviderDeleted": { "type": "object", "additionalProperties": false, "properties": {"deleted": {"type": "boolean", "const": true}}, "required": ["deleted"] }, "ProviderArtefact": { "type": "object", "additionalProperties": false, "properties": {"title": {"type": "string", "maxLength": 255}, "artefact_type": {"type": "string", "enum": ["irap_report", "soc_2_report", "iso_27001_certificate", "csa_caiq", "contract_clause", "shared_responsibility_matrix", "security_whitepaper", "other"]}, "external_provider_assurance_package_id": {"type": ["string", "null"]}, "document_role": {"type": ["string", "null"], "enum": ["ccm", "assessment_letter", "report", "consumer_guide", "addendum", null]}, "access_restricted": {"type": "boolean"}, "issue_date": {"type": ["string", "null"], "format": "date"}, "expiry_date": {"type": ["string", "null"], "format": "date"}, "external_url": {"type": ["string", "null"], "format": "uri", "maxLength": 2048}, "notes": {"type": ["string", "null"], "maxLength": 5000}, "id": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}, "external_control_provider_id": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}, "original_filename": {"type": ["string", "null"]}, "mime_type": {"type": ["string", "null"]}, "file_size": {"type": ["integer", "null"]}, "checksum": {"type": ["string", "null"]}, "checksum_algorithm": {"type": ["string", "null"]}, "upload_status": {"type": "string", "enum": ["pending_scan", "ready", "error"]}, "uploaded_by_user_id": {"type": ["string", "null"]}, "uploaded_at": {"type": ["string", "null"], "format": "date-time"}, "upload_error": {"type": ["object", "null"], "additionalProperties": false, "properties": {"type": {"type": "string"}}}, "import_error": {"type": ["string", "null"]}, "import_progress": {"type": ["object", "null"], "additionalProperties": false, "properties": {"status": {"type": "string"}, "phase": {"type": "string"}, "total": {"type": "integer"}, "processed": {"type": "integer"}, "updated_at": {"type": "string"}}}, "import_result": {"type": ["object", "null"], "additionalProperties": false, "properties": {"parser_version": {"type": "string"}, "parser_profile": {"type": "string"}, "rows_seen": {"type": "integer"}, "assertion_candidates": {"type": "integer"}, "quarantined_rows": {"type": "integer"}, "exact_matches": {"type": "integer"}, "staging_result_id": {"type": "string"}}}, "file_url": {"type": ["string", "null"]}} }, "ProviderAssertion": { "type": "object", "additionalProperties": false, "properties": {"id": {"type": ["string", "null"]}, "external_provider_assurance_package_id": {"type": ["string", "null"]}, "external_provider_artefact_id": {"type": ["string", "null"]}, "control_reference_id": {"type": ["string", "null"]}, "source_ism_version_id": {"type": ["string", "null"]}, "exact_ccm_identifier": {"type": ["string", "null"]}, "source_sheet": {"type": ["string", "null"]}, "mapping_method": {"type": ["string", "null"]}, "review_state": {"type": ["string", "null"]}, "coverage_classification": {"type": ["string", "null"]}, "upstream_provider_responsibility": {"type": ["string", "null"]}, "upstream_provider_implementation_status": {"type": ["string", "null"]}, "upstream_provider_comments": {"type": ["string", "null"]}, "upstream_consumer_responsibility": {"type": ["string", "null"]}, "upstream_consumer_implementation_required": {"type": ["string", "null"]}, "upstream_consumer_configuration_required": {"type": ["string", "null"]}, "upstream_consumer_comments": {"type": ["string", "null"]}, "checksum": {"type": ["string", "null"]}, "reviewed_by": {"type": ["string", "null"]}, "reviewed_at": {"type": ["string", "null"]}, "review_comments": {"type": ["string", "null"]}, "etag": {"type": ["string", "null"]}, "source_row": {"type": ["integer", "null"]}, "mapping_confidence": {"type": ["number", "null"]}, "parser_warnings": {"type": ["array", "null"], "items": {}}} }, "ProviderExactReview": { "type": "object", "additionalProperties": false, "properties": {"confirmed_count": {"type": "integer"}, "artefact": {"$ref": "#/components/schemas/ProviderArtefact"}} }, "ProviderOptions": { "type": "object", "additionalProperties": false, "properties": {"provider_types": {"type": "array", "items": {"type": "string", "enum": ["cloud_provider", "saas_provider", "managed_service_provider", "data_centre_provider", "other_supplier"]}}, "artefact_types": {"type": "array", "items": {"type": "string", "enum": ["irap_report", "soc_2_report", "iso_27001_certificate", "csa_caiq", "contract_clause", "shared_responsibility_matrix", "security_whitepaper", "other"]}}, "regions": {"type": "array", "items": {"type": "object", "additionalProperties": false, "properties": {"label": {"type": "string"}, "value": {"type": "string"}, "provider_key": {"type": ["string", "null"]}}}}, "classification_levels": {"type": "array", "items": {"type": "string"}}, "ism_versions": {"type": "array", "items": {"type": "object", "additionalProperties": false, "properties": {"id": {"type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$"}, "name": {"type": "string"}, "label": {"type": ["string", "null"]}}}}, "document_roles": {"type": "array", "items": {"type": "string"}}, "control_references": {"type": "array", "items": {"type": "object", "additionalProperties": false, "properties": {"id": {"$ref": "#/components/schemas/Ulid"}, "ism_version_id": {"$ref": "#/components/schemas/Ulid"}, "control_id": {"type": "string"}, "title": {"type": ["string", "null"]}}}, "description": "Only included when ism_version_id is supplied. Up to 50 catalogue references per page."}, "control_reference_pages": {"type": "object", "additionalProperties": false, "properties": {"current_page": {"type": "integer"}, "last_page": {"type": "integer"}, "next": {"type": ["string", "null"]}, "prev": {"type": ["string", "null"]}}}} } } } }