# QMind Genomics API Base URL: https://genomics-api.qmindlabs.ai OpenAPI: /api/openapi.json Interactive reference: /docs Full machine-readable guide: /llms-full.txt Use Authorization: Bearer . Keep keys in an environment variable or secret manager. Never put keys in URLs, prompts, committed files, or logs. A Math key cannot access this workspace. Roles: REVIEWER can read and work on assigned topics; OWNER can manage Genomics topics, clients, reviews and sync; ADMIN additionally manages existing memberships and worker controls. Scopes restrict a key further: read, write, files:read, files:write, paths:read, keys:manage. Membership and key revocation are rechecked inside writes. All data routes require authentication; documentation is public. A key cannot grant a role its user does not have. Start with GET /api/v1/session then GET /api/v1/tasks?limit=50. IDs are strings (PostgreSQL bigint safe). Task pagination uses the returned next.batch and next.topic as afterBatch and afterTopic. Other list endpoints use before=next. Topic IDs use batch-NNN:topic, e.g. batch-094:4674. Follow pagination to completion; do not assume a single page contains the workspace. Task decision and disposition are effective business state. A verdict from an older campaign returns PENDING with previous_decision and requires_re_review; a timed-out attempt returns TIMED_OUT unless a verified completion supersedes it. GET /tasks and /topics support disposition=TIMED_OUT. GET /assignments returns materialized current-campaign assignments; use history=true to include previous assignments. History is retained. Scientific counts and export item_count are JSON numbers; record IDs remain strings. Reviewer file access covers assigned reports, full revision ZIPs and original source client packages for the assigned campaign. Manual client revision ZIPs, manual publications, salvage evidence and generic internal artifacts require OWNER or ADMIN. Paths and revision feeds apply the same restrictions. Every POST/PUT needs a unique Idempotency-Key of 16–128 ASCII letters, digits or ._:-. Retry the same operation with the same key and identical body. A changed body returns 409. Mutations also check current assignment, campaign and version. Do not suppress conflicts; refetch and review the new state. API-key creation returns its secret exactly once; retrying returns 409, so revoke/recreate if the first response was lost. Report sync: POST /api/v1/sync with {"source":"reports"} to scan changed AWS Batch and Vast result markers. Add sourceKey:"runs/.../result.json" for a specific marker. The response is 202 with jobId; poll GET /api/v1/jobs/{jobId}. Report import atomically queues its baseline measurements and publication. GET /api/v1/operations/imports exposes MEASUREMENTS_PENDING, COMPLETE or NEEDS_ATTENTION. An import is not complete merely because its PDF is visible. Astra and other model reruns: POST /api/v1/sync with {"source":"reruns"}, or add sourceKey:"minos-evals-pass-runs/.../SUMMARY.json". The verifier checks summary, collection, attempt outcomes, model identity, immutable package and full archive checksums. Original report measurements and public-package reruns are separate scientific scopes. 0/10 is a measured 0%, while missing evidence remains UNAVAILABLE with a reason. Never fabricate or copy a model's rate to another model. Topics: POST /api/v1/topics creates a brief/task; POST /api/v1/sync with {"source":"topics"} discovers pipeline briefs. These operations do not launch compute jobs. POST /api/v1/sync with {"source":"measurements"} reconciles missing report measurements. Failed jobs are visible under /api/v1/operations/jobs and /api/v1/operations/issues; POST /api/v1/jobs/{jobId}/retry creates a new attempt chain without deleting history. Scheduled discovery runs every 5 minutes for reports/reruns, 30 minutes for topics; reconciliation every 15 minutes. Schedules only run while workers are explicitly enabled. ZIP revisions: begin a revision, reserve FULL_SUBMISSION or CLIENT_PACKAGE with filename, bytes and SHA-256, then PUT raw application/zip to its artifact URL. Upload only changed deliverables. Download/read-back verification is required before availability. Wait for client publication, then finalize with expectedSelectionRevision from topic details. Unchanged deliverables are inherited. Use the repair/salvage endpoints only for forward-only recovery of a source campaign; they preserve evidence and require OWNER. Files: download by database record ID, never arbitrary storage URLs. /api/v1/topics/{topicUid}/paths requires paths:read; downloads require files:read. Downloads validate bytes and SHA-256 before returning data. Package size limit is 100 MiB. At most two heavy file operations per API process; excess returns 429. API keys allow 600 requests/minute; honor Retry-After. Central dashboard login/invitations remain with the identity service. Existing Genomics memberships can be administered through this API. Fleet machine lists are imported observations, not proof of current AWS Batch status. Compute launch/terminate, collector ingestion and legacy dashboard contract compatibility are separate integration work; do not infer those operations exist from read endpoints. 503 means maintenance or an unavailable dependency; do not retry writes aggressively. /healthz is process liveness; /readyz is writable authority readiness. During migration, maintenance remains until the database, permissions, storage and dashboard compatibility are qualified. AI agents should ask their operator before destructive or externally consequential workflow changes. There is no MCP server in this release; use these REST functions and OpenAPI. { "openapi": "3.1.0", "info": { "title": "QMind Genomics API", "version": "1.0.0", "description": "Genomics workspace REST API. All data endpoints require an API key or a request-bound dashboard assertion. Original and rerun scientific measurements are separate." }, "servers": [ { "url": "https://genomics-api.qmindlabs.ai" } ], "paths": { "/api/v1/session": { "get": { "operationId": "get__session", "summary": "Get your workspace identity and effective role", "tags": [ "Authentication" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "username": { "type": "string" }, "display_name": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "role": { "type": "string", "enum": [ "REVIEWER", "OWNER", "ADMIN" ] }, "identityId": { "type": "string" } }, "required": [ "id", "username", "display_name", "email", "enabled", "role", "identityId" ], "additionalProperties": true }, "workspace": { "type": "object", "properties": { "id": { "const": "ws_genomics" }, "environment": { "const": "production" } }, "required": [ "id", "environment" ], "additionalProperties": true }, "apiKeyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "user", "workspace", "apiKeyId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys": { "get": { "operationId": "get__keys", "summary": "List API keys without secrets", "tags": [ "API keys" ], "description": "Minimum role: REVIEWER. Required key scopes: keys:manage.", "security": [ { "ApiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "actor_id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "identity_id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "REVIEWER", "OWNER", "ADMIN" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "actor_id", "identity_id", "name", "role", "scopes", "created_at", "expires_at", "revoked_at", "last_used_at" ], "additionalProperties": true } } }, "required": [ "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__keys", "summary": "Create an API key; secret returned once", "tags": [ "API keys" ], "description": "Owners create keys for themselves; administrators may create keys for an existing workspace member. A key cannot exceed its creator or recipient role, scopes, or creator-key expiry. A repeated creation returns 409; plaintext is never stored.\n\nMinimum role: OWNER. Required key scopes: keys:manage.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "Secret returned once. Store securely; never logged or recoverable." }, "role": { "type": "string", "enum": [ "REVIEWER", "OWNER", "ADMIN" ] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "token", "role", "scopes" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identityId": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "maxLength": 100 }, "role": { "type": "string", "enum": [ "REVIEWER", "OWNER", "ADMIN" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "files:read", "files:write", "paths:read", "keys:manage" ] }, "maxItems": 6 }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "identityId", "name", "role", "scopes", "expiresInDays" ], "additionalProperties": false } } } } } }, "/api/v1/keys/{keyId}": { "delete": { "operationId": "delete__keys_keyId", "summary": "Revoke an API key immediately", "tags": [ "API keys" ], "description": "Minimum role: OWNER. Required key scopes: keys:manage.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "revoked": { "const": true } }, "required": [ "id", "revoked" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tasks": { "get": { "operationId": "get__tasks", "summary": "Search tasks with reviewer visibility and cursor pagination", "tags": [ "Tasks" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "disposition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "REJECTED", "DISCARDED", "TIMED_OUT" ] } }, { "name": "afterBatch", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^batch-[0-9]{3,6}$" } }, { "name": "afterTopic", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string" }, "batch": { "type": "string" }, "topic": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflow_status": { "type": "string" }, "decision": { "type": "string" }, "previous_decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requires_re_review": { "type": "boolean" }, "decision_campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "submission_campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "type": "string" }, "planned_reviewer_id": { "anyOf": [ { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, { "type": "null" } ] }, "current_package_version_id": { "anyOf": [ { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, { "type": "null" } ] }, "deliverable_selection_revision": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "client_ids": { "type": "array", "items": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." } }, "exclusivity": { "type": "string" }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uid", "batch", "topic", "title", "category", "workflow_status", "decision", "previous_decision", "requires_re_review", "decision_campaign_id", "submission_campaign_id", "disposition", "planned_reviewer_id", "current_package_version_id", "deliverable_selection_revision", "client_ids", "exclusivity", "campaign_id", "status", "phase", "classification" ], "additionalProperties": true } }, "next": { "anyOf": [ { "type": "object", "properties": { "batch": { "type": "string" }, "topic": { "type": "integer", "minimum": 1 } }, "required": [ "batch", "topic" ], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/topics": { "get": { "operationId": "get__topics", "summary": "List topics and their task state", "tags": [ "Topics" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "disposition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "REJECTED", "DISCARDED", "TIMED_OUT" ] } }, { "name": "afterBatch", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 30 } }, { "name": "afterTopic", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string" }, "batch": { "type": "string" }, "topic": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflow_status": { "type": "string" }, "decision": { "type": "string" }, "previous_decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requires_re_review": { "type": "boolean" }, "decision_campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "submission_campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "type": "string" }, "planned_reviewer_id": { "anyOf": [ { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, { "type": "null" } ] }, "current_package_version_id": { "anyOf": [ { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, { "type": "null" } ] }, "deliverable_selection_revision": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "client_ids": { "type": "array", "items": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." } }, "exclusivity": { "type": "string" }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uid", "batch", "topic", "title", "category", "workflow_status", "decision", "previous_decision", "requires_re_review", "decision_campaign_id", "submission_campaign_id", "disposition", "planned_reviewer_id", "current_package_version_id", "deliverable_selection_revision", "client_ids", "exclusivity", "campaign_id", "status", "phase", "classification" ], "additionalProperties": true } }, "next": { "anyOf": [ { "type": "object", "properties": { "batch": { "type": "string" }, "topic": { "type": "integer", "minimum": 1 } }, "required": [ "batch", "topic" ], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__topics", "summary": "Add a Genomics topic and task", "tags": [ "Topics" ], "description": "Creates the dashboard topic/task. It does not launch an AWS Batch computation.\n\nMinimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "topicUid": { "type": "string" } }, "required": [ "topicUid" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batch": { "type": "string", "pattern": "^batch-[0-9]{3,6}$" }, "topic": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "title": { "type": "string", "maxLength": 500 }, "category": { "type": "string", "maxLength": 200 }, "markdown": { "type": "string", "maxLength": 2000000 } }, "required": [ "batch", "topic", "title", "category", "markdown" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}": { "get": { "operationId": "get__topics_topicUid", "summary": "Get topic brief, task, campaigns and clients", "tags": [ "Topics" ], "description": "Minimum role: REVIEWER. Required key scopes: read, paths:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." }, "campaigns": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "clients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "enabled", "created_at", "updated_at" ], "additionalProperties": true } } }, "required": [ "topic", "campaigns", "clients" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "put__topics_topicUid", "summary": "Update topic title and category", "tags": [ "Topics" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 180 }, "category": { "type": "string", "maxLength": 180 } }, "required": [ "title", "category" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/measurements": { "get": { "operationId": "get__topics_topicUid_measurements", "summary": "Get original and rerun pass rates with provenance", "tags": [ "Measurements" ], "description": "Original scientific cohorts and public-package reruns are distinct scopes. Includes scientific passes, completed attempts, rate (0–1), model, timestamp and evidence digest. Missing evidence is not represented as 0%.\n\nMinimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "model_id": { "type": "string" }, "scope": { "type": "string", "enum": [ "original_report", "public_package_rerun" ] }, "status": { "type": "string", "enum": [ "MEASURED", "UNAVAILABLE" ] }, "scientific_passes": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "completed": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "pass_rate": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "measured_at": { "type": "string", "format": "date-time" }, "artifact_sha256": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "model_id", "scope", "status", "scientific_passes", "completed", "pass_rate", "measured_at", "artifact_sha256", "reason" ], "additionalProperties": true } } }, "required": [ "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/topics/{topicUid}/paths": { "get": { "operationId": "get__topics_topicUid_paths", "summary": "Get R2 object paths and checksums", "tags": [ "Files" ], "description": "Minimum role: REVIEWER. Required key scopes: paths:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "reports": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "revisions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "publications": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } } }, "required": [ "reports", "revisions", "publications" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/topics/{topicUid}/notes": { "get": { "operationId": "get__topics_topicUid_notes", "summary": "List topic notes", "tags": [ "Topics" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } } }, "required": [ "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__topics_topicUid_notes", "summary": "Add a topic or campaign note", "tags": [ "Tasks" ], "description": "Minimum role: REVIEWER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 50000 }, "campaignId": { "type": [ "string", "null" ], "maxLength": 256 } }, "required": [ "body", "campaignId" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/events": { "get": { "operationId": "get__topics_topicUid_events", "summary": "List topic events", "tags": [ "Topics" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } } }, "required": [ "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/topics/{topicUid}/reports": { "get": { "operationId": "get__topics_topicUid_reports", "summary": "List topic reports", "tags": [ "Topics" ], "description": "Minimum role: REVIEWER. Required key scopes: read, paths:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } } }, "required": [ "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/topics/{topicUid}/revisions": { "get": { "operationId": "get__topics_topicUid_revisions", "summary": "List topic revisions", "tags": [ "Topics" ], "description": "Minimum role: REVIEWER. Required key scopes: read, paths:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } } }, "required": [ "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__topics_topicUid_revisions", "summary": "Start or resume a package revision", "tags": [ "Revisions" ], "description": "Minimum role: REVIEWER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaignId": { "type": "string", "maxLength": 256 }, "notes": { "type": "string", "maxLength": 10000 } }, "required": [ "campaignId", "notes" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/assignments": { "get": { "operationId": "get__topics_topicUid_assignments", "summary": "List topic assignments", "tags": [ "Topics" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } } }, "required": [ "items" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/topics/{topicUid}/notes/{noteId}": { "put": { "operationId": "put__topics_topicUid_notes_noteId", "summary": "Edit a note with a content precondition", "tags": [ "Tasks" ], "description": "Minimum role: REVIEWER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 50000 }, "expectedBodySha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "body", "expectedBodySha256" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/tags": { "put": { "operationId": "put__topics_topicUid_tags", "summary": "Replace topic tags", "tags": [ "Tasks" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "tags" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 50 } }, "required": [ "tags" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/reviewer": { "put": { "operationId": "put__topics_topicUid_reviewer", "summary": "Assign or remove a reviewer", "tags": [ "Reviews" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "topicUid": { "type": "string" }, "reviewerId": { "anyOf": [ { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, { "type": "null" } ] }, "assignmentId": { "anyOf": [ { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, { "type": "null" } ] } }, "required": [ "topicUid", "reviewerId", "assignmentId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewerId": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]{0,18}$" }, "instructions": { "type": "string", "maxLength": 10000 }, "dueAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "reviewerId", "instructions", "dueAt" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/reviews": { "post": { "operationId": "post__topics_topicUid_reviews", "summary": "Submit a review or comment", "tags": [ "Reviews" ], "description": "Minimum role: REVIEWER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "feedbackId": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "assignmentStatus": { "type": "string" } }, "required": [ "feedbackId", "assignmentStatus" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignmentId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "verdict": { "type": "string", "enum": [ "COMMENT", "READY_AS_IS", "MINOR_REPAIR", "MAJOR_REPAIR", "REJECTED" ] }, "body": { "type": "string", "maxLength": 50000 } }, "required": [ "assignmentId", "verdict", "body" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/decision": { "post": { "operationId": "post__topics_topicUid_decision", "summary": "Override a decision with optimistic concurrency", "tags": [ "Reviews" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedDecision": { "type": "string", "enum": [ "READY", "MINOR_REPAIR", "MAJOR_REPAIR", "REJECTED" ] }, "decision": { "type": "string", "enum": [ "READY", "MINOR_REPAIR", "MAJOR_REPAIR", "REJECTED" ] }, "campaignId": { "type": "string", "maxLength": 256 }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "expectedDecision", "decision", "campaignId", "reason" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/reopen": { "post": { "operationId": "post__topics_topicUid_reopen", "summary": "Reopen a submitted review", "tags": [ "Reviews" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedDecision": { "type": "string", "maxLength": 30 }, "campaignId": { "type": "string", "maxLength": 256 }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "expectedDecision", "campaignId", "reason" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/disposition": { "put": { "operationId": "put__topics_topicUid_disposition", "summary": "Change task disposition", "tags": [ "Tasks" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disposition": { "type": "string", "enum": [ "ACTIVE", "REJECTED", "DISCARDED" ] }, "reason": { "type": "string", "maxLength": 2000 }, "expectedRevision": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "disposition", "reason", "expectedRevision" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/clients": { "put": { "operationId": "put__topics_topicUid_clients", "summary": "Assign one or multiple clients", "tags": [ "Clients" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientIds": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "maxItems": 100 }, "exclusivity": { "type": "string", "enum": [ "EXCLUSIVE", "NON_EXCLUSIVE" ] }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "clientIds", "exclusivity", "reason" ], "additionalProperties": false } } } } } }, "/api/v1/reports": { "get": { "operationId": "get__reports", "summary": "List reports", "tags": [ "Catalog" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/campaigns": { "get": { "operationId": "get__campaigns", "summary": "List campaigns", "tags": [ "Catalog" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/assignments": { "get": { "operationId": "get__assignments", "summary": "List assignments", "tags": [ "Catalog" ], "description": "Returns assignments for each active task’s current campaign and planned reviewer. Use history=true for all historical assignments; no history is deleted. Planned tasks awaiting a campaign are available through /tasks.\n\nMinimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "history", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/clients": { "get": { "operationId": "get__clients", "summary": "List clients", "tags": [ "Catalog" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "enabled", "created_at", "updated_at" ], "additionalProperties": true } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__clients", "summary": "Create a client", "tags": [ "Clients" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/api/v1/reviewers": { "get": { "operationId": "get__reviewers", "summary": "List reviewers", "tags": [ "Catalog" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/users": { "get": { "operationId": "get__users", "summary": "List users", "tags": [ "Catalog" ], "description": "Minimum role: ADMIN. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bugs": { "get": { "operationId": "get__bugs", "summary": "List bugs", "tags": [ "Catalog" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__bugs", "summary": "Report a dashboard or API problem", "tags": [ "Support" ], "description": "Minimum role: REVIEWER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "minLength": 5, "maxLength": 4000 }, "pagePath": { "type": "string", "maxLength": 1000 } }, "required": [ "description", "pagePath" ], "additionalProperties": false } } } } } }, "/api/v1/views": { "get": { "operationId": "get__views", "summary": "List views", "tags": [ "Catalog" ], "description": "Minimum role: OWNER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "put__views", "summary": "Create or update a shared saved view", "tags": [ "Preferences" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "query": { "type": "string", "maxLength": 500 }, "scope": { "type": "string", "maxLength": 200 }, "batch": { "type": "string", "maxLength": 200 }, "category": { "type": "string", "maxLength": 200 }, "status": { "type": "string", "maxLength": 200 } }, "required": [ "name", "query", "scope", "batch", "category", "status" ], "additionalProperties": false } } } } } }, "/api/v1/incidents": { "get": { "operationId": "get__incidents", "summary": "List incidents", "tags": [ "Catalog" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/machines": { "get": { "operationId": "get__machines", "summary": "List machines", "tags": [ "Catalog" ], "description": "Minimum role: OWNER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "topicUid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/clients/{clientId}": { "put": { "operationId": "put__clients_clientId", "summary": "Update a client", "tags": [ "Clients" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "enabled": { "type": "boolean" } }, "required": [ "name", "enabled" ], "additionalProperties": false } } } } } }, "/api/v1/clients/{clientId}/exports": { "post": { "operationId": "post__clients_clientId_exports", "summary": "Create an immutable client delivery manifest", "tags": [ "Clients" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "manifestSha256": { "type": "string" }, "manifest": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "required": [ "id", "manifestSha256", "manifest" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "type": "object", "properties": { "topicUid": { "type": "string", "maxLength": 256 }, "expectedSelectionRevision": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "topicUid", "expectedSelectionRevision" ], "additionalProperties": false }, "maxItems": 100 } }, "required": [ "topics" ], "additionalProperties": false } } } } } }, "/api/v1/exports/{exportId}": { "get": { "operationId": "get__exports_exportId", "summary": "Get a saved client export manifest", "tags": [ "Clients" ], "description": "Minimum role: OWNER. Required key scopes: read, paths:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "exportId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "client_id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "item_count": { "type": "integer", "minimum": 0 }, "manifest_sha256": { "type": "string" }, "manifest_json": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "client_id", "item_count", "manifest_sha256", "manifest_json", "created_at" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/memberships/{identityId}": { "put": { "operationId": "put__memberships_identityId", "summary": "Update an existing workspace member", "tags": [ "Administration" ], "description": "Changes an existing Genomics membership. New global identities are created through the central dashboard identity service.\n\nMinimum role: ADMIN. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "identityId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "identityId": { "type": "string" }, "version": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." } }, "required": [ "identityId", "version" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "string", "pattern": "^[0-9]+$" }, "role": { "type": "string", "enum": [ "REVIEWER", "OWNER", "ADMIN" ] }, "enabled": { "type": "boolean" } }, "required": [ "expectedVersion", "role", "enabled" ], "additionalProperties": false } } } } } }, "/api/v1/preferences": { "get": { "operationId": "get__preferences", "summary": "Get your table preferences", "tags": [ "Preferences" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "column_order_json": { "type": "array", "items": { "type": "string" } }, "hidden_columns_json": { "type": "array", "items": { "type": "string" } } }, "required": [ "column_order_json", "hidden_columns_json" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "put__preferences", "summary": "Save your table preferences", "tags": [ "Preferences" ], "description": "Minimum role: REVIEWER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "columnOrder": { "type": "array", "items": { "type": "string" } }, "hiddenColumns": { "type": "array", "items": { "type": "string" } } }, "required": [ "columnOrder", "hiddenColumns" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "columnOrder": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 100 }, "hiddenColumns": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 100 } }, "required": [ "columnOrder", "hiddenColumns" ], "additionalProperties": false } } } } } }, "/api/v1/bugs/{bugId}": { "put": { "operationId": "put__bugs_bugId", "summary": "Resolve or reopen a bug report", "tags": [ "Support" ], "description": "Minimum role: ADMIN. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "bugId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OPEN", "RESOLVED" ] } }, "required": [ "status" ], "additionalProperties": false } } } } } }, "/api/v1/analytics": { "get": { "operationId": "get__analytics", "summary": "Get task counts and model measurement aggregates", "tags": [ "Measurements" ], "description": "Minimum role: REVIEWER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "workflow_status": { "type": "string" }, "decision": { "type": "string" }, "disposition": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "workflow_status", "decision", "disposition", "count" ], "additionalProperties": true } }, "measurements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } } }, "required": [ "tasks", "measurements" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/topics/{topicUid}/revisions/{versionId}/notes": { "put": { "operationId": "put__topics_topicUid_revisions_versionId_notes", "summary": "Update revision notes", "tags": [ "Revisions" ], "description": "Minimum role: REVIEWER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "maxLength": 10000 } }, "required": [ "notes" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/revisions/{versionId}/artifacts": { "post": { "operationId": "post__topics_topicUid_revisions_versionId_artifacts", "summary": "Reserve an immutable ZIP upload", "tags": [ "Revisions" ], "description": "Minimum role: REVIEWER. Required key scopes: write, files:write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "sha256": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 } }, "required": [ "id", "sha256", "bytes" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "FULL_SUBMISSION", "CLIENT_PACKAGE" ] }, "filename": { "type": "string", "maxLength": 184 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "bytes": { "type": "integer", "minimum": 1, "maximum": 104857600 } }, "required": [ "kind", "filename", "sha256", "bytes" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/revisions/{versionId}/artifacts/{artifactId}": { "put": { "operationId": "put__topics_topicUid_revisions_versionId_artifacts_artifactId", "summary": "Upload the reserved ZIP and verify its SHA-256", "tags": [ "Revisions" ], "description": "Minimum role: REVIEWER. Required key scopes: write, files:write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } } } }, "/api/v1/topics/{topicUid}/revisions/{versionId}/finalize": { "post": { "operationId": "post__topics_topicUid_revisions_versionId_finalize", "summary": "Finalize a complete published revision", "tags": [ "Revisions" ], "description": "Wait for the client package publication job before finalizing. Replacing only one ZIP inherits the other deliverable from the selected base. Stale selections return 409.\n\nMinimum role: REVIEWER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "maxLength": 10000 }, "expectedSelectionRevision": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "notes", "expectedSelectionRevision" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/revisions/{versionId}/cancel": { "post": { "operationId": "post__topics_topicUid_revisions_versionId_cancel", "summary": "Cancel a draft without deleting its files", "tags": [ "Revisions" ], "description": "Minimum role: REVIEWER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "reason" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/salvages": { "post": { "operationId": "post__topics_topicUid_salvages", "summary": "Start a forward-only report repair", "tags": [ "Repairs" ], "description": "Minimum role: OWNER. Required key scopes: write, files:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaignId": { "type": "string", "maxLength": 256 }, "resultKey": { "type": "string", "maxLength": 1024 }, "notes": { "type": "string", "maxLength": 10000 } }, "required": [ "campaignId", "resultKey", "notes" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/salvages/{salvageId}/report": { "post": { "operationId": "post__topics_topicUid_salvages_salvageId_report", "summary": "Bind the repaired PDF from a verified full ZIP", "tags": [ "Repairs" ], "description": "Minimum role: OWNER. Required key scopes: write, files:write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "salvageId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "artifactId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, "required": [ "artifactId" ], "additionalProperties": false } } } } } }, "/api/v1/topics/{topicUid}/salvages/{salvageId}/complete": { "post": { "operationId": "post__topics_topicUid_salvages_salvageId_complete", "summary": "Complete the repair with selection checks", "tags": [ "Repairs" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "topicUid", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "salvageId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Committed operation receipt. Includes the affected record ID and updated state; retries return the same receipt." } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedDraftRevision": { "type": "string", "pattern": "^[0-9]+$" }, "expectedSelectionRevision": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "expectedDraftRevision", "expectedSelectionRevision" ], "additionalProperties": false } } } } } }, "/api/v1/files/reports/{recordId}/download": { "get": { "operationId": "get__files_reports_recordId_download", "summary": "Download verified reports bytes", "tags": [ "Files" ], "description": "Minimum role: REVIEWER. Required key scopes: files:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/files/artifacts/{recordId}/download": { "get": { "operationId": "get__files_artifacts_recordId_download", "summary": "Download verified artifacts bytes", "tags": [ "Files" ], "description": "Minimum role: OWNER. Required key scopes: files:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/files/revisions/{recordId}/download": { "get": { "operationId": "get__files_revisions_recordId_download", "summary": "Download verified revisions bytes", "tags": [ "Files" ], "description": "Minimum role: REVIEWER. Required key scopes: files:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/publications/{publicationId}/download": { "get": { "operationId": "get__publications_publicationId_download", "summary": "Download a verified client package ZIP", "tags": [ "Files" ], "description": "Minimum role: REVIEWER. Required key scopes: files:read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "publicationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sync": { "get": { "operationId": "get__sync", "summary": "Get import, pass-rate and sync health", "tags": [ "Automation" ], "description": "Minimum role: OWNER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "imports": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "state", "count" ], "additionalProperties": true } }, "cursors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } } }, "required": [ "jobs", "imports", "cursors", "issues" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__sync", "summary": "Queue report, topic, Astra/rerun or measurement reconciliation", "tags": [ "Automation" ], "description": "Omit sourceKey to scan changed R2 objects. For reports supply runs/.../result.json; for Astra and other reruns use minos-evals-pass-runs/.../SUMMARY.json. Importing a report always queues its original measurements atomically. Jobs deduplicate and verify immutable evidence before committing.\n\nMinimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "state": { "const": "PENDING" } }, "required": [ "jobId", "state" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "reports", "reruns", "topics", "measurements" ] }, "sourceKey": { "type": "string", "maxLength": 1024 } }, "required": [ "source" ], "additionalProperties": false } } } } } }, "/api/v1/operations/jobs": { "get": { "operationId": "get__operations_jobs", "summary": "List jobs with cursor pagination", "tags": [ "Automation" ], "description": "Minimum role: OWNER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCEEDED", "FAILED" ] }, "attempts": { "type": "integer", "minimum": 0 }, "max_attempts": { "type": "integer", "minimum": 0 }, "available_at": { "type": "string", "format": "date-time" }, "last_error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "state", "attempts", "max_attempts", "available_at", "last_error_code", "created_at", "updated_at", "completed_at" ], "additionalProperties": true } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/operations/imports": { "get": { "operationId": "get__operations_imports", "summary": "List imports with cursor pagination", "tags": [ "Automation" ], "description": "Minimum role: OWNER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source_bucket": { "type": "string" }, "source_key": { "type": "string" }, "source_sha256": { "type": "string" }, "campaign_id": { "type": "string" }, "report_id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "state": { "type": "string", "enum": [ "IMPORTED", "MEASUREMENTS_PENDING", "COMPLETE", "NEEDS_ATTENTION" ] }, "last_error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imported_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "source_bucket", "source_key", "source_sha256", "campaign_id", "report_id", "state", "last_error_code", "imported_at", "updated_at" ], "additionalProperties": true } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/operations/issues": { "get": { "operationId": "get__operations_issues", "summary": "List issues with cursor pagination", "tags": [ "Automation" ], "description": "Minimum role: OWNER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/operations/audit": { "get": { "operationId": "get__operations_audit", "summary": "List audit with cursor pagination", "tags": [ "Automation" ], "description": "Minimum role: ADMIN. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "next" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{jobId}": { "get": { "operationId": "get__jobs_jobId", "summary": "Get a job and all attempt outcomes", "tags": [ "Automation" ], "description": "Minimum role: OWNER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCEEDED", "FAILED" ] }, "attempts": { "type": "integer", "minimum": 0 }, "max_attempts": { "type": "integer", "minimum": 0 }, "available_at": { "type": "string", "format": "date-time" }, "last_error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "payload": { "type": "object", "additionalProperties": true, "description": "Stored workspace record; historical nullable fields are preserved." }, "lease_until": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "state", "attempts", "max_attempts", "available_at", "last_error_code", "created_at", "updated_at", "completed_at" ], "additionalProperties": true }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer", "minimum": 0 }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "attempt", "started_at", "finished_at", "outcome", "error_code" ], "additionalProperties": true } } }, "required": [ "job", "attempts" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{jobId}/retry": { "post": { "operationId": "post__jobs_jobId_retry", "summary": "Retry failed work while retaining its attempt history", "tags": [ "Automation" ], "description": "Minimum role: OWNER. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Decimal PostgreSQL bigint, encoded as a string." }, "state": { "const": "PENDING" } }, "required": [ "jobId", "state" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } } }, "/api/v1/runtime": { "get": { "operationId": "get__runtime", "summary": "Get maintenance and worker heartbeat state", "tags": [ "Administration" ], "description": "Minimum role: OWNER. Required key scopes: read.", "security": [ { "ApiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "runtime": { "type": "object", "properties": { "workers_enabled": { "type": "boolean" }, "source_bucket": { "type": "string" }, "source_prefix": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "workers_enabled", "source_bucket", "source_prefix", "updated_at" ], "additionalProperties": true }, "authority": { "type": "object", "properties": { "active": { "type": "boolean" }, "writes_frozen": { "type": "boolean" } }, "required": [ "active", "writes_frozen" ], "additionalProperties": true }, "processes": { "type": "array", "items": { "type": "object", "properties": { "process": { "type": "string" }, "build": { "type": "string" }, "last_seen": { "type": "string", "format": "date-time" }, "state": { "type": "string" }, "healthy": { "type": "boolean" } }, "required": [ "process", "build", "last_seen", "state", "healthy" ], "additionalProperties": true } } }, "required": [ "runtime", "authority", "processes" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runtime/workers": { "put": { "operationId": "put__runtime_workers", "summary": "Pause or resume background processing", "tags": [ "Administration" ], "description": "Minimum role: ADMIN. Required key scopes: write.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Evidence validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or file concurrency limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance, unavailable authority or dependency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "gk_genomics_prod_.; never use a Math key." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 1000 }, "requestId": { "type": "string", "maxLength": 1000 } }, "required": [ "code", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }