Skip to content
OpsTech Docs

control-plane-api

📦 Auto-synced from

opsclaw-product/tools/api-inventory/openapi/control-plane-api.yaml

@ 2061009. To change this page, edit the upstream OpenAPI fragment and let docs-propagate.yml re-sync.

At a glance

FieldValue
Listen port8082
Ownercontrol-plane
Default authbearer-pat
Public hostnamesplatform.opstech.dev, opsclaw-qa.opstech.dev, opsclaw-preview.opstech.dev
Service-level side effectsmutates-db, calls-stripe, calls-postmark, calls-telegram
Declared paths113
Scanned routes61
Total paths emitted114

Event-flow diagram


      
        mmdc render failed: Command failed: npx --no-install mmdc -i "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/ea3fb396de18325c.mmd" -o "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/ea3fb396de18325c.svg" -b transparent 2>&1
control-plane-api — operations grouped and coloured by their primary side-effect class.

Per-tag flow diagrams

This service has more than 30 operations; one diagram per OpenAPI tag is emitted, plus the overview above. Use the tab(s) below to drill into a specific tag.

catalog


      
        mmdc render failed: Command failed: npx --no-install mmdc -i "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/f80d90ca272ecff4.mmd" -o "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/f80d90ca272ecff4.svg" -b transparent 2>&1
control-plane-api — operations tagged `catalog`

manager-bot


      
        mmdc render failed: Command failed: npx --no-install mmdc -i "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/4088b76841ad8e1c.mmd" -o "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/4088b76841ad8e1c.svg" -b transparent 2>&1
control-plane-api — operations tagged `manager-bot`

observability


      
        mmdc render failed: Command failed: npx --no-install mmdc -i "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/14071d387a86e6e8.mmd" -o "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/14071d387a86e6e8.svg" -b transparent 2>&1
control-plane-api — operations tagged `observability`

untagged


      
        mmdc render failed: Command failed: npx --no-install mmdc -i "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/a2e47707624c5c12.mmd" -o "/home/runner/_work/opstech-site/opstech-site/docs-site/.mermaid-cache/a2e47707624c5c12.svg" -b transparent 2>&1
control-plane-api — operations tagged `untagged`

Endpoints

