{ "openapi": "3.1.0", "info": { "title": "OrcheSphere API", "version": "1.0.0", "description": "Resource-bound company API. The initial release exposes saved workspaces, connections, portals, tasks and identity-verification jobs. Provider business-record reads/writes are not implemented. OAuth issuer remains https://orchesphere.ai. Backend/native clients only; no client secret, API key, client_credentials or browser CORS contract." }, "servers": [ { "url": "https://api.orchesphere.ai" } ], "paths": { "/v1/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List assigned workspaces", "description": "Current active company assignments; verified global authority may see all company workspaces. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Workspaces" ], "security": [ { "OAuth2": [ "orchesphere.read" ] } ], "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceList" }, "example": { "workspaces": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "Example Company" } ], "page": { "limit": 200, "returned": 1, "mayHaveMore": false } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Current active company assignments; verified global authority may see all company workspaces." } }, "/v1/workspaces/{workspaceId}/connections": { "get": { "operationId": "listConnections", "summary": "List connection evidence", "description": "Provider read permission in the selected workspace/environment. Configured is not proof of live access; managed_admin entries are read-only external projections. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Connections" ], "security": [ { "OAuth2": [ "orchesphere.read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionList" }, "example": { "connections": [ { "id": "22222222-2222-4222-8222-222222222222", "version": 1, "provider": "quickbooks", "name": "QuickBooks Online", "environment": "production", "expectedAccountId": "example-account", "expectedCompanyName": "Example Company", "authMode": "secrets_manager", "hasCredential": false, "state": "configured", "actualAccountId": null, "actualCompanyName": null, "lastCheckedAt": null, "lastReadAt": null, "lastRenewedAt": null, "credentialCheckedAt": null, "credentialErrorCode": null, "credentialError": null, "errorCode": null, "error": null } ], "page": { "limit": 200, "returned": 1, "mayHaveMore": false }, "runtime": { "workerState": "not_verified", "lastHeartbeat": null, "persistence": "PostgreSQL", "unattendedVerified": false } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Provider read permission in the selected workspace/environment. Configured is not proof of live access; managed_admin entries are read-only external projections." } }, "/v1/workspaces/{workspaceId}/portals": { "get": { "operationId": "listPortals", "summary": "List assigned portals", "description": "Current company membership and a parent portal assignment, or company-owner authority. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Portals" ], "security": [ { "OAuth2": [ "orchesphere.read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalList" }, "example": { "portals": [], "page": { "limit": 200, "returned": 0, "mayHaveMore": false } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Current company membership and a parent portal assignment, or company-owner authority." } }, "/v1/workspaces/{workspaceId}/tasks": { "get": { "operationId": "listTasks", "summary": "List accessible tasks", "description": "Current company/portal access and a task assignment/role. This lists saved requested work, not provider execution. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Tasks" ], "security": [ { "OAuth2": [ "orchesphere.read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskList" }, "example": { "tasks": [ { "id": "33333333-3333-4333-8333-333333333333", "workspaceId": "11111111-1111-4111-8111-111111111111", "portalId": "22222222-2222-4222-8222-222222222222", "title": "Review the saved verification", "description": "Requested work only.", "status": "todo", "assigneeEmail": null, "createdBy": "developer@example.com", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "role": "contributor", "canEdit": true, "canManage": false } ], "page": { "limit": 200, "returned": 1, "mayHaveMore": false } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Current company/portal access and a task assignment/role. This lists saved requested work, not provider execution." }, "post": { "operationId": "createTask", "summary": "Create a task", "description": "Portal admin/operator. Explicit assigneeEmail additionally requires the designated access administrator and an eligible active portal member. Saves requested work; no external execution. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Tasks" ], "security": [ { "OAuth2": [ "orchesphere.read", "orchesphere.jobs" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTask" }, "example": { "portalId": "22222222-2222-4222-8222-222222222222", "title": "Review the saved verification", "description": "Requested work only." } } } }, "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "ok": true, "workspaceId": "11111111-1111-4111-8111-111111111111", "task": { "id": "33333333-3333-4333-8333-333333333333", "workspaceId": "11111111-1111-4111-8111-111111111111", "portalId": "22222222-2222-4222-8222-222222222222", "title": "Review the saved verification", "description": "Requested work only.", "status": "todo", "assigneeEmail": null, "createdBy": "developer@example.com", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "role": "contributor", "canEdit": true, "canManage": false } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Portal admin/operator. Explicit assigneeEmail additionally requires the designated access administrator and an eligible active portal member. Saves requested work; no external execution." } }, "/v1/workspaces/{workspaceId}/jobs": { "get": { "operationId": "listJobs", "summary": "List saved verification jobs", "description": "Provider read permission plus requester identity or jobs_read_all. Latest 100 matching saved jobs, newest first. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Jobs" ], "security": [ { "OAuth2": [ "orchesphere.read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" }, "example": { "jobs": [ { "id": "33333333-3333-4333-8333-333333333333", "connectionId": "22222222-2222-4222-8222-222222222222", "provider": "quickbooks", "operation": "verify", "status": "queued", "attempts": 0, "createdBy": "developer@example.com", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "finishedAt": null, "result": null, "errorCode": null, "error": null } ], "page": { "limit": 100, "returned": 1, "mayHaveMore": false } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Provider read permission plus requester identity or jobs_read_all. Latest 100 matching saved jobs, newest first." } }, "/v1/workspaces/{workspaceId}/jobs/{jobId}": { "get": { "operationId": "getJob", "summary": "Get a saved job", "description": "Provider read permission plus requester identity or jobs_read_all. Missing and inaccessible jobs both return 404. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Jobs" ], "security": [ { "OAuth2": [ "orchesphere.read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "job": { "id": "33333333-3333-4333-8333-333333333333", "connectionId": "22222222-2222-4222-8222-222222222222", "provider": "quickbooks", "operation": "verify", "status": "queued", "attempts": 0, "createdBy": "developer@example.com", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "finishedAt": null, "result": null, "errorCode": null, "error": null } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Provider read permission plus requester identity or jobs_read_all. Missing and inaccessible jobs both return 404." } }, "/v1/workspaces/{workspaceId}/tasks/{taskId}": { "patch": { "operationId": "updateTask", "summary": "Update a task", "description": "Task admin/contributor/reviewer. Reviewer can update status only. Reassignment is not exposed. Parent portal and company rights still apply. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Tasks" ], "security": [ { "OAuth2": [ "orchesphere.read", "orchesphere.jobs" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTask" }, "example": { "status": "in_progress" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "ok": true, "workspaceId": "11111111-1111-4111-8111-111111111111", "task": { "id": "33333333-3333-4333-8333-333333333333", "workspaceId": "11111111-1111-4111-8111-111111111111", "portalId": "22222222-2222-4222-8222-222222222222", "title": "Review the saved verification", "description": "Requested work only.", "status": "in_progress", "assigneeEmail": null, "createdBy": "developer@example.com", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "role": "contributor", "canEdit": true, "canManage": false } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Task admin/contributor/reviewer. Reviewer can update status only. Reassignment is not exposed. Parent portal and company rights still apply." } }, "/v1/workspaces/{workspaceId}/connections/{connectionId}/verify": { "post": { "operationId": "verifyConnection", "summary": "Queue an identity verification", "description": "Provider verify permission, implemented identity adapter and current entitlement/quota. Requires Idempotency-Key; replay with the same workspace/requester/key and connection returns the existing job, possibly already terminal. A different connection conflicts. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Connections" ], "security": [ { "OAuth2": [ "orchesphere.read", "orchesphere.jobs" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$", "minLength": 8, "maxLength": 100 }, "description": "Unique workspace/requester key; reuse only for this same connection submission." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "responses": { "202": { "description": "Saved or previously saved verification job; not proof that execution has completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "job": { "id": "33333333-3333-4333-8333-333333333333", "connectionId": "22222222-2222-4222-8222-222222222222", "provider": "quickbooks", "operation": "verify", "status": "queued", "attempts": 0, "createdBy": "developer@example.com", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z", "finishedAt": null, "result": null, "errorCode": null, "error": null } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Provider verify permission, implemented identity adapter and current entitlement/quota. Requires Idempotency-Key; replay with the same workspace/requester/key and connection returns the existing job, possibly already terminal. A different connection conflicts." } }, "/v1/workspaces/{workspaceId}/jobs/{jobId}/cancel": { "post": { "operationId": "cancelJob", "summary": "Cancel a saved job", "description": "Company owner, or non-viewer requester with provider read, or provider jobs_cancel_all. Applies to queued/retry_wait/running/blocked states; terminal jobs remain unchanged. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Jobs" ], "security": [ { "OAuth2": [ "orchesphere.read", "orchesphere.jobs" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" }, "example": { "ok": true } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Company owner, or non-viewer requester with provider read, or provider jobs_cancel_all. Applies to queued/retry_wait/running/blocked states; terminal jobs remain unchanged." } }, "/v1/workspaces/{workspaceId}/connections/{provider}/{environment}": { "put": { "operationId": "configureConnection", "summary": "Configure a connection", "description": "Provider configure permission; browser_session also requires company owner. Allowed mode depends on catalog provider. Production entitlements/limits apply. Uses a credential reference only; changing settings invalidates previous evidence. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Connections" ], "security": [ { "OAuth2": [ "orchesphere.read", "orchesphere.manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$", "enum": [ "quickbooks", "netsuite", "stripe", "paypal", "payoneer", "us-bank", "bank-accounts", "plaid", "avalara", "track1099", "thomson-reuters", "xero", "sage", "freshbooks", "zoho-books", "bill", "ramp", "brex", "expensify", "gusto", "rippling", "square", "chargebee", "recurly", "pipe17", "magento", "shopify", "bigcommerce", "salsify", "amazon", "walmart", "ebay", "channelengine", "mirakl", "chewy", "sellerboard", "sps", "netsuite-connector", "gs1", "orderful", "woocommerce", "commercetools", "prestashop", "etsy", "tiktok-shop", "faire", "rithum", "klaviyo", "amazon-ads", "google-ads", "shipbob", "shipstation", "flavorcloud", "aftership", "ups", "fedex", "dhl", "usps", "easypost", "shippo", "easyship", "flexport", "dsv", "shiphero", "entra", "sharepoint", "onedrive", "teams", "outlook", "outlook-calendar", "exchange-fur4", "exchange-platformz", "google-workspace", "jira", "confluence", "slack", "notion", "asana", "linear", "airtable", "ipostal", "clickup", "monday", "trello", "smartsheet", "basecamp", "zoom", "dropbox", "box", "docusign", "pandadoc", "figma", "canva", "miro", "hubspot", "salesforce", "zendesk", "servicenow", "mailchimp", "mandrill", "twilio", "sendgrid", "brandfolder", "strapi", "google-analytics", "intercom", "helpscout", "freshdesk", "zoho-crm", "pipedrive", "activecampaign", "constant-contact", "customer-io", "aws", "cloudflare", "google-cloud", "new-relic", "plerion", "postman", "github", "azure", "digitalocean", "vercel", "netlify", "supabase", "firebase", "sentry", "datadog", "grafana", "gitlab", "bitbucket", "docker", "snowflake", "databricks", "bigquery", "redshift", "mongodb", "postgresql", "mysql", "tableau", "power-bi", "looker", "fivetran", "airbyte", "dbt", "segment", "openai", "anthropic", "gemini", "bedrock", "azure-openai", "perplexity", "cohere", "hugging-face", "elevenlabs", "heygen", "cursor" ] } }, { "name": "environment", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "production", "sandbox" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureConnection" }, "example": { "expectedAccountId": "example-account", "expectedCompanyName": "Example Company", "authMode": "secrets_manager" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponse" }, "example": { "connection": { "id": "22222222-2222-4222-8222-222222222222", "version": 1, "provider": "quickbooks", "name": "QuickBooks Online", "environment": "production", "expectedAccountId": "example-account", "expectedCompanyName": "Example Company", "authMode": "secrets_manager", "hasCredential": false, "state": "configured", "actualAccountId": null, "actualCompanyName": null, "lastCheckedAt": null, "lastReadAt": null, "lastRenewedAt": null, "credentialCheckedAt": null, "credentialErrorCode": null, "credentialError": null, "errorCode": null, "error": null } } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Provider configure permission; browser_session also requires company owner. Allowed mode depends on catalog provider. Production entitlements/limits apply. Uses a credential reference only; changing settings invalidates previous evidence." } }, "/v1/workspaces/{workspaceId}/service-permissions/{provider}/{environment}": { "put": { "operationId": "setServicePermissions", "summary": "Set exact service permissions", "description": "Designated global access administrator only, for an existing active/invited company member. Exact production/sandbox grant overrides the * default; empty actions deny access. Does not assign company membership. No query parameters are accepted. OAuth scopes never grant company rights.", "tags": [ "Permissions" ], "security": [ { "OAuth2": [ "orchesphere.read", "orchesphere.manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$", "enum": [ "quickbooks", "netsuite", "stripe", "paypal", "payoneer", "us-bank", "bank-accounts", "plaid", "avalara", "track1099", "thomson-reuters", "xero", "sage", "freshbooks", "zoho-books", "bill", "ramp", "brex", "expensify", "gusto", "rippling", "square", "chargebee", "recurly", "pipe17", "magento", "shopify", "bigcommerce", "salsify", "amazon", "walmart", "ebay", "channelengine", "mirakl", "chewy", "sellerboard", "sps", "netsuite-connector", "gs1", "orderful", "woocommerce", "commercetools", "prestashop", "etsy", "tiktok-shop", "faire", "rithum", "klaviyo", "amazon-ads", "google-ads", "shipbob", "shipstation", "flavorcloud", "aftership", "ups", "fedex", "dhl", "usps", "easypost", "shippo", "easyship", "flexport", "dsv", "shiphero", "entra", "sharepoint", "onedrive", "teams", "outlook", "outlook-calendar", "exchange-fur4", "exchange-platformz", "google-workspace", "jira", "confluence", "slack", "notion", "asana", "linear", "airtable", "ipostal", "clickup", "monday", "trello", "smartsheet", "basecamp", "zoom", "dropbox", "box", "docusign", "pandadoc", "figma", "canva", "miro", "hubspot", "salesforce", "zendesk", "servicenow", "mailchimp", "mandrill", "twilio", "sendgrid", "brandfolder", "strapi", "google-analytics", "intercom", "helpscout", "freshdesk", "zoho-crm", "pipedrive", "activecampaign", "constant-contact", "customer-io", "aws", "cloudflare", "google-cloud", "new-relic", "plerion", "postman", "github", "azure", "digitalocean", "vercel", "netlify", "supabase", "firebase", "sentry", "datadog", "grafana", "gitlab", "bitbucket", "docker", "snowflake", "databricks", "bigquery", "redshift", "mongodb", "postgresql", "mysql", "tableau", "power-bi", "looker", "fivetran", "airbyte", "dbt", "segment", "openai", "anthropic", "gemini", "bedrock", "azure-openai", "perplexity", "cohere", "hugging-face", "elevenlabs", "heygen", "cursor" ] } }, { "name": "environment", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "production", "sandbox", "*" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicePermissions" }, "example": { "email": "developer@example.com", "actions": [ "read", "verify" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" }, "example": { "ok": true } } } }, "400": { "description": "Invalid path/query/body/header or business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, revoked, invalid or wrong-resource token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "402": { "description": "Verified company payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient token scope or current company/service/portal/task authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource metadata challenge; scope upgrade details when insufficient_scope." } } }, "404": { "description": "Unknown endpoint or record not found/inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method is not supported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, quota or idempotency conflict; re-read current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 24,000 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use uncompressed application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Company job/rate/paid-period allowance reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; a lost mutation response does not prove nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-permission": "Designated global access administrator only, for an existing active/invited company member. Exact production/sandbox grant overrides the * default; empty actions deny access. Does not assign company membership." } } }, "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "Registered public application; Authorization Code with S256 PKCE. Supply resource=https://api.orchesphere.ai at authorization, token exchange and refresh. Token scope and current user authority both apply.", "flows": { "authorizationCode": { "authorizationUrl": "https://orchesphere.ai/oauth/authorize", "tokenUrl": "https://orchesphere.ai/oauth/token", "refreshUrl": "https://orchesphere.ai/oauth/token", "scopes": { "orchesphere.read": "Read only the current user’s permitted company data. Required for every operation.", "orchesphere.jobs": "Create/update authorized tasks and queue/cancel permitted identity-verification jobs.", "orchesphere.manage": "Configure permitted connections; service-grant changes still require the designated access administrator.", "offline_access": "Receive rotating refresh tokens, bounded by the grant lifetime. Adds no company permission." } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Page": { "type": "object", "properties": { "limit": { "type": "integer", "enum": [ 100, 200 ] }, "returned": { "type": "integer", "minimum": 0, "maximum": 200 }, "mayHaveMore": { "type": "boolean" } }, "required": [ "limit", "returned", "mayHaveMore" ], "additionalProperties": false }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "ProviderContext": { "type": "object", "properties": { "accountId": { "type": "string" }, "environment": { "type": "string" }, "roleId": { "type": "string" }, "roleName": { "type": "string" } }, "required": [], "additionalProperties": false }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "version": { "type": "integer", "minimum": 1 }, "provider": { "type": "string" }, "name": { "type": "string" }, "environment": { "type": "string", "enum": [ "production", "sandbox" ] }, "expectedAccountId": { "type": "string" }, "expectedCompanyName": { "type": "string" }, "authMode": { "type": "string", "enum": [ "secrets_manager", "agentcore", "browser_session", "managed_admin" ] }, "hasCredential": { "type": "boolean" }, "state": { "type": "string", "enum": [ "configured", "authentication_required", "permission_missing", "provider_error", "server_unavailable", "identity_mismatch", "adapter_required", "data_read_verified", "disconnect_pending" ] }, "actualAccountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actualCompanyName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastReadAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastRenewedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "credentialCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "credentialErrorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credentialError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowedActions": { "type": "array", "items": { "type": "string", "enum": [ "read", "verify", "configure", "jobs_read_all", "jobs_cancel_all" ] } }, "providerContext": { "$ref": "#/components/schemas/ProviderContext" }, "managedExternally": { "type": "boolean" }, "managedBy": { "type": "string" }, "manageUrl": { "type": "string", "format": "uri" }, "note": { "type": "string" } }, "required": [ "id", "provider", "name", "environment", "expectedAccountId", "expectedCompanyName", "authMode", "hasCredential", "state" ], "additionalProperties": false }, "Runtime": { "type": "object", "properties": { "workerState": { "type": "string", "enum": [ "online", "not_verified" ] }, "lastHeartbeat": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "persistence": { "type": "string", "const": "PostgreSQL" }, "unattendedVerified": { "const": false } }, "required": [ "workerState", "lastHeartbeat", "persistence", "unattendedVerified" ], "additionalProperties": false }, "Portal": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "workspaceId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "operator", "viewer" ] }, "canManage": { "type": "boolean" }, "canCreateTask": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "slug", "description", "role", "canManage", "canCreateTask", "createdAt" ], "additionalProperties": false }, "Task": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "workspaceId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "portalId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "title": { "type": "string", "minLength": 2, "maxLength": 240 }, "description": { "type": "string", "maxLength": 6000 }, "status": { "type": "string", "enum": [ "todo", "in_progress", "blocked", "review", "done", "cancelled" ] }, "assigneeEmail": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "role": { "type": "string", "enum": [ "admin", "contributor", "reviewer", "viewer" ] }, "canEdit": { "type": "boolean" }, "canManage": { "type": "boolean" } }, "required": [ "id", "workspaceId", "portalId", "title", "description", "status", "assigneeEmail", "createdBy", "createdAt", "updatedAt", "role", "canEdit", "canManage" ], "additionalProperties": false }, "VerificationResult": { "type": "object", "properties": { "accountId": { "type": "string" }, "companyName": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "identityLabelKind": { "type": "string", "enum": [ "account_label", "company_name" ] }, "credentialRenewedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "accountId", "companyName", "observedAt", "identityLabelKind", "credentialRenewedAt" ], "additionalProperties": false }, "Job": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "connectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "provider": { "type": "string" }, "environment": { "type": "string", "enum": [ "production", "sandbox" ] }, "operation": { "type": "string", "const": "verify" }, "status": { "type": "string", "enum": [ "queued", "running", "retry_wait", "succeeded", "failed", "blocked", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0 }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "result": { "anyOf": [ { "$ref": "#/components/schemas/VerificationResult" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canCancel": { "type": "boolean" }, "canResume": { "type": "boolean" }, "resumeBlockedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "connectionId", "provider", "operation", "status", "attempts", "createdBy", "createdAt", "updatedAt", "finishedAt", "result", "errorCode", "error" ], "additionalProperties": false }, "CreateTask": { "type": "object", "properties": { "portalId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "title": { "type": "string", "minLength": 2, "maxLength": 240 }, "description": { "type": "string", "maxLength": 6000 }, "assigneeEmail": { "type": "string", "format": "email", "minLength": 3, "maxLength": 254 } }, "required": [ "portalId", "title" ], "additionalProperties": false }, "UpdateTask": { "type": "object", "properties": { "title": { "type": "string", "minLength": 2, "maxLength": 240 }, "description": { "type": "string", "maxLength": 6000 }, "status": { "type": "string", "enum": [ "todo", "in_progress", "blocked", "review", "done", "cancelled" ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "ConfigureConnection": { "type": "object", "properties": { "expectedAccountId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedCompanyName": { "type": "string", "minLength": 1, "maxLength": 160 }, "authMode": { "type": "string", "enum": [ "secrets_manager", "agentcore", "browser_session" ] }, "credentialRef": { "type": "string", "maxLength": 512, "description": "A company-scoped credential reference, never a provider secret. Omit to retain an existing reference with unchanged authMode; empty string clears it. Browser mode forbids a reference." } }, "required": [ "expectedAccountId", "expectedCompanyName", "authMode" ], "additionalProperties": false }, "ServicePermissions": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 254 }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "read", "verify", "configure", "jobs_read_all", "jobs_cancel_all" ] }, "uniqueItems": true, "maxItems": 5, "description": "Nonempty actions require read. jobs_cancel_all requires jobs_read_all. Empty array denies access. Viewer members may receive read-only actions only." } }, "required": [ "email", "actions" ], "additionalProperties": false }, "Empty": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "Ok": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false }, "TaskResponse": { "type": "object", "properties": { "ok": { "const": true }, "workspaceId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$", "minLength": 8, "maxLength": 80 }, "task": { "$ref": "#/components/schemas/Task" } }, "required": [ "ok", "workspaceId", "task" ], "additionalProperties": false }, "JobResponse": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" } }, "required": [ "job" ], "additionalProperties": false }, "ConnectionResponse": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/Connection" }, "reused": { "const": true } }, "required": [ "connection" ], "additionalProperties": false }, "WorkspaceList": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" }, "maxItems": 200 }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "workspaces", "page" ], "additionalProperties": false }, "ConnectionList": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" }, "maxItems": 200 }, "page": { "$ref": "#/components/schemas/Page" }, "runtime": { "$ref": "#/components/schemas/Runtime" } }, "required": [ "connections", "page", "runtime" ], "additionalProperties": false }, "PortalList": { "type": "object", "properties": { "portals": { "type": "array", "items": { "$ref": "#/components/schemas/Portal" }, "maxItems": 200 }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "portals", "page" ], "additionalProperties": false }, "TaskList": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" }, "maxItems": 200 }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "tasks", "page" ], "additionalProperties": false }, "JobList": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" }, "maxItems": 100 }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "jobs", "page" ], "additionalProperties": false } } }, "x-resource": "https://api.orchesphere.ai", "x-request-body-max-bytes": 24000, "x-query-parameters": "None supported", "x-transport": "HTTPS JSON; backend/native clients only", "x-revocation-endpoint": "https://orchesphere.ai/oauth/revoke", "x-protected-resource-metadata": "https://api.orchesphere.ai/.well-known/oauth-protected-resource" }