{ "openapi": "3.1.0", "info": { "title": "Handover API", "version": "1.16.0", "description": "Versioned context and revision-anchored review shared by humans and agents. Browser requests use the signed-in human session; agents authenticate with a scoped bearer credential." }, "servers": [ { "url": "/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/spaces": { "get": { "operationId": "listSpaces", "summary": "List accessible company Spaces", "responses": { "200": { "description": "Accessible Spaces" } } }, "post": { "operationId": "createSpace", "summary": "Create a product, department, customer, project, initiative, or custom Space", "responses": { "201": { "description": "Space created" } } } }, "/spaces/{space}": { "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getSpace", "summary": "Inspect a Space and its members", "responses": { "200": { "description": "Space detail" } } }, "put": { "operationId": "updateSpace", "summary": "Update or archive a Space", "responses": { "200": { "description": "Updated Space" } } }, "delete": { "operationId": "deleteSpace", "summary": "Delete an empty non-default Space", "responses": { "204": { "description": "Space deleted" } } } }, "/spaces/{space}/resources": { "get": { "operationId": "listSpaceResources", "summary": "List versioned knowledge and assets", "responses": { "200": { "description": "Space Resources" } } }, "post": { "operationId": "createSpaceResource", "summary": "Create maintained knowledge or an asset", "responses": { "201": { "description": "Resource created" } } } }, "/spaces/{space}/resources/{resource}": { "get": { "operationId": "getSpaceResource", "summary": "Inspect Resource versions", "responses": { "200": { "description": "Resource detail" } } }, "put": { "operationId": "updateSpaceResource", "summary": "Append a Resource version with optimistic concurrency", "responses": { "200": { "description": "Updated Resource" }, "409": { "description": "Stale current version" } } }, "delete": { "operationId": "deleteSpaceResource", "summary": "Delete a Resource", "responses": { "204": { "description": "Resource deleted" } } } }, "/spaces/{space}/requests": { "get": { "operationId": "listSpaceRequests", "summary": "List Space Requests", "responses": { "200": { "description": "Space Requests" } } }, "post": { "operationId": "createSpaceRequest", "summary": "Create a Space Request", "responses": { "201": { "description": "Request created" } } } }, "/spaces/{space}/health": { "get": { "operationId": "getSpaceHealth", "summary": "Score Space context health", "responses": { "200": { "description": "Health score, dimensions, counts, and recommendations" } } } }, "/spaces/{space}/okf": { "get": { "operationId": "exportSpaceOkf", "summary": "Export Space knowledge and assets as OKF", "responses": { "200": { "description": "OKF JSON or tar bundle" } } }, "post": { "operationId": "importSpaceOkf", "summary": "Additively import a Space OKF bundle", "responses": { "200": { "description": "Idempotent import" }, "201": { "description": "Imported Resource versions" } } } }, "/publications": { "get": { "operationId": "listPublications", "summary": "List stable published report projections", "responses": { "200": { "description": "Workspace publications" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/handovers/{id}/publication": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^hov_" } } ], "get": { "operationId": "getPublication", "summary": "Inspect a handover publication", "responses": { "200": { "description": "Publication or null" } } }, "put": { "operationId": "publishHandover", "summary": "Create or update a stable report projection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationInput" } } } }, "responses": { "200": { "description": "Published report" }, "409": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "unpublishHandover", "summary": "Remove a stable report projection", "responses": { "204": { "description": "Publication removed" } } } }, "/handovers/{id}/okf": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^hov_" } } ], "get": { "operationId": "exportOkf", "summary": "Export an Open Knowledge Format bundle", "parameters": [ { "name": "revision", "in": "query", "schema": { "type": "string", "pattern": "^rev_" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "tar", "json" ], "default": "tar" } } ], "responses": { "200": { "description": "OKF tar archive or JSON bundle", "content": { "application/x-tar": {}, "application/json": { "schema": { "$ref": "#/components/schemas/OkfBundleEnvelope" } } } } } }, "post": { "operationId": "importOkf", "summary": "Import OKF as an immutable revision", "requestBody": { "required": true, "content": { "application/x-tar": {}, "application/json": { "schema": { "$ref": "#/components/schemas/OkfBundle" } } } }, "responses": { "200": { "description": "Bundle was already imported" }, "201": { "description": "Bundle imported" } } } }, "/folders": { "get": { "operationId": "listFolders", "summary": "List workspace folders", "responses": { "200": { "description": "Folders and visible handover counts" } } }, "post": { "operationId": "createFolder", "summary": "Create a workspace folder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderInput" } } } }, "responses": { "201": { "description": "Folder created" } } } }, "/folders/{slug}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getFolder", "summary": "Read a folder and its visible handovers", "responses": { "200": { "description": "Folder detail" } } }, "put": { "operationId": "updateFolder", "summary": "Update a folder", "responses": { "200": { "description": "Folder updated" } } }, "delete": { "operationId": "deleteFolder", "summary": "Delete a non-default folder", "responses": { "204": { "description": "Folder deleted" } } } }, "/folders/{slug}/handovers": { "post": { "operationId": "addFolderHandovers", "summary": "Add handovers or Reporter report slugs to a folder", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Membership changes" } } } }, "/reports": { "get": { "operationId": "listReporterContexts", "summary": "List Reporter-compatible published reports", "responses": { "200": { "description": "Published reports" } } }, "post": { "operationId": "deployReporterContext", "summary": "Publish a Reporter-compatible folder payload", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReporterDeployInput" } } } }, "responses": { "201": { "description": "Report published" } } } }, "/reports/{slug}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getReporterContext", "summary": "Inspect a Reporter-compatible report", "responses": { "200": { "description": "Report descriptor" } } }, "put": { "operationId": "updateReporterContext", "summary": "Replace report files with a new immutable revision", "responses": { "200": { "description": "Report republished" } } } }, "/reports/{slug}/pull": { "post": { "operationId": "pullReporterContext", "summary": "Pull report files with binary-safe encodings", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report files and pull manifest data" } } } }, "/me": { "get": { "operationId": "getCurrentIdentity", "summary": "Read the authenticated identity and organization context", "responses": { "200": { "description": "Authenticated identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Error" } } } }, "/organization": { "get": { "operationId": "getOrganizationProfile", "summary": "Read the current company profile", "responses": { "200": { "description": "Organization profile" } } }, "put": { "operationId": "updateOrganizationProfile", "summary": "Update the company name as an organization owner", "responses": { "200": { "description": "Updated organization profile" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/activity": { "get": { "operationId": "listActivity", "summary": "List organization-scoped audit events", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Recent activity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityEnvelope" } } } }, "403": { "$ref": "#/components/responses/Error" } } } }, "/agents": { "get": { "operationId": "listAgents", "summary": "List agent identities and their credential metadata", "responses": { "200": { "description": "Agent identities" }, "403": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createAgentCredential", "summary": "Create an agent identity and one scoped credential", "description": "The bearer credential is returned once. Handover stores only its SHA-256 digest.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgent" } } } }, "responses": { "201": { "description": "Agent identity and one-time bearer credential" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/tokens/{id}": { "delete": { "operationId": "revokeAgentCredential", "summary": "Immediately revoke an agent credential", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tok_" } } ], "responses": { "204": { "description": "Credential revoked" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/handovers": { "get": { "operationId": "listHandovers", "summary": "Discover active handovers", "parameters": [ { "name": "q", "in": "query", "description": "Search across titles, summaries, revision notes, authors, artifact names, continuation briefs, and indexed text artifact content.", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "description": "Hybrid combines lexical and semantic ranks. Hybrid falls back to lexical with modeUsed set accordingly when embeddings are unavailable.", "schema": { "type": "string", "enum": [ "hybrid", "semantic", "lexical" ], "default": "hybrid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Lifecycle collection to list or search.", "schema": { "type": "string", "enum": [ "active", "archived", "trashed" ], "default": "active" } } ], "responses": { "200": { "description": "A page of handovers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverPageEnvelope" } } } } } }, "post": { "operationId": "createHandover", "summary": "Create a handover and its first immutable revision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHandover" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/HandoverForm" } } } }, "responses": { "201": { "description": "Created handover", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" } } } }, "/search/semantic": { "get": { "operationId": "getSemanticSearchStatus", "summary": "Read semantic provider and derived-index status", "responses": { "200": { "description": "Semantic search status" } } }, "post": { "operationId": "manageSemanticIndex", "summary": "Process or rebuild the derived semantic index", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "process", "rebuild" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } } } } }, "responses": { "200": { "description": "Semantic index operation result" }, "403": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/handovers/{id}": { "get": { "operationId": "getHandover", "summary": "Read a handover snapshot and its history", "parameters": [ { "$ref": "#/components/parameters/HandoverId" }, { "name": "revision", "in": "query", "description": "Read a specific immutable revision instead of the current one.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Handover snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverEnvelope" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "purgeHandover", "summary": "Permanently purge a trashed handover after retention", "description": "Metadata is removed permanently. Content-addressed object bytes are deleted only when no remaining artifact references them.", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "responses": { "204": { "description": "Handover purged" }, "409": { "description": "The handover is not trashed or its retention window remains active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/handovers/{id}/access": { "get": { "operationId": "getHandoverAccess", "summary": "Read visibility, explicit grants, and eligible organization participants", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "responses": { "200": { "description": "Handover access state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverAccessEnvelope" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateHandoverAccess", "summary": "Set workspace or restricted visibility and replace explicit grants", "description": "Organization owners, the handover creator, and explicitly granted access owners can manage sharing.", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHandoverAccess" } } } }, "responses": { "200": { "description": "Updated handover access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverAccessEnvelope" } } } }, "403": { "$ref": "#/components/responses/Error" } } } }, "/handovers/{id}/lifecycle": { "post": { "operationId": "updateHandoverLifecycle", "summary": "Archive, restore, or move a handover to trash", "description": "Trash is reversible for 30 days. Trashed handovers cannot receive revisions.", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverLifecycleAction" } } } }, "responses": { "200": { "description": "Updated handover snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverEnvelope" } } } }, "403": { "$ref": "#/components/responses/Error" } } } }, "/handovers/{id}/revisions": { "post": { "operationId": "appendRevision", "summary": "Continue a handover with a new immutable snapshot", "description": "Artifacts omitted from the request are inherited from the current revision. An artifact with the same case-insensitive name replaces the previous artifact in the new snapshot.", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendRevision" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RevisionForm" } } } }, "responses": { "201": { "description": "Updated handover", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverEnvelope" } } } }, "409": { "description": "The expected revision is stale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/handovers/{id}/thread": { "get": { "operationId": "getHandoverThread", "summary": "Read comments, mentions, assignments, and collaborators", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "responses": { "200": { "description": "Handover collaboration thread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverThreadEnvelope" } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/handovers/{id}/comments": { "post": { "operationId": "addHandoverComment", "summary": "Append a comment and notify explicit mentions", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddComment" } } } }, "responses": { "201": { "description": "Updated collaboration thread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverThreadEnvelope" } } } }, "403": { "$ref": "#/components/responses/Error" } } } }, "/handovers/{id}/annotations": { "get": { "operationId": "listHandoverAnnotations", "summary": "List revision-anchored artifact comments", "parameters": [ { "$ref": "#/components/parameters/HandoverId" }, { "name": "artifactId", "in": "query", "schema": { "type": "string", "pattern": "^art_" } }, { "name": "revisionId", "in": "query", "schema": { "type": "string", "pattern": "^rev_" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "resolved", "stale" ] } } ], "responses": { "200": { "description": "Filtered artifact annotations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverThreadEnvelope" } } } } } }, "post": { "operationId": "addHandoverAnnotation", "summary": "Add a comment anchored to an immutable artifact revision", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAnnotation" } } } }, "responses": { "201": { "description": "Updated collaboration thread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverThreadEnvelope" } } } } } } }, "/handovers/{id}/comments/{commentId}": { "patch": { "operationId": "updateHandoverComment", "summary": "Edit, resolve, or reopen a comment", "parameters": [ { "$ref": "#/components/parameters/HandoverId" }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cmt_" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateComment" } } } }, "responses": { "200": { "description": "Updated collaboration thread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverThreadEnvelope" } } } }, "403": { "$ref": "#/components/responses/Error" } } } }, "/handovers/{id}/assignments": { "put": { "operationId": "setHandoverAssignments", "summary": "Replace the open assignments for a handover", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAssignments" } } } }, "responses": { "200": { "description": "Updated collaboration thread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverThreadEnvelope" } } } } } } }, "/handovers/{id}/assignments/{assignmentId}": { "patch": { "operationId": "updateHandoverAssignment", "summary": "Complete or reopen one assignment", "parameters": [ { "$ref": "#/components/parameters/HandoverId" }, { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asn_" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "complete", "reopen" ] } } } } } }, "responses": { "200": { "description": "Updated collaboration thread" } } } }, "/connectors": { "get": { "operationId": "listConnectorDestinations", "summary": "List provider-neutral export destinations", "responses": { "200": { "description": "Configured destinations" } } }, "post": { "operationId": "createConnectorDestination", "summary": "Create a GitHub or signed HTTP export destination", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectorDestination" } } } }, "responses": { "201": { "description": "Created destination" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/connectors/{id}": { "patch": { "operationId": "updateConnectorDestination", "summary": "Enable or disable an export destination", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^dst_" } } ], "responses": { "200": { "description": "Updated destination" } } } }, "/imports": { "get": { "operationId": "getImportState", "summary": "List provider-neutral import sources and durable history", "responses": { "200": { "description": "Configured sources and recent import jobs" }, "403": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createConnectorSource", "summary": "Create a GitHub folder or signed HTTP import source", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectorSource" } } } }, "responses": { "201": { "description": "Created import source" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/imports/{id}": { "patch": { "operationId": "updateConnectorSource", "summary": "Enable or disable an import source", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^src_" } } ], "responses": { "200": { "description": "Updated import source" } } } }, "/imports/{id}/run": { "post": { "operationId": "queueGitHubImport", "summary": "Import the current pinned version of a GitHub source", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^src_" } } ], "responses": { "202": { "description": "Queued or existing import state" } } } }, "/imports/http/{id}": { "post": { "operationId": "receiveHttpImport", "summary": "Receive idempotent context through a signed source endpoint", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^src_" } }, { "name": "x-handover-signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[a-f0-9]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpImportPayload" } } } }, "responses": { "202": { "description": "Import accepted or previously processed" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/handovers/{id}/exports": { "get": { "operationId": "getHandoverExportState", "summary": "List destinations and durable delivery history", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "responses": { "200": { "description": "Export state" } } }, "post": { "operationId": "queueHandoverExport", "summary": "Queue an idempotent one-way revision export", "description": "The same destination and immutable revision resolve to one durable job. Provider delivery never changes Handover revision history.", "parameters": [ { "$ref": "#/components/parameters/HandoverId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueHandoverExport" } } } }, "responses": { "202": { "description": "Queued or existing export state" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/handovers/{id}/exports/{jobId}/retry": { "post": { "operationId": "retryHandoverExport", "summary": "Retry a failed or dead-lettered export", "parameters": [ { "$ref": "#/components/parameters/HandoverId" }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^exp_" } } ], "responses": { "202": { "description": "Updated export state" } } } }, "/exports/run": { "post": { "operationId": "processDueExports", "summary": "Process due export retries for the organization", "responses": { "200": { "description": "Processed delivery jobs" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/notifications": { "get": { "operationId": "listNotifications", "summary": "List the authenticated identity's mention and assignment inbox", "responses": { "200": { "description": "Personal notifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPageEnvelope" } } } } } }, "put": { "operationId": "markNotificationsRead", "summary": "Mark selected or all personal notifications as read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkNotificationsRead" } } } }, "responses": { "200": { "description": "Updated personal notifications" } } } }, "/storage": { "get": { "operationId": "getStorageStatus", "summary": "Read the organization's storage-cell and residency placement", "responses": { "200": { "description": "Current tenant placement and configured cells", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageStatusEnvelope" } } } }, "403": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/operations": { "get": { "operationId": "getOperationsStatus", "summary": "Read organization-scoped queue, scheduler, retention, and recovery health", "responses": { "200": { "description": "Current operational status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsStatusEnvelope" } } } }, "403": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "manageBackgroundJobs", "summary": "Run due work, requeue stopped jobs, or start a recovery operation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "action" ], "properties": { "action": { "const": "run" } } }, { "type": "object", "required": [ "action", "queue" ], "properties": { "action": { "const": "retry" }, "queue": { "type": "string", "enum": [ "imports", "exports", "semantic", "all" ] } } }, { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "backup", "verify" ] } } } ] } } } }, "responses": { "200": { "description": "Stopped jobs requeued" }, "202": { "description": "Bounded background run completed" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/reliability/backups/{id}": { "get": { "operationId": "downloadBackupManifest", "summary": "Download an organization backup manifest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rel_" } } ], "responses": { "200": { "description": "Backup manifest", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/artifacts/{id}": { "get": { "operationId": "downloadArtifact", "summary": "Read or download an artifact body", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artifact bytes" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/analytics/events": { "post": { "operationId": "recordAcquisitionEvent", "summary": "Record a privacy-safe acquisition milestone", "description": "Accepts an allowlisted event and limited campaign attribution. The service does not store IP addresses, user agents, search queries, handover metadata, or artifact content in acquisition analytics.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionEventInput" } } } }, "responses": { "202": { "description": "Event accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionAcceptedEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" } } } }, "/analytics/overview": { "get": { "operationId": "getAcquisitionOverview", "summary": "Get the organization acquisition and activation funnel", "description": "Returns aggregates only and requires organization owner access.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 } } ], "responses": { "200": { "description": "Organization acquisition overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionOverviewEnvelope" } } } }, "403": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "hnd_tok__", "description": "Scoped agent credential. Create it from the People & agents view; the secret is shown once." } }, "parameters": { "HandoverId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^hov_" } } }, "responses": { "Error": { "description": "Request error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "JobQueueCounts": { "type": "object", "required": [ "pending", "running", "failed", "deadLetter" ], "properties": { "pending": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "deadLetter": { "type": "integer", "minimum": 0 } } }, "OperationsStatusEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "scheduler", "imports", "exports", "semantic", "retention", "reliability" ], "properties": { "scheduler": { "type": "object", "required": [ "schedule", "status", "lastStartedAt", "lastCompletedAt", "lastErrorMessage" ], "properties": { "schedule": { "type": "string" }, "status": { "type": "string", "enum": [ "idle", "running", "succeeded", "failed", "never_run" ] }, "lastStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCompletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastErrorMessage": { "type": [ "string", "null" ] } } }, "exports": { "$ref": "#/components/schemas/JobQueueCounts" }, "imports": { "$ref": "#/components/schemas/JobQueueCounts" }, "semantic": { "allOf": [ { "$ref": "#/components/schemas/JobQueueCounts" }, { "type": "object", "required": [ "available", "indexed" ], "properties": { "available": { "type": "boolean" }, "indexed": { "type": "integer", "minimum": 0 } } } ] }, "retention": { "type": "object", "required": [ "scheduledForPurge", "dueForPurge" ], "properties": { "scheduledForPurge": { "type": "integer", "minimum": 0 }, "dueForPurge": { "type": "integer", "minimum": 0 } } }, "reliability": { "type": "object", "required": [ "schedule", "lastBackupAt", "lastVerifiedAt", "active", "history" ], "properties": { "schedule": { "type": "object", "required": [ "backups", "verification" ], "properties": { "backups": { "type": "string" }, "verification": { "type": "string" } } }, "lastBackupAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "active": { "oneOf": [ { "$ref": "#/components/schemas/ReliabilityRun" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/ReliabilityRun" } } } } } } } }, "ReliabilityRun": { "type": "object", "required": [ "id", "kind", "status", "backupRunId", "manifestAvailable", "totalObjects", "totalBytes", "checkedObjects", "missingObjects", "corruptObjects", "requestedByName", "startedAt", "completedAt" ], "properties": { "id": { "type": "string", "pattern": "^rel_" }, "kind": { "type": "string", "enum": [ "backup", "verification" ] }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed" ] }, "backupRunId": { "type": [ "string", "null" ] }, "manifestAvailable": { "type": "boolean" }, "totalObjects": { "type": "integer", "minimum": 0 }, "totalBytes": { "type": "integer", "minimum": 0 }, "checkedObjects": { "type": "integer", "minimum": 0 }, "missingObjects": { "type": "integer", "minimum": 0 }, "corruptObjects": { "type": "integer", "minimum": 0 }, "requestedByName": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "CreateConnectorDestination": { "type": "object", "required": [ "displayName", "provider", "config" ], "properties": { "displayName": { "type": "string", "maxLength": 120 }, "workspaceId": { "type": "string", "pattern": "^wsp_" }, "provider": { "type": "string", "enum": [ "github", "http" ] }, "config": { "oneOf": [ { "type": "object", "title": "GitHub destination", "required": [ "owner", "repository" ], "properties": { "owner": { "type": "string" }, "repository": { "type": "string" }, "branch": { "type": "string", "default": "main" }, "basePath": { "type": "string", "default": "handovers" } } }, { "type": "object", "title": "Signed HTTP destination", "required": [ "url", "secretEnv" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS receiver endpoint." }, "secretEnv": { "type": "string", "pattern": "^HANDOVER_WEBHOOK_[A-Z0-9_]+$", "description": "Runtime environment key containing the HMAC secret. The secret value is never stored in destination metadata." } } } ] } } }, "CreateConnectorSource": { "type": "object", "required": [ "displayName", "provider", "config" ], "properties": { "displayName": { "type": "string", "maxLength": 120 }, "workspaceId": { "type": "string", "pattern": "^wsp_" }, "provider": { "type": "string", "enum": [ "github", "http" ] }, "config": { "oneOf": [ { "type": "object", "title": "GitHub folder source", "required": [ "owner", "repository" ], "properties": { "owner": { "type": "string" }, "repository": { "type": "string" }, "branch": { "type": "string", "default": "main" }, "path": { "type": "string", "default": "" } } }, { "type": "object", "title": "Signed HTTP source", "required": [ "secretEnv" ], "properties": { "secretEnv": { "type": "string", "pattern": "^HANDOVER_IMPORT_[A-Z0-9_]*SECRET[A-Z0-9_]*$", "description": "Runtime environment key containing the HMAC secret. The secret value is never stored in source metadata." } } } ] } } }, "HttpImportPayload": { "allOf": [ { "$ref": "#/components/schemas/CreateHandover" }, { "type": "object", "required": [ "externalId", "providerRef" ], "properties": { "schemaVersion": { "type": "integer", "const": 1 }, "externalId": { "type": "string", "maxLength": 500 }, "providerRef": { "type": "string", "maxLength": 500 } } } ] }, "QueueHandoverExport": { "type": "object", "required": [ "destinationId" ], "properties": { "destinationId": { "type": "string", "pattern": "^dst_" }, "revisionId": { "type": "string", "pattern": "^rev_" } } }, "AddComment": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 }, "mentionPrincipalIds": { "type": "array", "maxItems": 20, "items": { "type": "string", "pattern": "^prn_" } }, "target": { "oneOf": [ { "$ref": "#/components/schemas/AnnotationTarget" }, { "type": "null" } ] } } }, "AnnotationSelector": { "type": "object", "required": [ "exact" ], "properties": { "exact": { "type": "string", "minLength": 1, "maxLength": 4000 }, "prefix": { "type": "string", "maxLength": 500 }, "suffix": { "type": "string", "maxLength": 500 }, "startOffset": { "type": "integer", "minimum": 0 }, "endOffset": { "type": "integer", "minimum": 0 }, "startLine": { "type": "integer", "minimum": 1 }, "endLine": { "type": "integer", "minimum": 1 } } }, "AnnotationTarget": { "type": "object", "required": [ "revisionId", "artifactId", "targetKind", "selector" ], "properties": { "revisionId": { "type": "string", "pattern": "^rev_" }, "artifactId": { "type": "string", "pattern": "^art_" }, "targetKind": { "type": "string", "enum": [ "text", "code", "html" ] }, "selector": { "$ref": "#/components/schemas/AnnotationSelector" } } }, "AddAnnotation": { "allOf": [ { "$ref": "#/components/schemas/AddComment" }, { "type": "object", "required": [ "target" ], "properties": { "target": { "$ref": "#/components/schemas/AnnotationTarget" } } } ] }, "UpdateComment": { "type": "object", "minProperties": 1, "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 }, "mentionPrincipalIds": { "type": "array", "maxItems": 20, "items": { "type": "string", "pattern": "^prn_" } }, "target": { "oneOf": [ { "$ref": "#/components/schemas/AnnotationTarget" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "open", "resolved" ] }, "resolvedRevisionId": { "oneOf": [ { "type": "string", "pattern": "^rev_" }, { "type": "null" } ] } } }, "SetAssignments": { "type": "object", "required": [ "principalIds" ], "properties": { "principalIds": { "type": "array", "maxItems": 20, "items": { "type": "string", "pattern": "^prn_" } } } }, "MarkNotificationsRead": { "type": "object", "properties": { "all": { "type": "boolean" }, "ids": { "type": "array", "maxItems": 100, "items": { "type": "string", "pattern": "^ntf_" } } } }, "HandoverThreadEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "handoverId", "canWrite", "participants", "comments", "assignments" ], "additionalProperties": true } } }, "NotificationPageEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "items", "unreadCount" ], "additionalProperties": true } } }, "ArtifactInput": { "type": "object", "required": [ "name", "content" ], "properties": { "name": { "type": "string" }, "mediaType": { "type": "string", "default": "application/octet-stream" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ], "default": "utf8" } } }, "RevisionInput": { "type": "object", "properties": { "note": { "type": "string" }, "brief": { "$ref": "#/components/schemas/ContinuationBrief" }, "artifactMode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" }, "artifacts": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ArtifactInput" } } } }, "CreateHandover": { "allOf": [ { "$ref": "#/components/schemas/RevisionInput" }, { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "summary": { "type": "string" } } } ] }, "AppendRevision": { "allOf": [ { "$ref": "#/components/schemas/RevisionInput" }, { "type": "object", "properties": { "expectedRevisionId": { "type": "string" } } } ] }, "RevisionForm": { "type": "object", "properties": { "note": { "type": "string" }, "brief": { "type": "string", "description": "JSON-encoded ContinuationBrief." }, "artifactName": { "type": "string" }, "mediaType": { "type": "string" }, "content": { "type": "string" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" } }, "expectedRevisionId": { "type": "string" } } }, "HandoverForm": { "allOf": [ { "$ref": "#/components/schemas/RevisionForm" }, { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "summary": { "type": "string" } } } ] }, "CreateAgent": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "handover:read", "handover:write", "audit:read" ] } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ContinuationStep": { "type": "object", "required": [ "id", "text", "status" ], "properties": { "id": { "type": "string", "pattern": "^step_" }, "text": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done" ] } } }, "HandoverGrantInput": { "type": "object", "required": [ "principalId", "role" ], "properties": { "principalId": { "type": "string", "pattern": "^prn_" }, "role": { "type": "string", "enum": [ "viewer", "editor", "owner" ] } } }, "HandoverLifecycleAction": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "archive", "restore", "trash" ] } } }, "UpdateHandoverAccess": { "type": "object", "required": [ "visibility", "grants" ], "properties": { "visibility": { "type": "string", "enum": [ "workspace", "restricted" ] }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/HandoverGrantInput" } } } }, "HandoverAccessEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/HandoverAccess" } } }, "HandoverAccess": { "type": "object", "required": [ "handoverId", "visibility", "canManage", "participants" ], "properties": { "handoverId": { "type": "string", "pattern": "^hov_" }, "visibility": { "type": "string", "enum": [ "workspace", "restricted" ] }, "canManage": { "type": "boolean" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/HandoverAccessParticipant" } } } }, "HandoverAccessParticipant": { "type": "object", "required": [ "principalId", "displayName", "type", "organizationRole", "isCreator", "isCurrentActor" ], "properties": { "principalId": { "type": "string", "pattern": "^prn_" }, "displayName": { "type": "string" }, "type": { "type": "string", "enum": [ "human", "agent", "system" ] }, "organizationRole": { "type": "string", "enum": [ "owner", "member" ] }, "grantRole": { "type": [ "string", "null" ], "enum": [ "viewer", "editor", "owner", null ] }, "isCreator": { "type": "boolean" }, "isCurrentActor": { "type": "boolean" } } }, "ContinuationBrief": { "type": "object", "description": "An immutable, structured snapshot of what a person or agent needs to resume the work.", "properties": { "objective": { "type": "string" }, "currentState": { "type": "string" }, "decisions": { "type": "array", "items": { "type": "string" } }, "openQuestions": { "type": "array", "items": { "type": "string" } }, "nextSteps": { "type": "array", "items": { "$ref": "#/components/schemas/ContinuationStep" } } } }, "ActorEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "principalId", "organizationId", "type", "displayName", "scopes", "storage" ], "properties": { "storage": { "$ref": "#/components/schemas/StoragePlacement" } }, "additionalProperties": true } } }, "StoragePlacement": { "type": "object", "required": [ "cellId", "cellLabel", "residencyRegion", "status" ], "properties": { "cellId": { "type": "string" }, "cellLabel": { "type": "string" }, "residencyRegion": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "copying", "verifying", "cutover", "blocked" ] } } }, "StorageStatusEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "placement", "availableCells" ], "properties": { "placement": { "$ref": "#/components/schemas/StoragePlacement" }, "availableCells": { "type": "array", "items": { "type": "object", "required": [ "cellId", "cellLabel", "residencyRegion", "current" ], "properties": { "cellId": { "type": "string" }, "cellLabel": { "type": "string" }, "residencyRegion": { "type": "string" }, "current": { "type": "boolean" } } } } } } } }, "ActivityEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "action", "actorType", "actorName", "createdAt" ], "additionalProperties": true } } } }, "Handover": { "type": "object", "required": [ "id", "title", "status", "visibility", "deletedAt", "purgeAfter", "currentRevisionId", "currentRevision", "revisions" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived", "trashed" ] }, "visibility": { "type": "string", "enum": [ "workspace", "restricted" ] }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "purgeAfter": { "type": [ "string", "null" ], "format": "date-time" }, "currentRevisionId": { "type": "string" }, "currentRevision": { "type": "object", "additionalProperties": true }, "revisions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "HandoverEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Handover" } } }, "HandoverPageEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Handover" } }, "nextCursor": { "type": [ "string", "null" ] }, "modeRequested": { "type": "string", "enum": [ "hybrid", "semantic", "lexical" ] }, "modeUsed": { "type": "string", "enum": [ "hybrid", "semantic", "lexical" ] }, "semanticAvailable": { "type": "boolean" } } } } }, "PublicationInput": { "type": "object", "additionalProperties": false, "properties": { "slug": { "type": "string" }, "entryPath": { "type": "string" }, "access": { "type": "string", "enum": [ "organization", "public" ] }, "revisionMode": { "type": "string", "enum": [ "latest", "pinned" ] }, "revisionId": { "type": "string", "pattern": "^rev_" } } }, "FolderInput": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "slug": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "maxLength": 2000 } } }, "ReporterFile": { "type": "object", "additionalProperties": false, "required": [ "path", "content" ], "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "content_type": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf-8", "base64" ] } } }, "ReporterDeployInput": { "type": "object", "additionalProperties": false, "required": [ "name", "files" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "entry_file": { "type": "string" }, "access": { "type": "string", "enum": [ "organization", "public" ] }, "files": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/ReporterFile" } } } }, "OkfFile": { "type": "object", "additionalProperties": false, "required": [ "path", "encoding", "content" ], "properties": { "path": { "type": "string" }, "mediaType": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf-8", "base64" ] }, "content": { "type": "string" }, "byteSize": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string" } } }, "OkfBundle": { "type": "object", "required": [ "files" ], "properties": { "okfVersion": { "type": "string", "const": "0.1" }, "handoverId": { "type": "string" }, "revisionId": { "type": "string" }, "expectedRevisionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "merge", "replace" ] }, "files": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/OkfFile" } } } }, "OkfBundleEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OkfBundle" } } }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "AcquisitionEventInput": { "type": "object", "required": [ "eventName" ], "additionalProperties": false, "properties": { "eventName": { "type": "string", "enum": [ "page_view", "cta_clicked", "workspace_opened", "onboarding_viewed" ] }, "path": { "type": "string", "maxLength": 240 }, "pageKind": { "type": "string", "enum": [ "landing", "docs", "guide", "template", "workspace", "other" ] }, "source": { "type": "string", "maxLength": 80 }, "medium": { "type": "string", "maxLength": 80 }, "campaign": { "type": "string", "maxLength": 120 }, "referrer": { "type": "string", "format": "uri" } } }, "AcquisitionAcceptedEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean", "const": true } } } } }, "AcquisitionOverviewEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "days", "generatedAt", "funnel", "channels", "pages" ], "properties": { "days": { "type": "integer" }, "generatedAt": { "type": "string", "format": "date-time" }, "funnel": { "type": "object", "required": [ "visitors", "ctaVisitors", "signedInVisitors", "activatedPrincipals", "totalHandoversCreated" ], "properties": { "visitors": { "type": "integer" }, "ctaVisitors": { "type": "integer" }, "signedInVisitors": { "type": "integer" }, "activatedPrincipals": { "type": "integer" }, "totalHandoversCreated": { "type": "integer" } } }, "channels": { "type": "array", "items": { "type": "object", "required": [ "source", "medium", "campaign", "visitors" ], "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "visitors": { "type": "integer" } } } }, "pages": { "type": "array", "items": { "type": "object", "required": [ "path", "pageKind", "visitors", "views" ], "properties": { "path": { "type": "string" }, "pageKind": { "type": "string" }, "visitors": { "type": "integer" }, "views": { "type": "integer" } } } } } } } } } } }