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.

POST /v1/conversation-bindings/ingest

Ingest one verified provider conversation event

cURL

curl --request POST \
  --url https://api.checkfu.com/v1/conversation-bindings/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "external_installation_id": "<string>",
  "agent_installation_id": "<string>",
  "surface_scope_id": "<string>",
  "conversation": {
    "root_external_id": "<string>",
    "thread_external_id": null
  },
  "external_event_id": "<string>",
  "principal": "<string>",
  "input": {
    "kind": "invoke",
    "content": "<string>",
    "is_direct_mention": true,
    "author_restricted": true,
    "observation": "<unknown>",
    "message_external_id": "<unknown>"
  },
  "occurred_at": "<string>",
  "session_id": "<unknown>",
  "agent": "<unknown>",
  "agent_deployment_revision_selection": "<unknown>",
  "mounts": "<unknown>",
  "acted_as": "<unknown>",
  "caused_by": "<unknown>",
  "harness": "<unknown>",
  "model_routing_profile_key": "<unknown>",
  "sandbox_profile_key": "<unknown>"
}
'

200

{
  "event_id": "<string>",
  "binding": {
    "id": "<string>",
    "workspace_id": "<string>",
    "external_installation_id": "<string>",
    "surface_scope_id": "<string>",
    "conversation": {
      "kind": "ambient",
      "root_external_id": "<string>",
      "thread_external_id": null
    },
    "session_id": "<string>",
    "state": "active",
    "replaced_by": "<string>",
    "last_projected_message_id": "<string>",
    "reconciliation_cursor": "<string>",
    "created_at": "<string>",
    "updated_at": "<string>",
    "agent_installation_id": "<string>",
    "projection_policy": {
      "role": "interaction",
      "classes": [
        "input"
      ],
      "delivery_grade": "provider_idempotent"
    },
    "last_projected_event_sequence": 1
  },
  "session_id": "<string>",
  "disposition": "driven",
  "silence_reason": "disabled"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-27

idempotency-key · string

Maximum string length: 255

Body

application/json

Option 1

Option 2

external_installation_id · string · required

Pattern: ^exti_[0-9a-f]{32}$

agent_installation_id · string · required

Pattern: ^aini_[0-9a-f]{32}$

surface_scope_id · string · required

Pattern: ^surf_[0-9a-f]{32}$

conversation · object · required

Option 1

Option 2

Show child attributes

external_event_id · string · required

Required string length: 1 - 512

principal · string · required

Pattern: ^prin_[0-9a-f]{32}$

input · object · required

Show child attributes

occurred_at · string

session_id · any

agent · any

agent_deployment_revision_selection · any

mounts · any

acted_as · any

caused_by · any

harness · any

model_routing_profile_key · any

sandbox_profile_key · any

Response

200

application/json

Success

Option 1

Option 2

event_id · string | null · required

Pattern: ^evt_[0-9a-f]{32}$

binding · object · required

Show child attributes

session_id · string · required

Pattern: ^sess_[0-9a-f]{32}$

disposition · enum<string> · required

Available options: driven, observed, replayed, filtered

silence_reason · enum<string> | null

Available options: disabled, muted, restricted_author, rate_limited, budget_exhausted, busy, self_quieted, not_answerable, uncertain