MethodPathSummarySide effectsStatus
GET/healthzHealth check for the internal API process
GET/metricsPrometheus metrics scraperead-onlyverified-from-code
GET/v1/agent-blueprintsList static contract-only AgentBlueprint fixtures
GET/v1/agent-blueprints/{ref}Get one static contract-only AgentBlueprint by id@version
GET/v1/agent-instancesList agent instances for dashboard/admin fleet views
POST/v1/agent-instancesCreate or request a new agent instance
DELETE/v1/agent-instances/{id}Soft-delete an agent instance (S20-T04, V2 PAT-gated)
GET/v1/agent-instances/{id}Get agent instance status
PATCH/v1/agent-instances/{id}/configChange customer-controlled options on an instance
POST/v1/agent-instances/{id}/convertConvert a trial to a paid instance
POST/v1/agent-instances/{id}/deleteRequest deletion of an existing agent instance
POST/v1/agent-instances/{id}/plan-changeRequest a plan change for one agent instance
POST/v1/agent-instances/{id}/plan-previewPreview plan-change impact for one agent instance
GET/v1/agent-instances/{id}/plan-statusGet active plan and storage quota status for one agent instance
POST/v1/agent-instances/{id}/select-as-currentSelect an agent as current for the caller's session (S20-T04)
POST/v1/agent-instances/{id}/suspendSuspend an existing agent instance
POST/v1/agent-instances/{id}/trial/activateActivate a trial for an existing draft instance
GET/v1/agent-packsRead the product-facing Agent Pack catalog contract backed by existing control-plane truth
GET/v1/agent-runsList AgentRun history for the authenticated principal (API0.1, S15-T03)
POST/v1/agentsCreate a persona-authored agent
DELETE/v1/agents/{id}Soft-delete a persona-authored agent
GET/v1/agents/{id}Get a persona-authored agent
PUT/v1/agents/{id}Update a persona-authored agent
POST/v1/agents/{id}/chatSynchronous REST chat with a hosted agent (API1.4, S16-T03)
POST/v1/agents/{id}/chat/completionsOpenAI-compatible chat completions on a hosted agent (M2.5, S20-T01)
POST/v1/agents/{id}/runSynchronous one-shot AgentRun trigger (S22-T04, Sprint 022)
POST/v1/audit/reclassify-policy-idReclassify an audit event's retention policy (S18-T02 / P8.3 Phase 2)
POST/v1/auth/signupPublic B2C Solo €19 BYOK self-service onramp (S19-T04 / API1.7)
POST/v1/auth/tokensMint a per-principal PAT for Mode 2 edge auth (API0.4 / M2.1, S15-T03)
GET/v1/billing/invoicesStripe invoices list (read-through, OpsClaw-normalised) (API0.2, S15-T03)
GET/v1/billing/planCurrent Solo/Pro/Squad tier + trial status (API0.2, S15-T03)
POST/v1/billing/stripe-webhookReceive Stripe webhooks
GET/v1/billing/usageCurrent month usage spend for the authenticated tenant (API0.2, S15-T03)
POST/v1/bot-claimsStart or register a Telegram managed-bot claim flow
GET/v1/bot-claims/{id}Read one Telegram managed-bot claim
POST/v1/bot-claims/{id}/cancelCancel one pending or failed Telegram managed-bot claim
POST/v1/bot-claims/{id}/managed-botAttach the created Telegram managed bot to an existing claim
GET/v1/cluster-event-hook-profilesList ClusterEventHookProfile catalog contractsread-onlyverified-from-code
GET/v1/cluster-event-hook-profiles/{name}Get one ClusterEventHookProfile contract by nameread-onlyverified-from-code
GET/v1/cluster-event-hook-subscriptionsList cluster event hook subscriptions
POST/v1/cluster-event-hook-subscriptionsCreate a cluster event hook subscription
DELETE/v1/cluster-event-hook-subscriptions/{id}Delete a cluster event hook subscription
GET/v1/cluster-event-hook-subscriptions/{id}Get one cluster event hook subscription
PATCH/v1/cluster-event-hook-subscriptions/{id}Pause or resume a cluster event hook subscription
POST/v1/cluster-event-hook-subscriptions/{id}/testDry-run a cluster event hook subscription filter and delivery envelope
GET/v1/execution-profilesList ExecutionProfile resources visible to the control-plane API
GET/v1/execution-profiles/{name}Get one ExecutionProfile resource by name
GET/v1/invitationsList pending IAM invitations (S16-T01 / API1.1)
POST/v1/invitationsMint an IAM invitation token (S16-T01 / API1.1)
DELETE/v1/invitations/{id}Revoke a pending invitation (S16-T01 / API1.1)
POST/v1/invitations/{token}/acceptAccept an invitation, mint Principal + RoleAssignment (S16-T01 / API1.1)
GET/v1/manager-bot/agent-instancesRead the bounded account inventory for one Telegram manager-bot user
GET/v1/manager-bot/agent-instances/{id}/runtime-readinessGet a conservative runtime readiness summary for manager-bot handoff
GET/v1/manager-bot/bot-claims/(unverified) GET /v1/manager-bot/bot-claims/unverified-scanned
GET/v1/manager-bot/bot-claims/{id}Resolve a bot claim from the manager-bot callerread-dbverified-from-code
GET/v1/manager-bot/capability-pack-optionsRead manager-bot capability pack options backed by AgentClass and MCPProfile truth
GET/v1/manager-bot/pending-bot-claimResolve the pending BotClaim for a Telegram userread-dbverified-from-code
POST/v1/manager-bot/telegram/managed-bot-callbackFulfill one BotClaim from an external Telegram manager-bot bridge callback
GET/v1/mcp-attachmentsList tenant MCP attachments
POST/v1/mcp-attachmentsAttach a ready MCP installation to an agent or run
DELETE/v1/mcp-attachments/{id}Detach one tenant MCP attachment
GET/v1/mcp-attachments/runtime-projectionRead runtime MCP projection for an agent or run
GET/v1/mcp-installationsList tenant MCP installations
POST/v1/mcp-installationsCreate a tenant MCP installation
DELETE/v1/mcp-installations/{id}Revoke one tenant MCP installation
GET/v1/mcp-installations/{id}Get one tenant MCP installation
POST/v1/mcp-installations/{id}/credentialsStore tenant MCP API-key credential and materialize runtime endpoint
GET/v1/mcp-installations/{id}/oauth/callbackComplete tenant MCP OAuth flow
POST/v1/mcp-installations/{id}/oauth/startStart tenant MCP OAuth flow
GET/v1/mcp-profilesList MCPProfile catalog resources visible to the control-plane API
GET/v1/mcp-profiles/{name}Get one MCPProfile catalog resource by name
GET/v1/mcpsList MCPs the caller's commercial tier may use (S19-T05)
GET/v1/mcps/{name}Get one curated MCP by name (S19-T05)
GET/v1/mcps/customList the caller's tenant-scoped custom MCPs (S19-T05)
POST/v1/mcps/customRegister a tenant-scoped custom MCP (S19-T05)
DELETE/v1/mcps/custom/{id}Soft-delete a tenant-scoped custom MCP (S19-T05)
GET/v1/notification-profilesList NotificationProfile catalog contractsread-onlyverified-from-code
GET/v1/notification-profiles/{name}Get one NotificationProfile contract by nameread-onlyverified-from-code
GET/v1/notification-subscriptionsList user-facing notification subscriptions
POST/v1/notification-subscriptionsCreate a user-facing notification subscription
DELETE/v1/notification-subscriptions/{id}Delete a user-facing notification subscription
GET/v1/notification-subscriptions/{id}Get one user-facing notification subscription
PATCH/v1/notification-subscriptions/{id}Update user-facing notification subscription preferences
GET/v1/observability-profilesList ObservabilityProfile catalog contractsread-onlyverified-from-code
GET/v1/observability-profiles/{name}Get one ObservabilityProfile contract by nameread-onlyverified-from-code
GET/v1/offer-catalogsList OfferCatalog contractsread-onlyverified-from-code
GET/v1/offer-catalogs/{name}Get one OfferCatalog contract by nameread-onlyverified-from-code
GET/v1/outbox/eventsList recent outbox queue events for support/admin inspection
POST/v1/outbox/events/{id}/retrySchedule an immediate retry for one outbox event
GET/v1/outbox/statsGet aggregate queue stats for the asynchronous outbox
GET/v1/personality-profilesList PersonalityProfile catalog resources visible to the control-plane API
GET/v1/personality-profiles/{name}Get one PersonalityProfile catalog resource by name
GET/v1/personasList personas the caller's commercial tier may purchase (S18-T05)
GET/v1/personas/{name}Get one persona by name (S18-T05)
GET/v1/plan-profilesList PlanProfile contractsread-onlyverified-from-code
GET/v1/plan-profiles/{name}Get one PlanProfile contract by nameread-onlyverified-from-code
GET/v1/platform-console-profilesList PlatformConsoleProfile contractsread-onlyverified-from-code
GET/v1/platform-console-profiles/{name}Get one PlatformConsoleProfile contract by nameread-onlyverified-from-code
GET/v1/platform-console-read-modelsList PlatformConsoleReadModel contractsread-onlyverified-from-code
GET/v1/platform-console-read-models/{name}Get one PlatformConsoleReadModel contract by nameread-onlyverified-from-code
GET/v1/portal-app-enablementsList per-agent tenant portal app enablement policies
POST/v1/portal-app-enablementsCreate a per-agent tenant portal app enablement policy
DELETE/v1/portal-app-enablements/{id}Delete a portal app enablement policy
GET/v1/portal-app-enablements/{id}Get one portal app enablement policy
PATCH/v1/portal-app-enablements/{id}Update a portal app enablement policy
GET/v1/principalsList IAM Principals (S15-T04 / API1.2)
POST/v1/principalsMint a new IAM Principal + PAT (S15-T04 / API1.2)
DELETE/v1/principals/{id}Revoke an IAM Principal — cascades RoleAssignments (S15-T04 / API1.2)
GET/v1/principals/{id}Get one IAM Principal by id (S15-T04 / API1.2)
PATCH/v1/principals/{id}Update an IAM Principal (subjectId rename, notAfter expiry; S15-T04 / API1.2)
POST/v1/prospect-agentsCreate a product-facing prospect agent request
GET/v1/role-assignmentsList RoleAssignments (S15-T04 / API1.2)
POST/v1/role-assignmentsGrant a RoleAssignment to a Principal at a scope (S15-T04 / API1.2)
DELETE/v1/role-assignments/{id}Revoke a RoleAssignment (S15-T04 / API1.2)
GET/v1/role-assignments/{id}Get one RoleAssignment by id (S15-T04 / API1.2)
GET/v1/role-definitionsList RoleDefinitions — v1 catalogue (5 predefined; S15-T04 / API1.2)
GET/v1/role-definitions/{id}Get one RoleDefinition by id or name (S15-T04 / API1.2)
GET/v1/runtime-profile-catalogsList RuntimeProfileCatalog contractsread-onlyverified-from-code
GET/v1/runtime-profile-catalogs/{name}Get one RuntimeProfileCatalog contract by nameread-onlyverified-from-code
GET/v1/skill-bundlesList contract-only SkillBundle catalog fixtures
GET/v1/skill-bundles/{ref}Get one contract-only SkillBundle by id@version
GET/v1/sympozium-integration-profilesList SympoziumIntegrationProfile contractsread-onlyverified-from-code
GET/v1/sympozium-integration-profiles/{name}Get one SympoziumIntegrationProfile contract by nameread-onlyverified-from-code
GET/v1/tenant-portal-profilesList TenantPortalProfile contractsread-onlyverified-from-code
GET/v1/tenant-portal-profiles/{name}Get one TenantPortalProfile contract by nameread-onlyverified-from-code
DELETE/v1/tenants/{id}Cascade-delete a tenant (RGPD article 17 + ToS termination ; S16-T04 / API1.5)
POST/v1/tenants/{id}/restoreRestore a tenant from tombstone within the 30-day grace window (S17-T04)
GET/v1/tooling-matrix-profilesList ToolingMatrixProfile contractsread-onlyverified-from-code
GET/v1/tooling-matrix-profiles/{name}Get one ToolingMatrixProfile contract by nameread-onlyverified-from-code
POST/v1/workspace-auth/challengesRequest a passwordless workspace login code over Telegram
POST/v1/workspace-auth/verificationsVerify a passwordless workspace login code
GET/v1/workspace-filesystem-profilesList contract-only workspace filesystem profiles
GET/v1/workspace-filesystem-profiles/{ref}Get one contract-only workspace filesystem profile by id@version
POST/v1/workspace-filesystem-profiles/{ref}/mount-sessionsIssue a signed short-lived workspace mount session
GET/v1/workspace-filesystem-profiles/{ref}/mount-workflowPreview a redacted local mount workflow for macOS or Windows
GET/v1/workspace-profilesList contract-only WorkspaceProfile catalog fixtures
GET/v1/workspace-profiles/{ref}Get one contract-only WorkspaceProfile by id@version