{ "openapi": "3.1.0", "info": { "title": "BimZone API", "version": "1.0.0", "description": "The BimZone public API. Authenticate with a workspace-scoped API key in the `X-Api-Key` header.\n\n**Pagination is cursor-based.** Pass `nextCursor` from the previous page back as `cursor`. The cursor is opaque: do not parse or construct one. Offset paging is not offered because a concurrent insert makes it skip and duplicate rows, which is silent data loss for a poller.\n\n**Errors** are always `{ error: { code, message, requestId } }`. Switch on `code`; `message` is not stable. A resource in another workspace returns 404, not 403.\n\n**Deprecation** is announced with the `Deprecation` and `Sunset` headers (RFC 8594)." }, "servers": [ { "url": "/", "description": "This deployment" } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } }, "security": [ { "apiKey": [] } ], "paths": { "/api/v1/projects/{projectId}/capture/floor-plans/{floorPlanId}": { "get": { "operationId": "getFloorPlan", "summary": "Fetch a single floor plan by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "floorPlanId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "level": { "type": [ "string", "null" ] }, "widthPx": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "heightPx": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "scaleMPerPx": { "type": [ "number", "null" ] }, "rotationDeg": { "type": "number" }, "sortOrder": { "type": "integer" }, "levelOrder": { "type": "integer" }, "isVisible": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "level", "widthPx", "heightPx", "scaleMPerPx", "rotationDeg", "sortOrder", "levelOrder", "isVisible", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/capture/floor-plans": { "get": { "operationId": "listFloorPlans", "summary": "List floor plans in a project.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "level": { "type": [ "string", "null" ] }, "widthPx": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "heightPx": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "scaleMPerPx": { "type": [ "number", "null" ] }, "rotationDeg": { "type": "number" }, "sortOrder": { "type": "integer" }, "levelOrder": { "type": "integer" }, "isVisible": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "level", "widthPx", "heightPx", "scaleMPerPx", "rotationDeg", "sortOrder", "levelOrder", "isVisible", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/capture/milestones/{milestoneId}": { "get": { "operationId": "getCaptureMilestone", "summary": "Fetch a single capture milestone by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "milestoneId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "capturedOn": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "capturedOn", "description", "sortOrder", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/capture/milestones": { "get": { "operationId": "listCaptureMilestones", "summary": "List named capture milestones in a project.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "capturedOn": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "capturedOn", "description", "sortOrder", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/capture/photos/{photoId}": { "get": { "operationId": "getPhoto", "summary": "Fetch a single captured photo by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "photoId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "floorPlanId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "milestoneId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "photo360", "photo", "video_frame", "drone" ] }, "planX": { "type": [ "number", "null" ] }, "planY": { "type": [ "number", "null" ] }, "worldPosition": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" } }, "required": [ "x", "y", "z" ], "additionalProperties": false }, { "type": "null" } ] }, "elementGuid": { "type": [ "string", "null" ] }, "modelId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "takenAt": { "type": "string" }, "visibility": { "type": "string", "enum": [ "draft", "live" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "floorPlanId", "milestoneId", "kind", "planX", "planY", "worldPosition", "elementGuid", "modelId", "takenAt", "visibility", "tags", "notes", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/capture/photos": { "get": { "operationId": "listPhotos", "summary": "List captured photos in a project, optionally scoped to a takenAt window (from/to).", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "floorPlanId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "milestoneId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "photo360", "photo", "video_frame", "drone" ] }, "planX": { "type": [ "number", "null" ] }, "planY": { "type": [ "number", "null" ] }, "worldPosition": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" } }, "required": [ "x", "y", "z" ], "additionalProperties": false }, { "type": "null" } ] }, "elementGuid": { "type": [ "string", "null" ] }, "modelId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "takenAt": { "type": "string" }, "visibility": { "type": "string", "enum": [ "draft", "live" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "floorPlanId", "milestoneId", "kind", "planX", "planY", "worldPosition", "elementGuid", "modelId", "takenAt", "visibility", "tags", "notes", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/change-orders/{changeOrderId}": { "get": { "operationId": "getChangeOrder", "summary": "Fetch a single change order by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "changeOrderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "reasonType": { "type": "string", "enum": [ "client_request", "design_change", "site_condition", "error_omission", "regulatory", "other" ] }, "status": { "type": "string", "enum": [ "proposed", "under_review", "approved", "rejected" ] }, "amount": { "type": [ "string", "null" ] }, "currencyCode": { "type": [ "string", "null" ] }, "scheduleImpactDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "wbsCode": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "rejectionReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "description", "reasonType", "status", "amount", "currencyCode", "scheduleImpactDays", "wbsCode", "decidedAt", "rejectionReason", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/change-orders": { "get": { "operationId": "listChangeOrders", "summary": "List change orders in a project, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "reasonType": { "type": "string", "enum": [ "client_request", "design_change", "site_condition", "error_omission", "regulatory", "other" ] }, "status": { "type": "string", "enum": [ "proposed", "under_review", "approved", "rejected" ] }, "amount": { "type": [ "string", "null" ] }, "currencyCode": { "type": [ "string", "null" ] }, "scheduleImpactDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "wbsCode": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "rejectionReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "description", "reasonType", "status", "amount", "currencyCode", "scheduleImpactDays", "wbsCode", "decidedAt", "rejectionReason", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/clashes/tests/{testId}/results/{resultId}": { "get": { "operationId": "getClashResult", "summary": "Fetch a single clash result by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "testId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resultId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "testId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "clashType": { "type": "string", "enum": [ "hard", "clearance", "duplicate" ] }, "aGuid": { "type": "string" }, "aType": { "type": [ "string", "null" ] }, "aName": { "type": [ "string", "null" ] }, "bGuid": { "type": "string" }, "bType": { "type": [ "string", "null" ] }, "bName": { "type": [ "string", "null" ] }, "overlap": { "type": [ "number", "null" ] }, "position": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" } }, "required": [ "x", "y", "z" ], "additionalProperties": false }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "new", "active", "reviewed", "approved", "resolved", "not_an_issue", "acceptable", "duplicate" ] }, "severityScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "severityBand": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, { "type": "null" } ] }, "priorityScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reviewerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "ownerDiscipline": { "type": [ "string", "null" ] }, "reviewerDiscipline": { "type": [ "string", "null" ] }, "issueId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "slaDueAt": { "type": [ "string", "null" ] }, "resolvedAt": { "type": [ "string", "null" ] }, "firstSeenAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "testId", "projectId", "clashType", "aGuid", "aType", "aName", "bGuid", "bType", "bName", "overlap", "position", "status", "severityScore", "severityBand", "priorityScore", "ownerId", "reviewerId", "ownerDiscipline", "reviewerDiscipline", "issueId", "slaDueAt", "resolvedAt", "firstSeenAt", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/clashes/tests/{testId}/results": { "get": { "operationId": "listClashResults", "summary": "List clash results for a test.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "testId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "testId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "clashType": { "type": "string", "enum": [ "hard", "clearance", "duplicate" ] }, "aGuid": { "type": "string" }, "aType": { "type": [ "string", "null" ] }, "aName": { "type": [ "string", "null" ] }, "bGuid": { "type": "string" }, "bType": { "type": [ "string", "null" ] }, "bName": { "type": [ "string", "null" ] }, "overlap": { "type": [ "number", "null" ] }, "position": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" } }, "required": [ "x", "y", "z" ], "additionalProperties": false }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "new", "active", "reviewed", "approved", "resolved", "not_an_issue", "acceptable", "duplicate" ] }, "severityScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "severityBand": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, { "type": "null" } ] }, "priorityScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reviewerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "ownerDiscipline": { "type": [ "string", "null" ] }, "reviewerDiscipline": { "type": [ "string", "null" ] }, "issueId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "slaDueAt": { "type": [ "string", "null" ] }, "resolvedAt": { "type": [ "string", "null" ] }, "firstSeenAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "testId", "projectId", "clashType", "aGuid", "aType", "aName", "bGuid", "bType", "bName", "overlap", "position", "status", "severityScore", "severityBand", "priorityScore", "ownerId", "reviewerId", "ownerDiscipline", "reviewerDiscipline", "issueId", "slaDueAt", "resolvedAt", "firstSeenAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/clashes/tests/{testId}": { "get": { "operationId": "getClashTest", "summary": "Fetch a single clash test by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "testId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "category_matrix", "search_set" ] }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "autoClash": { "type": "boolean" }, "summary": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "lastRunAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "mode", "status", "autoClash", "summary", "lastRunAt", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/clashes/tests": { "get": { "operationId": "listClashTests", "summary": "List clash tests in a project.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "category_matrix", "search_set" ] }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "autoClash": { "type": "boolean" }, "summary": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "lastRunAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "mode", "status", "autoClash", "summary", "lastRunAt", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/documents/{documentId}/download": { "get": { "operationId": "downloadDocument", "summary": "A short-lived signed URL for the document's file. Never the storage key itself.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "url", "expiresAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/documents/{documentId}/revisions": { "get": { "operationId": "listDocumentRevisions", "summary": "List every live revision in a document's revision chain, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "folderPath": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": [ "string", "null" ] }, "sizeBytes": { "type": "integer" }, "cdeState": { "type": "string", "enum": [ "wip", "shared", "published", "archived" ] }, "suitabilityCode": { "type": [ "string", "null" ] }, "revision": { "type": [ "string", "null" ] }, "revisionCode": { "type": [ "string", "null" ] }, "revisionStage": { "anyOf": [ { "type": "string", "enum": [ "P", "C" ] }, { "type": "null" } ] }, "revisionOrdinal": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "revisionGroupId": { "type": "string", "format": "uuid" }, "isCurrentRevision": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "folderPath", "name", "contentType", "sizeBytes", "cdeState", "suitabilityCode", "revision", "revisionCode", "revisionStage", "revisionOrdinal", "revisionGroupId", "isCurrentRevision", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/documents/{documentId}": { "get": { "operationId": "getDocument", "summary": "Fetch a single document by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "folderPath": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": [ "string", "null" ] }, "sizeBytes": { "type": "integer" }, "cdeState": { "type": "string", "enum": [ "wip", "shared", "published", "archived" ] }, "suitabilityCode": { "type": [ "string", "null" ] }, "revision": { "type": [ "string", "null" ] }, "revisionCode": { "type": [ "string", "null" ] }, "revisionStage": { "anyOf": [ { "type": "string", "enum": [ "P", "C" ] }, { "type": "null" } ] }, "revisionOrdinal": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "revisionGroupId": { "type": "string", "format": "uuid" }, "isCurrentRevision": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "folderPath", "name", "contentType", "sizeBytes", "cdeState", "suitabilityCode", "revision", "revisionCode", "revisionStage", "revisionOrdinal", "revisionGroupId", "isCurrentRevision", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/documents": { "get": { "operationId": "listDocuments", "summary": "List the current, live document revisions in a project.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "folderPath": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": [ "string", "null" ] }, "sizeBytes": { "type": "integer" }, "cdeState": { "type": "string", "enum": [ "wip", "shared", "published", "archived" ] }, "suitabilityCode": { "type": [ "string", "null" ] }, "revision": { "type": [ "string", "null" ] }, "revisionCode": { "type": [ "string", "null" ] }, "revisionStage": { "anyOf": [ { "type": "string", "enum": [ "P", "C" ] }, { "type": "null" } ] }, "revisionOrdinal": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "revisionGroupId": { "type": "string", "format": "uuid" }, "isCurrentRevision": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "folderPath", "name", "contentType", "sizeBytes", "cdeState", "suitabilityCode", "revision", "revisionCode", "revisionStage", "revisionOrdinal", "revisionGroupId", "isCurrentRevision", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/inspections/{inspectionId}/items/{itemId}": { "get": { "operationId": "getInspectionItem", "summary": "Fetch a single inspection checklist item by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "inspectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "inspectionId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "standardRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "pass", "fail", "observation", "na" ] }, "notes": { "type": [ "string", "null" ] }, "elementGuid": { "type": [ "string", "null" ] }, "issueId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sortOrder": { "type": "integer" }, "updatedAt": { "type": "string" } }, "required": [ "id", "inspectionId", "title", "standardRef", "status", "notes", "elementGuid", "issueId", "sortOrder", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/inspections/{inspectionId}/items": { "get": { "operationId": "listInspectionItems", "summary": "List an inspection's checklist items, in checklist order.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "inspectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "inspectionId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "standardRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "pass", "fail", "observation", "na" ] }, "notes": { "type": [ "string", "null" ] }, "elementGuid": { "type": [ "string", "null" ] }, "issueId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sortOrder": { "type": "integer" }, "updatedAt": { "type": "string" } }, "required": [ "id", "inspectionId", "title", "standardRef", "status", "notes", "elementGuid", "issueId", "sortOrder", "updatedAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/inspections/{inspectionId}": { "get": { "operationId": "getInspection", "summary": "Fetch a single inspection by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "inspectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "quality", "safety", "compliance", "maintenance" ] }, "standardRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "in_progress", "completed" ] }, "assigneeId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dueDate": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "type", "standardRef", "status", "assigneeId", "dueDate", "completedAt", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/inspections": { "get": { "operationId": "listInspections", "summary": "List inspections in a project, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "quality", "safety", "compliance", "maintenance" ] }, "standardRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "in_progress", "completed" ] }, "assigneeId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dueDate": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "type", "standardRef", "status", "assigneeId", "dueDate", "completedAt", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/issues/{issueId}/comments/{commentId}": { "get": { "operationId": "getIssueComment", "summary": "Fetch a single issue comment by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "issueId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "issueId": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "issueId", "body", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/issues/{issueId}/comments": { "get": { "operationId": "listIssueComments", "summary": "List comments on an issue, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "issueId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "issueId": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "issueId", "body", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } }, "post": { "operationId": "addIssueComment", "summary": "Add a comment to an issue. Idempotent when clientUuid is repeated.", "description": "Requires an API key with the `write` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "issueId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 8000 }, "clientUuid": { "type": "string", "format": "uuid" } }, "required": [ "body" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "issueId": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "issueId", "body", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/issues/{issueId}/status": { "post": { "operationId": "transitionIssueStatus", "summary": "Move an issue to a new status. A repeat of the current status is a no-op.", "description": "Requires an API key with the `write` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "issueId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "in_progress", "in_review", "closed", "verified" ] } }, "required": [ "status" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assigneeId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dueDate": { "type": [ "string", "null" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "bcfTopicGuid": { "type": [ "string", "null" ] }, "closedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "description", "type", "status", "priority", "assigneeId", "dueDate", "labels", "source", "bcfTopicGuid", "closedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/issues/{issueId}": { "get": { "operationId": "getIssue", "summary": "Fetch a single issue by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "issueId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assigneeId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dueDate": { "type": [ "string", "null" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "bcfTopicGuid": { "type": [ "string", "null" ] }, "closedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "description", "type", "status", "priority", "assigneeId", "dueDate", "labels", "source", "bcfTopicGuid", "closedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/issues": { "get": { "operationId": "listIssues", "summary": "List issues in a project, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assigneeId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dueDate": { "type": [ "string", "null" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "bcfTopicGuid": { "type": [ "string", "null" ] }, "closedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "description", "type", "status", "priority", "assigneeId", "dueDate", "labels", "source", "bcfTopicGuid", "closedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } }, "post": { "operationId": "createIssue", "summary": "Create an issue. Idempotent when clientUuid is repeated.", "description": "Requires an API key with the `write` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientUuid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "clash", "design", "observation", "quality", "safety" ], "default": "design" }, "priority": { "type": "string", "enum": [ "critical", "major", "normal", "minor" ], "default": "normal" }, "assigneeId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string", "maxLength": 60 }, "maxItems": 20, "default": [] } }, "required": [ "title" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assigneeId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dueDate": { "type": [ "string", "null" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "bcfTopicGuid": { "type": [ "string", "null" ] }, "closedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "description", "type", "status", "priority", "assigneeId", "dueDate", "labels", "source", "bcfTopicGuid", "closedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/mars/{marId}": { "get": { "operationId": "getMar", "summary": "Fetch a single MAR by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "marId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "materialDescription": { "type": "string" }, "specClause": { "type": [ "string", "null" ] }, "manufacturer": { "type": [ "string", "null" ] }, "modelNumber": { "type": [ "string", "null" ] }, "supplier": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "submitted", "under_review", "approved", "approved_with_comments", "rejected" ] }, "submittedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reviewerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "requiredDecisionDate": { "type": [ "string", "null" ] }, "decisionNotes": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "materialDescription", "specClause", "manufacturer", "modelNumber", "supplier", "status", "submittedBy", "reviewerId", "requiredDecisionDate", "decisionNotes", "decidedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/mars": { "get": { "operationId": "listMars", "summary": "List Material Approval Requests in a project, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "materialDescription": { "type": "string" }, "specClause": { "type": [ "string", "null" ] }, "manufacturer": { "type": [ "string", "null" ] }, "modelNumber": { "type": [ "string", "null" ] }, "supplier": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "submitted", "under_review", "approved", "approved_with_comments", "rejected" ] }, "submittedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reviewerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "requiredDecisionDate": { "type": [ "string", "null" ] }, "decisionNotes": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "materialDescription", "specClause", "manufacturer", "modelNumber", "supplier", "status", "submittedBy", "reviewerId", "requiredDecisionDate", "decisionNotes", "decidedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/members": { "get": { "operationId": "listProjectMembers", "summary": "List the members of a project.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "upload_engineer", "viewer", "inspector" ] }, "createdAt": { "type": "string" } }, "required": [ "userId", "name", "role", "createdAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/models/{modelId}": { "get": { "operationId": "getModel", "summary": "Fetch a single model (any version) by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "modelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "ifc", "frag", "pointcloud", "aps" ] }, "originalFilename": { "type": "string" }, "status": { "type": "string", "enum": [ "uploaded", "processing", "ready", "failed" ] }, "progress": { "type": "number" }, "sizeBytes": { "type": "number" }, "elementCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ifcSchema": { "type": [ "string", "null" ] }, "cdeState": { "type": "string", "enum": [ "wip", "shared", "published", "archived" ] }, "suitabilityCode": { "type": [ "string", "null" ] }, "revisionCode": { "type": [ "string", "null" ] }, "versionGroupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "versionNumber": { "type": "integer" }, "isCurrentVersion": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "sourceType", "originalFilename", "status", "progress", "sizeBytes", "elementCount", "ifcSchema", "cdeState", "suitabilityCode", "revisionCode", "versionGroupId", "versionNumber", "isCurrentVersion", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/models": { "get": { "operationId": "listModels", "summary": "List the current-version 3D models in a project.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "ifc", "frag", "pointcloud", "aps" ] }, "originalFilename": { "type": "string" }, "status": { "type": "string", "enum": [ "uploaded", "processing", "ready", "failed" ] }, "progress": { "type": "number" }, "sizeBytes": { "type": "number" }, "elementCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ifcSchema": { "type": [ "string", "null" ] }, "cdeState": { "type": "string", "enum": [ "wip", "shared", "published", "archived" ] }, "suitabilityCode": { "type": [ "string", "null" ] }, "revisionCode": { "type": [ "string", "null" ] }, "versionGroupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "versionNumber": { "type": "integer" }, "isCurrentVersion": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "sourceType", "originalFilename", "status", "progress", "sizeBytes", "elementCount", "ifcSchema", "cdeState", "suitabilityCode", "revisionCode", "versionGroupId", "versionNumber", "isCurrentVersion", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/rfis/{rfiId}": { "get": { "operationId": "getRfi", "summary": "Fetch a single RFI by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "rfiId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "subject": { "type": "string" }, "question": { "type": "string" }, "specSection": { "type": [ "string", "null" ] }, "drawingRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "under_review", "answered", "closed" ] }, "priority": { "type": "string", "enum": [ "critical", "major", "normal", "minor" ] }, "submittedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "submittedTo": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reviewerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "approverId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "costImpact": { "type": [ "string", "null" ] }, "costImpactCurrency": { "type": [ "string", "null" ] }, "scheduleImpactDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "requiredResponseDate": { "type": [ "string", "null" ] }, "response": { "type": [ "string", "null" ] }, "resolution": { "type": [ "string", "null" ] }, "issueId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "answeredAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "subject", "question", "specSection", "drawingRef", "status", "priority", "submittedBy", "submittedTo", "reviewerId", "approverId", "costImpact", "costImpactCurrency", "scheduleImpactDays", "requiredResponseDate", "response", "resolution", "issueId", "answeredAt", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/rfis": { "get": { "operationId": "listRfis", "summary": "List RFIs in a project, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "subject": { "type": "string" }, "question": { "type": "string" }, "specSection": { "type": [ "string", "null" ] }, "drawingRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "under_review", "answered", "closed" ] }, "priority": { "type": "string", "enum": [ "critical", "major", "normal", "minor" ] }, "submittedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "submittedTo": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reviewerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "approverId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "costImpact": { "type": [ "string", "null" ] }, "costImpactCurrency": { "type": [ "string", "null" ] }, "scheduleImpactDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "requiredResponseDate": { "type": [ "string", "null" ] }, "response": { "type": [ "string", "null" ] }, "resolution": { "type": [ "string", "null" ] }, "issueId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "answeredAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "subject", "question", "specSection", "drawingRef", "status", "priority", "submittedBy", "submittedTo", "reviewerId", "approverId", "costImpact", "costImpactCurrency", "scheduleImpactDays", "requiredResponseDate", "response", "resolution", "issueId", "answeredAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } }, "post": { "operationId": "createRfi", "summary": "Submit an RFI. Idempotent when clientUuid is repeated.", "description": "Requires an API key with the `write` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientUuid": { "type": "string", "format": "uuid" }, "subject": { "type": "string", "minLength": 2, "maxLength": 300 }, "question": { "type": "string", "minLength": 2, "maxLength": 10000 }, "specSection": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "drawingRef": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "critical", "major", "normal", "minor" ], "default": "normal" }, "submittedTo": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reviewerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "requiredResponseDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "subject", "question" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "subject": { "type": "string" }, "question": { "type": "string" }, "specSection": { "type": [ "string", "null" ] }, "drawingRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "under_review", "answered", "closed" ] }, "priority": { "type": "string", "enum": [ "critical", "major", "normal", "minor" ] }, "submittedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "submittedTo": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reviewerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "approverId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "costImpact": { "type": [ "string", "null" ] }, "costImpactCurrency": { "type": [ "string", "null" ] }, "scheduleImpactDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "requiredResponseDate": { "type": [ "string", "null" ] }, "response": { "type": [ "string", "null" ] }, "resolution": { "type": [ "string", "null" ] }, "issueId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "answeredAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "subject", "question", "specSection", "drawingRef", "status", "priority", "submittedBy", "submittedTo", "reviewerId", "approverId", "costImpact", "costImpactCurrency", "scheduleImpactDays", "requiredResponseDate", "response", "resolution", "issueId", "answeredAt", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/safety-incidents/{incidentId}": { "get": { "operationId": "getSafetyIncident", "summary": "Fetch a single safety incident by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "incidentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "type": { "type": "string", "enum": [ "injury", "near_miss", "property_damage", "environmental", "security" ] }, "severity": { "type": "string", "enum": [ "near_miss", "first_aid", "medical_treatment", "lost_time", "fatality" ] }, "status": { "type": "string", "enum": [ "reported", "investigating", "closed" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "occurredAt": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "peopleInvolved": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "correctiveActions": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "type", "severity", "status", "title", "description", "occurredAt", "location", "peopleInvolved", "correctiveActions", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/safety-incidents": { "get": { "operationId": "listSafetyIncidents", "summary": "List safety incidents in a project, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "type": { "type": "string", "enum": [ "injury", "near_miss", "property_damage", "environmental", "security" ] }, "severity": { "type": "string", "enum": [ "near_miss", "first_aid", "medical_treatment", "lost_time", "fatality" ] }, "status": { "type": "string", "enum": [ "reported", "investigating", "closed" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "occurredAt": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "peopleInvolved": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "correctiveActions": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "type", "severity", "status", "title", "description", "occurredAt", "location", "peopleInvolved", "correctiveActions", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/schedules/{scheduleId}/tasks/{taskId}": { "get": { "operationId": "getScheduleTask", "summary": "Fetch a single schedule task by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "scheduleId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentTaskId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "wbsCode": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "discipline": { "type": [ "string", "null" ] }, "storey": { "type": [ "string", "null" ] }, "plannedStart": { "type": [ "string", "null" ] }, "plannedEnd": { "type": [ "string", "null" ] }, "actualStart": { "type": [ "string", "null" ] }, "actualFinish": { "type": [ "string", "null" ] }, "percentComplete": { "type": "number" }, "durationDays": { "type": [ "number", "null" ] }, "budgetedCost": { "type": "number" }, "actualCost": { "type": "number" }, "isMilestone": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "scheduleId", "parentTaskId", "externalId", "wbsCode", "name", "discipline", "storey", "plannedStart", "plannedEnd", "actualStart", "actualFinish", "percentComplete", "durationDays", "budgetedCost", "actualCost", "isMilestone", "sortOrder", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/schedules/{scheduleId}/tasks": { "get": { "operationId": "listScheduleTasks", "summary": "List tasks in a schedule.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "scheduleId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentTaskId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "wbsCode": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "discipline": { "type": [ "string", "null" ] }, "storey": { "type": [ "string", "null" ] }, "plannedStart": { "type": [ "string", "null" ] }, "plannedEnd": { "type": [ "string", "null" ] }, "actualStart": { "type": [ "string", "null" ] }, "actualFinish": { "type": [ "string", "null" ] }, "percentComplete": { "type": "number" }, "durationDays": { "type": [ "number", "null" ] }, "budgetedCost": { "type": "number" }, "actualCost": { "type": "number" }, "isMilestone": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "scheduleId", "parentTaskId", "externalId", "wbsCode", "name", "discipline", "storey", "plannedStart", "plannedEnd", "actualStart", "actualFinish", "percentComplete", "durationDays", "budgetedCost", "actualCost", "isMilestone", "sortOrder", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/schedules/{scheduleId}": { "get": { "operationId": "getSchedule", "summary": "Fetch a single schedule by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "currencyCode": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "xer", "msp", "manual" ] }, "taskCount": { "type": "integer" }, "plannedStart": { "type": [ "string", "null" ] }, "plannedFinish": { "type": [ "string", "null" ] }, "statusDate": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "currencyCode", "source", "taskCount", "plannedStart", "plannedFinish", "statusDate", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/schedules": { "get": { "operationId": "listSchedules", "summary": "List imported programmes (schedules) in a project.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "currencyCode": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "xer", "msp", "manual" ] }, "taskCount": { "type": "integer" }, "plannedStart": { "type": [ "string", "null" ] }, "plannedFinish": { "type": [ "string", "null" ] }, "statusDate": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "currencyCode", "source", "taskCount", "plannedStart", "plannedFinish", "statusDate", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/site-diary/{entryId}": { "get": { "operationId": "getSiteDiaryEntry", "summary": "Fetch a single site-diary entry by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "entryDate": { "type": "string" }, "weatherCondition": { "type": [ "string", "null" ] }, "temperatureC": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "manpowerCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "equipment": { "type": [ "string", "null" ] }, "deliveries": { "type": [ "string", "null" ] }, "delays": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "entryDate", "weatherCondition", "temperatureC", "manpowerCount", "equipment", "deliveries", "delays", "notes", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/site-diary": { "get": { "operationId": "listSiteDiaryEntries", "summary": "List a project's site-diary entries, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "entryDate": { "type": "string" }, "weatherCondition": { "type": [ "string", "null" ] }, "temperatureC": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "manpowerCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "equipment": { "type": [ "string", "null" ] }, "deliveries": { "type": [ "string", "null" ] }, "delays": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "entryDate", "weatherCondition", "temperatureC", "manpowerCount", "equipment", "deliveries", "delays", "notes", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/takeoff/summary": { "get": { "operationId": "getTakeoffSummary", "summary": "Quantity takeoff totals for a project's current-version 3D models, grouped by IFC type.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" }, "elementCount": { "type": "integer" }, "groupCount": { "type": "integer" }, "elementsWithQuantities": { "type": "integer" }, "byQuantityKey": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "projectId", "elementCount", "groupCount", "elementsWithQuantities", "byQuantityKey" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/transmittals/{transmittalId}/items/{itemId}": { "get": { "operationId": "getTransmittalItem", "summary": "Fetch a single transmittal manifest line by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transmittalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "transmittalId": { "type": "string", "format": "uuid" }, "documentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "name": { "type": "string" }, "revision": { "type": [ "string", "null" ] }, "suitabilityCode": { "type": [ "string", "null" ] }, "contentHash": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "transmittalId", "documentId", "name", "revision", "suitabilityCode", "contentHash", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/transmittals/{transmittalId}/items": { "get": { "operationId": "listTransmittalItems", "summary": "List the manifest lines issued in a transmittal.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transmittalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "transmittalId": { "type": "string", "format": "uuid" }, "documentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "name": { "type": "string" }, "revision": { "type": [ "string", "null" ] }, "suitabilityCode": { "type": [ "string", "null" ] }, "contentHash": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "transmittalId", "documentId", "name", "revision", "suitabilityCode", "contentHash", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/transmittals/{transmittalId}": { "get": { "operationId": "getTransmittal", "summary": "Fetch a single transmittal by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transmittalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "purposeOfIssue": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "issuedAt": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "purposeOfIssue", "note", "status", "issuedAt", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/transmittals": { "get": { "operationId": "listTransmittals", "summary": "List transmittals in a project, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "purposeOfIssue": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "issuedAt": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "purposeOfIssue", "note", "status", "issuedAt", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/wirs/{wirId}": { "get": { "operationId": "getWir", "summary": "Fetch a single WIR by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "wirId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "inspectionType": { "type": "string", "enum": [ "quality", "safety", "compliance", "structural", "mep", "finishes" ] }, "itpRef": { "type": [ "string", "null" ] }, "floor": { "type": [ "string", "null" ] }, "zone": { "type": [ "string", "null" ] }, "requestedDate": { "type": [ "string", "null" ] }, "scheduledDate": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "submitted", "scheduled", "passed", "failed", "conditional" ] }, "submittedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "inspectorId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "result": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "description", "inspectionType", "itpRef", "floor", "zone", "requestedDate", "scheduledDate", "status", "submittedBy", "inspectorId", "result", "decidedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}/wirs": { "get": { "operationId": "listWirs", "summary": "List Work Inspection Requests in a project, newest first.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "inspectionType": { "type": "string", "enum": [ "quality", "safety", "compliance", "structural", "mep", "finishes" ] }, "itpRef": { "type": [ "string", "null" ] }, "floor": { "type": [ "string", "null" ] }, "zone": { "type": [ "string", "null" ] }, "requestedDate": { "type": [ "string", "null" ] }, "scheduledDate": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "submitted", "scheduled", "passed", "failed", "conditional" ] }, "submittedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "inspectorId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "result": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "number", "title", "description", "inspectionType", "itpRef", "floor", "zone", "requestedDate", "scheduledDate", "status", "submittedBy", "inspectorId", "result", "decidedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects/{projectId}": { "get": { "operationId": "getProject", "summary": "Fetch a single project by id.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived", "closeout" ] }, "units": { "type": "string", "enum": [ "metric", "imperial" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "code", "description", "address", "status", "units", "createdAt", "updatedAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/projects": { "get": { "operationId": "listProjects", "summary": "List the projects in the workspace the API key belongs to.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived", "closeout" ] }, "units": { "type": "string", "enum": [ "metric", "imperial" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "code", "description", "address", "status", "units", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/webhooks/{webhookId}/deliveries/{deliveryId}/replay": { "post": { "operationId": "replayWebhookDelivery", "summary": "Re-queue a dead-lettered delivery.", "description": "Requires an API key with the `write` scope or higher.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requeued": { "type": "boolean" } }, "required": [ "requeued" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/webhooks/{webhookId}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Delivery attempts for a subscription — status, attempts and last error.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "dead_letter" ] }, "attempts": { "type": "integer" }, "lastStatusCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lastError": { "type": [ "string", "null" ] }, "deliveredAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "eventType", "status", "attempts", "lastStatusCode", "lastError", "deliveredAt", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/webhooks/{webhookId}/enable": { "post": { "operationId": "enableWebhook", "summary": "Re-enable a subscription that was switched off after sustained delivery failure.", "description": "Requires an API key with the `write` scope or higher.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "projectId", "eventTypes", "active", "disabledReason", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/webhooks/{webhookId}": { "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook subscription and its delivery history.", "description": "Requires an API key with the `write` scope or higher.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } }, "get": { "operationId": "getWebhook", "summary": "Fetch a single webhook subscription by id. Never carries the signing secret.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "projectId", "eventTypes", "active", "disabledReason", "createdAt" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhook subscriptions in the workspace.", "description": "Requires an API key with the `read` scope or higher.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "projectId", "eventTypes", "active", "disabledReason", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } }, "post": { "operationId": "createWebhook", "summary": "Create a webhook subscription. The signing secret is returned once and never again.", "description": "Requires an API key with the `write` scope or higher.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000, "pattern": "^https\\:\\/\\/" }, "projectId": { "type": "string", "format": "uuid" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "issue.created", "issue.updated", "issue.closed", "rfi.created", "clash.decided", "audit.logged" ] }, "maxItems": 20, "default": [] } }, "required": [ "url" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "secret": { "type": "string", "description": "Shown ONCE. Store it now — it cannot be retrieved later." } }, "required": [ "id", "url", "projectId", "eventTypes", "active", "disabledReason", "createdAt", "secret" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/api/v1/whoami": { "get": { "operationId": "whoami", "summary": "Identify the API key presented: its workspace, scope and prefix.", "description": "Requires an API key with the `read` scope or higher.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "read", "write", "admin" ] }, "name": { "type": "string" }, "keyPrefix": { "type": "string" } }, "required": [ "workspaceId", "scope", "name", "keyPrefix" ], "additionalProperties": false, "$schema": "https://json-schema.org/draft/2019-09/schema#" } } } }, "401": { "description": "No API key, or the key is invalid or revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "The key's scope is below what this operation requires.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Not found — also returned for a resource in another workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Per-key quota exceeded. Honour Retry-After.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "validation_failed", "payload_too_large", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "Human-facing. NOT stable — do not parse it." }, "requestId": { "type": "string", "description": "Quote this when reporting a problem." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } } } }