> ## Documentation Index > Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Ingest one verified provider conversation event > One call per verified provider event. An invoke requires the asserted person `principal`, create-or-resolves the ConversationBinding and installed Session, and appends one authored drive event with `caused_by` of `external_event`. An observation records an edit, deletion, or reaction durably without driving and may omit `principal` when the provider event has no author. An authorless observation attaches to an existing live interaction binding; if none exists, it settles with null `binding` and `session_id` and creates neither. The caller-supplied `external_event_id` anchors a per-installation occurrence claim, so retries converge and exact replay returns `replayed` without re-judging. Verify the provider signature before calling: Checkfu trusts that provenance but never treats it as human Session admission authority. Checkfu support posture: alpha; hosted. Required evidence journey: collaboration-identity. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities. ## OpenAPI ````yaml /openapi.json post /v1/conversation-bindings/ingest openapi: 3.1.0 info: title: Checkfu API version: '2026-08-27' 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-27); 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: harnesses - name: harnessRuntime - name: sandboxProfiles - name: computerProfiles - name: permissionAssignments - name: actionPolicies - name: files - name: memoryStores - name: dreams - name: modelCredentials - name: modelRoutingProfiles - name: blueprintInstallations - name: toolSources - name: skills - name: skillSources - name: agentSources - name: skillProposals - name: instructionProposals - name: catalog - name: concepts - name: support - name: connections - name: connectionVaults - name: connectionAssignments - name: connectedRuntimes - name: projects - name: collaboration - name: automationGraphs - name: automations - name: actionApprovals - name: standingApprovals - 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: webhookEndpoints - name: integrationGateway - name: agentDeployments - name: workEnvironments - name: computers - name: computerScreens - name: computerBrowserObservations - name: computerBrowserActions - name: environments - name: vaults - name: apiMcp - name: a2a paths: /v1/conversation-bindings/ingest: post: tags: - collaboration summary: Ingest one verified provider conversation event description: >- One call per verified provider event. An invoke requires the asserted person `principal`, create-or-resolves the ConversationBinding and installed Session, and appends one authored drive event with `caused_by` of `external_event`. An observation records an edit, deletion, or reaction durably without driving and may omit `principal` when the provider event has no author. An authorless observation attaches to an existing live interaction binding; if none exists, it settles with null `binding` and `session_id` and creates neither. The caller-supplied `external_event_id` anchors a per-installation occurrence claim, so retries converge and exact replay returns `replayed` without re-judging. Verify the provider signature before calling: Checkfu trusts that provenance but never treats it as human Session admission authority. Checkfu support posture: alpha; hosted. Required evidence journey: collaboration-identity. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities. operationId: collaboration.ingestConversation parameters: - name: checkfu-version in: header schema: type: string enum: - '2026-08-27' required: true - name: idempotency-key in: header schema: type: string allOf: - maxLength: 255 required: false requestBody: content: application/json: schema: anyOf: - type: object properties: external_installation_id: $ref: '#/components/schemas/CollaborationInstallationId' agent_installation_id: $ref: '#/components/schemas/AgentInstallationId' surface_scope_id: $ref: '#/components/schemas/SurfaceScopeId' conversation: $ref: '#/components/schemas/Union_197' external_event_id: type: string allOf: - minLength: 1 - maxLength: 512 occurred_at: type: string session_id: false agent: false agent_deployment_revision_selection: false mounts: false acted_as: false caused_by: false harness: false model_routing_profile_key: false sandbox_profile_key: false principal: $ref: '#/components/schemas/PrincipalId' input: type: object properties: kind: type: string enum: - invoke content: type: string allOf: - minLength: 1 is_direct_mention: type: boolean author_restricted: type: boolean observation: false message_external_id: false required: - kind - content additionalProperties: false required: - external_installation_id - agent_installation_id - surface_scope_id - conversation - external_event_id - principal - input additionalProperties: false - type: object properties: external_installation_id: $ref: '#/components/schemas/CollaborationInstallationId' agent_installation_id: $ref: '#/components/schemas/AgentInstallationId' surface_scope_id: $ref: '#/components/schemas/SurfaceScopeId' conversation: $ref: '#/components/schemas/Union_197' external_event_id: type: string allOf: - minLength: 1 - maxLength: 512 occurred_at: type: string session_id: false agent: false agent_deployment_revision_selection: false mounts: false acted_as: false caused_by: false harness: false model_routing_profile_key: false sandbox_profile_key: false principal: $ref: '#/components/schemas/PrincipalId' input: type: object properties: kind: type: string enum: - observe observation: type: string enum: - message_edited - message_deleted - reaction_added - reaction_removed message_external_id: anyOf: - type: string allOf: - minLength: 1 - maxLength: 512 - type: 'null' content: false required: - kind - observation additionalProperties: false required: - external_installation_id - agent_installation_id - surface_scope_id - conversation - external_event_id - input additionalProperties: false required: true responses: '200': description: Success content: application/json: schema: anyOf: - type: object properties: event_id: anyOf: - $ref: '#/components/schemas/EventId' - type: 'null' silence_reason: anyOf: - type: string enum: - disabled - muted - restricted_author - rate_limited - budget_exhausted - busy - self_quieted - not_answerable - uncertain - type: 'null' binding: $ref: '#/components/schemas/Objects_113' session_id: $ref: '#/components/schemas/SessionId' disposition: type: string enum: - driven - observed - replayed - filtered required: - event_id - binding - session_id - disposition additionalProperties: false - type: object properties: event_id: anyOf: - $ref: '#/components/schemas/EventId' - type: 'null' silence_reason: anyOf: - type: string enum: - disabled - muted - restricted_author - rate_limited - budget_exhausted - busy - self_quieted - not_answerable - uncertain - type: 'null' binding: type: 'null' session_id: type: 'null' disposition: type: string enum: - observed - replayed required: - event_id - binding - session_id - disposition 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: anyOf: - $ref: '#/components/schemas/ValidationMalformedError' - $ref: '#/components/schemas/SessionDriveBadRequestError' '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' '404': description: >- The requested resource does not exist in the resolved deployment boundary. content: application/json: schema: $ref: '#/components/schemas/ValidationNotFoundError' '409': description: >- The request conflicts with the resource's current state. | An idempotent mutation conflicts with a completed or in-progress request for the same key. | The operation is illegal for the resource's current lifecycle state. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationConflictError' - $ref: '#/components/schemas/IdempotencyConflictError' - $ref: '#/components/schemas/RuntimeInvalidTransitionError' '422': description: >- No model candidate satisfies the deployment's routing constraints. | The harness does not satisfy the required protocol or capability set. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ModelNoEligibleModelError' - $ref: '#/components/schemas/ModelNoEligibleModelError' - $ref: '#/components/schemas/RuntimeHarnessIncompatibleError' '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 '500': description: >- An unexpected internal failure occurred; the message contains an opaque incident reference. content: application/json: schema: $ref: '#/components/schemas/RuntimeInternalError' '503': description: >- No eligible Runner can currently claim the work. | Platform-managed model credentials are temporarily unavailable. content: application/json: schema: anyOf: - $ref: '#/components/schemas/RuntimeRunnerUnavailableError' - $ref: '#/components/schemas/ModelPlatformSupplyUnavailableError' security: - bearerAuth: [] components: schemas: CollaborationInstallationId: type: string allOf: - pattern: ^exti_[0-9a-f]{32}$ AgentInstallationId: type: string allOf: - pattern: ^aini_[0-9a-f]{32}$ SurfaceScopeId: type: string allOf: - pattern: ^surf_[0-9a-f]{32}$ Union_197: anyOf: - type: object properties: kind: type: string enum: - ambient - direct root_external_id: type: string allOf: - minLength: 1 - maxLength: 512 thread_external_id: type: 'null' required: - kind - root_external_id - thread_external_id additionalProperties: false - type: object properties: kind: type: string enum: - thread root_external_id: type: string allOf: - minLength: 1 - maxLength: 512 thread_external_id: type: string allOf: - minLength: 1 - maxLength: 512 required: - kind - root_external_id - thread_external_id additionalProperties: false PrincipalId: type: string allOf: - pattern: ^prin_[0-9a-f]{32}$ EventId: type: string allOf: - pattern: ^evt_[0-9a-f]{32}$ Objects_113: type: object properties: id: $ref: '#/components/schemas/ConversationBindingId' workspace_id: $ref: '#/components/schemas/WorkspaceId' external_installation_id: $ref: '#/components/schemas/CollaborationInstallationId' agent_installation_id: $ref: '#/components/schemas/AgentInstallationId' surface_scope_id: $ref: '#/components/schemas/SurfaceScopeId' conversation: $ref: '#/components/schemas/Union_197' session_id: $ref: '#/components/schemas/SessionId' projection_policy: $ref: '#/components/schemas/Objects_114' state: $ref: '#/components/schemas/Union_199' replaced_by: anyOf: - $ref: '#/components/schemas/ConversationBindingId' - type: 'null' last_projected_message_id: anyOf: - type: string allOf: - minLength: 1 - maxLength: 512 - type: 'null' reconciliation_cursor: anyOf: - type: string allOf: - minLength: 1 - maxLength: 512 - type: 'null' last_projected_event_sequence: type: integer allOf: - exclusiveMinimum: 0 created_at: type: string updated_at: type: string required: - id - workspace_id - external_installation_id - surface_scope_id - conversation - session_id - state - replaced_by - last_projected_message_id - reconciliation_cursor - created_at - updated_at additionalProperties: false SessionId: type: string allOf: - pattern: ^sess_[0-9a-f]{32}$ WorkspaceId: type: string allOf: - pattern: ^wrkspc_[0-9a-f]{32}$ 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. SessionDriveBadRequestError: anyOf: - $ref: '#/components/schemas/ValidationMalformedError' - $ref: '#/components/schemas/ValidationPromptIntegrityReviewRequiredError' description: >- A Session drive request was malformed or requires explicit prompt-integrity review. 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. ValidationNotFoundError: type: object properties: error: type: object properties: type: type: string enum: - validation.not_found message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#validation-not-found description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: >- The requested resource does not exist in the resolved deployment boundary. 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. IdempotencyConflictError: anyOf: - $ref: '#/components/schemas/ValidationIdempotencyConflictError' - $ref: '#/components/schemas/ValidationIdempotencyInProgressError' description: >- An idempotent mutation conflicts with a completed or in-progress request for the same key. RuntimeInvalidTransitionError: type: object properties: error: type: object properties: type: type: string enum: - runtime.invalid_transition message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#runtime-invalid-transition description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: The operation is illegal for the resource's current lifecycle state. ModelNoEligibleModelError: type: object properties: error: type: object properties: type: type: string enum: - model.no_eligible_model message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#model-no-eligible-model description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: No model candidate satisfies the deployment's routing constraints. RuntimeHarnessIncompatibleError: type: object properties: error: type: object properties: type: type: string enum: - runtime.harness_incompatible message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#runtime-harness-incompatible description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: The harness does not satisfy the required protocol or capability set. RuntimeInternalError: type: object properties: error: type: object properties: type: type: string enum: - runtime.internal message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#runtime-internal description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: >- An unexpected internal failure occurred; the message contains an opaque incident reference. RuntimeRunnerUnavailableError: type: object properties: error: type: object properties: type: type: string enum: - runtime.runner_unavailable message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#runtime-runner-unavailable description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: No eligible Runner can currently claim the work. ModelPlatformSupplyUnavailableError: type: object properties: error: type: object properties: type: type: string enum: - model.platform_supply_unavailable message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#model-platform-supply-unavailable description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: Platform-managed model credentials are temporarily unavailable. ConversationBindingId: type: string allOf: - pattern: ^conv_[0-9a-f]{32}$ Objects_114: type: object properties: role: type: string enum: - interaction - delivery classes: type: array items: $ref: '#/components/schemas/Union_198' allOf: - minItems: 1 - maxItems: 5 delivery_grade: type: string enum: - provider_idempotent - reconcilable - at_most_once_on_ambiguity required: - role - classes additionalProperties: false Union_199: type: string enum: - active - replaced - archived ValidationPromptIntegrityReviewRequiredError: type: object properties: error: type: object properties: type: type: string enum: - validation.prompt_integrity_review_required message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#validation-prompt-integrity-review-required description: Stable public documentation and remedy for this error type. review: type: object properties: analyzer_version: type: string enum: - unicode-17.0.0-uts39-r32-checkfu-1 normalized: type: string findings: type: array items: $ref: '#/components/schemas/Union_200' allOf: - minItems: 1 - maxItems: 256 required: - analyzer_version - normalized - findings additionalProperties: false required: - type - message - more - review additionalProperties: false required: - error additionalProperties: false description: The request contains deceptive Unicode and requires an explicit review. ValidationIdempotencyConflictError: type: object properties: error: type: object properties: type: type: string enum: - validation.idempotency_conflict message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#validation-idempotency-conflict description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: The Idempotency-Key is already bound to a different request. ValidationIdempotencyInProgressError: type: object properties: error: type: object properties: type: type: string enum: - validation.idempotency_in_progress message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#validation-idempotency-in-progress description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: >- An identical idempotent request is still in progress and may be retried later. Union_198: type: string enum: - input - progress - question - result - failure Union_200: anyOf: - type: object properties: kind: type: string enum: - mixed_script_confusable utf16_offset: type: integer allOf: - minimum: 0 code_point: type: string allOf: - pattern: ^U\+[0-9A-F]{4,6}$ replacement: type: string allOf: - maxLength: 5 answer_id: type: string value_index: type: integer allOf: - minimum: 0 required: - kind - utf16_offset - code_point - replacement additionalProperties: false - type: object properties: kind: type: string enum: - bidirectional_control utf16_offset: type: integer allOf: - minimum: 0 code_point: type: string allOf: - pattern: ^U\+[0-9A-F]{4,6}$ answer_id: type: string value_index: type: integer allOf: - minimum: 0 required: - kind - utf16_offset - code_point additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer ````