> ## Documentation Index > Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt > Use this file to discover all available pages before exploring further. # Invoke an exact Managed Tool release > Selects an exact release and an acting Principal using an Organization-managed root or admin API key. ## OpenAPI ````yaml /openapi.json post /v1/workspaces/{workspace_id}/managed-tool-invocations openapi: 3.1.0 info: title: Checkfu API version: '2026-08-31' description: >- Authentication is declared per operation: API-key, runtime, or connector bearer; Automation signature; or credential-free pairing redemption. Every general Checkfu REST request requires the dated `Checkfu-Version` header (one of: 2026-08-31); the three MCP JSON-RPC transports use `MCP-Protocol-Version`, A2A uses `A2A-Version`, and the provider OAuth callback carries neither Checkfu header. API keys resolve one Workspace without a request selector; authenticated responses identify it with `Checkfu-Workspace-Id`. servers: - url: https://api.checkfu.com security: - bearerAuth: [] tags: - name: organizations - name: sourceRepositories - name: tenants - name: workspaces - name: principals - name: principalGroups - name: principalAccessCredentials - name: apiKeys - name: agents - name: harnessRuntime - name: permissionAssignments - name: actionPolicies - name: files - name: memoryStores - name: modelCredentials - name: modelRoutingProfiles - name: blueprintInstallations - name: toolSources - name: skills - name: skillSources - name: agentBlueprints - name: skillProposals - name: instructionProposals - name: catalog - name: managedTools - name: concepts - name: support - name: connections - name: connectionVaults - name: connectionAssignments - name: connectedRuntimes - name: fileTrees - name: collaboration - name: automationGraphs - name: automations - name: actionApprovals - name: standingApprovals - name: workloadReviewPolicies - name: usage - name: models - name: outcomes - name: budgets - name: billing - name: sessions - name: audit - name: sessionExports - name: runs - name: runnerPools - name: transcripts - name: sessionWatches - name: sessionCapsules - name: sessionTrajectories - name: webhookEndpoints - name: integrationGateway - name: workEnvironments - name: computers - name: computerScreens - name: computerBrowserObservations - name: computerBrowserActions - name: environments - name: computerHeadlessOperations - name: vaults - name: apiMcp - name: a2a paths: /v1/workspaces/{workspace_id}/managed-tool-invocations: post: tags: - managedTools summary: Invoke an exact Managed Tool release description: >- Selects an exact release and an acting Principal using an Organization-managed root or admin API key. The server checks the active Principal's tool and spending authority. Idempotency-Key is required and identifies the original invocation. Returns only its retained state: prepared and admitted do not establish provider completion; unknown requires recovery of that same original and must not be retried with a fresh key. The request supplies no execution subject, provider credential or approval context. Principal-only MCP invocation is not supported. Checkfu support posture: preview; hosted. No release evidence journey applies to this operation. operationId: managedTools.invokeManagedTool parameters: - name: workspace_id in: path schema: $ref: '#/components/schemas/WorkspaceId' required: true - name: checkfu-version in: header schema: type: string enum: - '2026-08-31' required: true - name: idempotency-key in: header schema: type: string allOf: - maxLength: 255 - minLength: 1 required: true requestBody: content: application/json: schema: type: object properties: selection: $ref: '#/components/schemas/ManagedToolSelection' arguments: $ref: '#/components/schemas/ManagedToolInvocationArguments' maximum_charge_microusd: type: integer allOf: - minimum: 0 - maximum: 9007199254740991 acted_as_principal_id: $ref: '#/components/schemas/PrincipalId' required: - selection - arguments - maximum_charge_microusd - acted_as_principal_id additionalProperties: false required: true responses: '200': description: Success content: application/json: schema: anyOf: - type: object properties: tool_invocation_id: $ref: '#/components/schemas/ToolInvocationId' status: type: string enum: - prepared - admitted - canceled_no_send - unknown required: - tool_invocation_id - status additionalProperties: false - type: object properties: tool_invocation_id: $ref: '#/components/schemas/ToolInvocationId' selection: $ref: '#/components/schemas/ManagedToolSelection' status: type: string enum: - approval_required action_approval_id: $ref: '#/components/schemas/ActionApprovalId' expires_at: $ref: '#/components/schemas/CurrentTimestamp' required: - tool_invocation_id - selection - status - action_approval_id - expires_at additionalProperties: false - type: object properties: tool_invocation_id: $ref: '#/components/schemas/ToolInvocationId' selection: $ref: '#/components/schemas/ManagedToolSelection' status: type: string enum: - completed provider_effect: type: string enum: - completed usage_entry_id: $ref: '#/components/schemas/UsageEntryId' result: $ref: '#/components/schemas/ManagedToolInvocationResult' required: - tool_invocation_id - selection - status - provider_effect - usage_entry_id - result additionalProperties: false headers: checkfu-workspace-id: description: The Workspace resolved from the authenticated bearer credential. required: true schema: $ref: '#/components/schemas/WorkspaceId' '400': description: Typed Checkfu wire error content: application/json: schema: $ref: '#/components/schemas/ValidationMalformedError' '401': description: Typed Checkfu wire error content: application/json: schema: type: object required: - error properties: error: type: object required: - type - message - more properties: type: type: string enum: - auth.invalid_key message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#auth-invalid-key description: >- Stable public documentation and remedy for this error type. additionalProperties: false additionalProperties: false '403': description: >- The organization, tenant, or workspace backing this key is administratively disabled. | Deployment governance or retention policy denied the request. content: application/json: schema: anyOf: - type: object required: - error properties: error: type: object properties: type: type: string enum: - auth.disabled_tenancy message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#auth-disabled-tenancy description: >- Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false additionalProperties: false - $ref: '#/components/schemas/PolicyDeniedError' '409': description: The request conflicts with the resource's current state. content: application/json: schema: $ref: '#/components/schemas/ValidationConflictError' '429': description: Typed Checkfu wire error headers: retry-after: description: >- Delay in seconds for rate limits or deployment quotas with a known release or UTC reset boundary required: false schema: type: integer minimum: 1 content: application/json: schema: type: object required: - error properties: error: type: object required: - type - message - more properties: type: type: string enum: - budget.exceeded message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#budget-exceeded description: >- Stable public documentation and remedy for this error type. additionalProperties: false additionalProperties: false '503': description: Authorization could not be evaluated. Retry the same request. content: application/json: schema: $ref: '#/components/schemas/AuthorizationUnavailableError' security: - bearerAuth: [] components: schemas: WorkspaceId: type: string pattern: ^wrkspc_[0-9a-f]{32}$ ManagedToolSelection: type: object properties: managed_tool_id: $ref: '#/components/schemas/ManagedToolId' managed_tool_release_id: $ref: '#/components/schemas/ManagedToolReleaseId' required: - managed_tool_id - managed_tool_release_id additionalProperties: false ManagedToolInvocationArguments: x-checkfu-json-budget: maximumBytes: 1048576 maximumDepth: 64 maximumNodes: 100000 maximumInspectionWork: 100000 x-checkfu-unicode-scalar-values: true description: >- ManagedMap arguments: at most 1 MiB of UTF-8 JSON, with Unicode scalar strings and bounded structure. PrincipalId: type: string pattern: ^prin_[0-9a-f]{32}$ ToolInvocationId: type: string pattern: ^tinv_[0-9a-f]{32}$ ActionApprovalId: anyOf: - $ref: '#/components/schemas/NonBrowserActionApprovalId' - $ref: '#/components/schemas/BrowserActionApprovalId' description: >- an ActionApprovalId of the form approval_<32 hex chars> or bapproval_<32 hex chars> CurrentTimestamp: type: string allOf: - maxLength: 24 - pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ x-checkfu-current-timestamp: true description: A canonical UTC ISO-8601 timestamp with millisecond precision. UsageEntryId: type: string pattern: ^use_[0-9a-f]{32}$ ManagedToolInvocationResult: x-checkfu-json-budget: maximumBytes: 1048576 maximumDepth: 64 maximumNodes: 100000 maximumInspectionWork: 100000 x-checkfu-unicode-scalar-values: true description: >- A current-authorized Managed Tool result projection, bounded to 1 MiB UTF-8 JSON. ValidationMalformedError: type: object properties: error: type: object properties: type: type: string enum: - validation.malformed message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#validation-malformed description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: >- The request could not be decoded or violated a declared input constraint. PolicyDeniedError: type: object properties: error: type: object properties: type: type: string enum: - policy.denied message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#policy-denied description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: Deployment governance or retention policy denied the request. ValidationConflictError: type: object properties: error: type: object properties: type: type: string enum: - validation.conflict message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#validation-conflict description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: The request conflicts with the resource's current state. AuthorizationUnavailableError: type: object properties: error: type: object properties: type: type: string enum: - auth.authorization_unavailable message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#auth-authorization-unavailable description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: Authorization could not be evaluated. Retry the same request. ManagedToolId: type: string pattern: ^mtl_[0-9a-f]{32}$ ManagedToolReleaseId: type: string pattern: ^mtrel_[0-9a-f]{32}$ NonBrowserActionApprovalId: type: string pattern: ^approval_[0-9a-f]{32}$ BrowserActionApprovalId: type: string pattern: ^bapproval_[0-9a-f]{32}$ securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.