API docs by Redocly

Agent Observability API (1.0)

Download OpenAPI specification:

APIs for querying agent traces from OpenSearch.

access

Get the current BKN Trace access profile

Returns server-derived page capabilities and a scope fingerprint. Roles and managed resource identifiers are never accepted from or disclosed to the client.

Responses

Response samples

Content type
application/json
{
  • "access_scope_fingerprint": "string",
  • "allowed_log_categories": [
    ],
  • "business_provenance_managed_networks": true,
  • "business_provenance_own": true,
  • "global_log_search": true,
  • "log_export": true,
  • "log_policy_read": true,
  • "log_sensitive_fields": true,
  • "management_audit": true,
  • "observability_archive_manage": true,
  • "security_audit": true,
  • "technical_trace": true
}

lifecycle

List managed Conversations in the authorized owner scope

Authorizations:
BearerAuth
query Parameters
limit
integer

Page size, 1..100

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

Create or return the current managed Conversation

Authorizations:
BearerAuth
header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Managed Conversation request

external_conversation_key
required
string
idempotency_key
string
one_shot
boolean

Responses

Request samples

Content type
application/json
{
  • "external_conversation_key": "string",
  • "idempotency_key": "string",
  • "one_shot": true
}

Response samples

Content type
application/json
{
  • "actor_name_snapshot": "string",
  • "agent_name": "string",
  • "business_context": "string",
  • "closed_at": "string",
  • "conversation_id": "string",
  • "created_at": "string",
  • "creation_auth_method": "string",
  • "creation_request_id": "string",
  • "external_conversation_key": "string",
  • "generation": 0,
  • "one_shot": true,
  • "owner": {
    },
  • "row_version": 0,
  • "status": "active",
  • "updated_at": "string"
}

Get one managed Conversation

Authorizations:
BearerAuth
path Parameters
conversation_id
required
string

Conversation ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Responses

Response samples

Content type
application/json
{
  • "actor_name_snapshot": "string",
  • "agent_name": "string",
  • "business_context": "string",
  • "closed_at": "string",
  • "conversation_id": "string",
  • "created_at": "string",
  • "creation_auth_method": "string",
  • "creation_request_id": "string",
  • "external_conversation_key": "string",
  • "generation": 0,
  • "one_shot": true,
  • "owner": {
    },
  • "row_version": 0,
  • "status": "active",
  • "updated_at": "string"
}

Close one managed Conversation

Authorizations:
BearerAuth
path Parameters
conversation_id
required
string

Conversation ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Idempotent close request

idempotency_key
string

Responses

Request samples

Content type
application/json
{
  • "idempotency_key": "string"
}

Response samples

Content type
application/json
{
  • "actor_name_snapshot": "string",
  • "agent_name": "string",
  • "business_context": "string",
  • "closed_at": "string",
  • "conversation_id": "string",
  • "created_at": "string",
  • "creation_auth_method": "string",
  • "creation_request_id": "string",
  • "external_conversation_key": "string",
  • "generation": 0,
  • "one_shot": true,
  • "owner": {
    },
  • "row_version": 0,
  • "status": "active",
  • "updated_at": "string"
}

Start one managed Interaction

Authorizations:
BearerAuth
path Parameters
conversation_id
required
string

Conversation ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Interaction start request

agent_name
string <= 128 characters
idempotency_key
required
string
lease_seconds
integer
request_hash
string

Responses

Request samples

Content type
application/json
{
  • "agent_name": "string",
  • "idempotency_key": "string",
  • "lease_seconds": 0,
  • "request_hash": "string"
}

Response samples

Content type
application/json
{
  • "closure_manifest": {
    },
  • "conversation_id": "string",
  • "created_at": "string",
  • "evidence_status": "not_applicable",
  • "execution_status": "active",
  • "interaction_id": "string",
  • "lease_epoch": 0,
  • "lease_expires_at": "string",
  • "lease_token": "string",
  • "lease_version": 0,
  • "ordinal": 0,
  • "row_version": 0,
  • "terminal_at": "string",
  • "updated_at": "string"
}

Ensure an idempotent Operation intent and durable Receipt

Authorizations:
BearerAuth
path Parameters
conversation_id
required
string

Conversation ID

interaction_id
required
string

Interaction ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Operation intent

causation_event_ids
Array of strings
required
object (sessionvo.PayloadEnvelope)
lease_epoch
required
integer
lease_token
required
string
operation_key
required
string
parent_operation_id
string
protocol
required
string (sessionvo.OperationProtocol)
Enum: "mcp" "sdk" "internal"
required
boolean
source_module
required
string
tool_name
required
string

Responses

Request samples

Content type
application/json
{
  • "causation_event_ids": [
    ],
  • "input": {
    },
  • "lease_epoch": 0,
  • "lease_token": "string",
  • "operation_key": "string",
  • "parent_operation_id": "string",
  • "protocol": "mcp",
  • "required": true,
  • "source_module": "string",
  • "tool_name": "string"
}

Response samples

Content type
application/json
{
  • "created": true,
  • "execute": true,
  • "operation": {
    },
  • "receipt": {
    }
}

Create a new managed Conversation generation

Authorizations:
BearerAuth
header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

New generation request

external_conversation_key
required
string
idempotency_key
string
one_shot
boolean

Responses

Request samples

Content type
application/json
{
  • "external_conversation_key": "string",
  • "idempotency_key": "string",
  • "one_shot": true
}

Response samples

Content type
application/json
{
  • "actor_name_snapshot": "string",
  • "agent_name": "string",
  • "business_context": "string",
  • "closed_at": "string",
  • "conversation_id": "string",
  • "created_at": "string",
  • "creation_auth_method": "string",
  • "creation_request_id": "string",
  • "external_conversation_key": "string",
  • "generation": 0,
  • "one_shot": true,
  • "owner": {
    },
  • "row_version": 0,
  • "status": "active",
  • "updated_at": "string"
}

Ensure the current managed Conversation

Authorizations:
BearerAuth
header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Managed Conversation request

external_conversation_key
required
string
idempotency_key
string
one_shot
boolean

Responses

Request samples

Content type
application/json
{
  • "external_conversation_key": "string",
  • "idempotency_key": "string",
  • "one_shot": true
}

Response samples

Content type
application/json
{
  • "actor_name_snapshot": "string",
  • "agent_name": "string",
  • "business_context": "string",
  • "closed_at": "string",
  • "conversation_id": "string",
  • "created_at": "string",
  • "creation_auth_method": "string",
  • "creation_request_id": "string",
  • "external_conversation_key": "string",
  • "generation": 0,
  • "one_shot": true,
  • "owner": {
    },
  • "row_version": 0,
  • "status": "active",
  • "updated_at": "string"
}

Resume an active managed Conversation by Core ID

Authorizations:
BearerAuth
header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Conversation resume request

conversation_id
required
string

Responses

Request samples

Content type
application/json
{
  • "conversation_id": "string"
}

Response samples

Content type
application/json
{
  • "actor_name_snapshot": "string",
  • "agent_name": "string",
  • "business_context": "string",
  • "closed_at": "string",
  • "conversation_id": "string",
  • "created_at": "string",
  • "creation_auth_method": "string",
  • "creation_request_id": "string",
  • "external_conversation_key": "string",
  • "generation": 0,
  • "one_shot": true,
  • "owner": {
    },
  • "row_version": 0,
  • "status": "active",
  • "updated_at": "string"
}

Get one managed Interaction

Authorizations:
BearerAuth
path Parameters
interaction_id
required
string

Interaction ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Responses

Response samples

Content type
application/json
{
  • "closure_manifest": {
    },
  • "conversation_id": "string",
  • "created_at": "string",
  • "evidence_status": "not_applicable",
  • "execution_status": "active",
  • "interaction_id": "string",
  • "lease_epoch": 0,
  • "lease_expires_at": "string",
  • "lease_token": "string",
  • "lease_version": 0,
  • "ordinal": 0,
  • "row_version": 0,
  • "terminal_at": "string",
  • "updated_at": "string"
}

Cancel one managed Interaction

Authorizations:
BearerAuth
path Parameters
interaction_id
required
string

Interaction ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Terminal closure manifest

answer_artifact_ref
string
assembler_deadline
string
claims
Array of strings
completion_manifest_version
required
string
completion_reason
required
string
Array of objects (httphandler.expectedOperationRequest)
Array of objects (httphandler.expectedReceiptRequest)
lease_epoch
required
integer
lease_token
required
string
terminal_idempotency_key
required
string

Responses

Request samples

Content type
application/json
{
  • "answer_artifact_ref": "string",
  • "assembler_deadline": "string",
  • "claims": [
    ],
  • "completion_manifest_version": "string",
  • "completion_reason": "string",
  • "expected_operations": [
    ],
  • "expected_receipts": [
    ],
  • "lease_epoch": 0,
  • "lease_token": "string",
  • "terminal_idempotency_key": "string"
}

Response samples

Content type
application/json
{
  • "closure_manifest": {
    },
  • "conversation_id": "string",
  • "created_at": "string",
  • "evidence_status": "not_applicable",
  • "execution_status": "active",
  • "interaction_id": "string",
  • "lease_epoch": 0,
  • "lease_expires_at": "string",
  • "lease_token": "string",
  • "lease_version": 0,
  • "ordinal": 0,
  • "row_version": 0,
  • "terminal_at": "string",
  • "updated_at": "string"
}

Complete one managed Interaction

Authorizations:
BearerAuth
path Parameters
interaction_id
required
string

Interaction ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Terminal closure manifest

answer_artifact_ref
string
assembler_deadline
string
claims
Array of strings
completion_manifest_version
required
string
completion_reason
required
string
Array of objects (httphandler.expectedOperationRequest)
Array of objects (httphandler.expectedReceiptRequest)
lease_epoch
required
integer
lease_token
required
string
terminal_idempotency_key
required
string

Responses

Request samples

Content type
application/json
{
  • "answer_artifact_ref": "string",
  • "assembler_deadline": "string",
  • "claims": [
    ],
  • "completion_manifest_version": "string",
  • "completion_reason": "string",
  • "expected_operations": [
    ],
  • "expected_receipts": [
    ],
  • "lease_epoch": 0,
  • "lease_token": "string",
  • "terminal_idempotency_key": "string"
}

Response samples

Content type
application/json
{
  • "closure_manifest": {
    },
  • "conversation_id": "string",
  • "created_at": "string",
  • "evidence_status": "not_applicable",
  • "execution_status": "active",
  • "interaction_id": "string",
  • "lease_epoch": 0,
  • "lease_expires_at": "string",
  • "lease_token": "string",
  • "lease_version": 0,
  • "ordinal": 0,
  • "row_version": 0,
  • "terminal_at": "string",
  • "updated_at": "string"
}

Fail one managed Interaction

Authorizations:
BearerAuth
path Parameters
interaction_id
required
string

Interaction ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Terminal closure manifest

answer_artifact_ref
string
assembler_deadline
string
claims
Array of strings
completion_manifest_version
required
string
completion_reason
required
string
Array of objects (httphandler.expectedOperationRequest)
Array of objects (httphandler.expectedReceiptRequest)
lease_epoch
required
integer
lease_token
required
string
terminal_idempotency_key
required
string

Responses

Request samples

Content type
application/json
{
  • "answer_artifact_ref": "string",
  • "assembler_deadline": "string",
  • "claims": [
    ],
  • "completion_manifest_version": "string",
  • "completion_reason": "string",
  • "expected_operations": [
    ],
  • "expected_receipts": [
    ],
  • "lease_epoch": 0,
  • "lease_token": "string",
  • "terminal_idempotency_key": "string"
}

Response samples

Content type
application/json
{
  • "closure_manifest": {
    },
  • "conversation_id": "string",
  • "created_at": "string",
  • "evidence_status": "not_applicable",
  • "execution_status": "active",
  • "interaction_id": "string",
  • "lease_epoch": 0,
  • "lease_expires_at": "string",
  • "lease_token": "string",
  • "lease_version": 0,
  • "ordinal": 0,
  • "row_version": 0,
  • "terminal_at": "string",
  • "updated_at": "string"
}

Finish one Interaction through the Agent-facing facade

Derives the current lease and closure manifest from authoritative Operations and Receipts. Ordinary Agents do not submit concurrency or closure internals.

Authorizations:
BearerAuth
path Parameters
interaction_id
required
string

Interaction ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Managed finish request

answer_artifact_ref
string
claims
Array of strings
idempotency_key
required
string
outcome
required
string
reason
string

Responses

Request samples

Content type
application/json
{
  • "answer_artifact_ref": "string",
  • "claims": [
    ],
  • "idempotency_key": "string",
  • "outcome": "string",
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "closure_manifest": {
    },
  • "conversation_id": "string",
  • "created_at": "string",
  • "evidence_status": "not_applicable",
  • "execution_status": "active",
  • "interaction_id": "string",
  • "lease_epoch": 0,
  • "lease_expires_at": "string",
  • "lease_token": "string",
  • "lease_version": 0,
  • "ordinal": 0,
  • "row_version": 0,
  • "terminal_at": "string",
  • "updated_at": "string"
}

Hand off one managed Interaction

Authorizations:
BearerAuth
path Parameters
interaction_id
required
string

Interaction ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Terminal closure manifest

answer_artifact_ref
string
assembler_deadline
string
claims
Array of strings
completion_manifest_version
required
string
completion_reason
required
string
Array of objects (httphandler.expectedOperationRequest)
Array of objects (httphandler.expectedReceiptRequest)
lease_epoch
required
integer
lease_token
required
string
terminal_idempotency_key
required
string

Responses

Request samples

Content type
application/json
{
  • "answer_artifact_ref": "string",
  • "assembler_deadline": "string",
  • "claims": [
    ],
  • "completion_manifest_version": "string",
  • "completion_reason": "string",
  • "expected_operations": [
    ],
  • "expected_receipts": [
    ],
  • "lease_epoch": 0,
  • "lease_token": "string",
  • "terminal_idempotency_key": "string"
}

Response samples

Content type
application/json
{
  • "closure_manifest": {
    },
  • "conversation_id": "string",
  • "created_at": "string",
  • "evidence_status": "not_applicable",
  • "execution_status": "active",
  • "interaction_id": "string",
  • "lease_epoch": 0,
  • "lease_expires_at": "string",
  • "lease_token": "string",
  • "lease_version": 0,
  • "ordinal": 0,
  • "row_version": 0,
  • "terminal_at": "string",
  • "updated_at": "string"
}

List raw Operation call facts for one Interaction

Authorizations:
BearerAuth
path Parameters
interaction_id
required
string

Interaction ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total": 0
}

Get one Operation

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Responses

Response samples

Content type
application/json
{
  • "attempt": 0,
  • "attempt_status": "ready",
  • "causation_event_ids": [
    ],
  • "conversation_id": "string",
  • "created_at": "string",
  • "interaction_id": "string",
  • "operation_id": "string",
  • "operation_key": "string",
  • "parent_operation_id": "string",
  • "retryable": true,
  • "row_version": 0,
  • "tool_name": "string",
  • "updated_at": "string"
}

Start the next retry attempt for an Operation

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Current Interaction lease

lease_epoch
required
integer
lease_token
required
string

Responses

Request samples

Content type
application/json
{
  • "lease_epoch": 0,
  • "lease_token": "string"
}

Response samples

Content type
application/json
{
  • "created": true,
  • "execute": true,
  • "operation": {
    },
  • "receipt": {
    }
}

Get one authorized Operation attempt call fact

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

attempt
required
integer

Attempt number

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Responses

Response samples

Content type
application/json
{
  • "attempt": 0,
  • "conversation_id": "string",
  • "error": {
    },
  • "finished_at": "string",
  • "input": {
    },
  • "interaction_id": "string",
  • "operation_id": "string",
  • "output": {
    },
  • "parent_operation_id": "string",
  • "protocol": "mcp",
  • "receipt_id": "string",
  • "request_id": "string",
  • "retryable": true,
  • "source_module": "string",
  • "span_id": "string",
  • "started_at": "string",
  • "status": "ready",
  • "tool_name": "string",
  • "trace_id": "string"
}

Complete one Operation attempt

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

attempt
required
integer

Attempt number

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Durable operation result

artifact_refs
Array of strings
Array of objects (sessionvo.BusinessRef)
object (sessionvo.PayloadEnvelope)
evidence_durability
required
string (sessionvo.EvidenceDurability)
Enum: "pending" "durable" "failed"
observed_evidence_refs
Array of strings
object (sessionvo.PayloadEnvelope)
partial_reasons
Array of strings
receipt_id
required
string
request_id
required
string
retryable
boolean
span_id
string
trace_id
required
string

Responses

Request samples

Content type
application/json
{
  • "artifact_refs": [
    ],
  • "business_refs": [
    ],
  • "error": {
    },
  • "evidence_durability": "pending",
  • "observed_evidence_refs": [
    ],
  • "output": {
    },
  • "partial_reasons": [
    ],
  • "receipt_id": "string",
  • "request_id": "string",
  • "retryable": true,
  • "span_id": "string",
  • "trace_id": "string"
}

Response samples

Content type
application/json
{
  • "created": true,
  • "execute": true,
  • "operation": {
    },
  • "receipt": {
    }
}

Fail one Operation attempt

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

attempt
required
integer

Attempt number

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Request Body schema: application/json
required

Durable operation failure

artifact_refs
Array of strings
Array of objects (sessionvo.BusinessRef)
object (sessionvo.PayloadEnvelope)
evidence_durability
required
string (sessionvo.EvidenceDurability)
Enum: "pending" "durable" "failed"
observed_evidence_refs
Array of strings
object (sessionvo.PayloadEnvelope)
partial_reasons
Array of strings
receipt_id
required
string
request_id
required
string
retryable
boolean
span_id
string
trace_id
required
string

Responses

Request samples

Content type
application/json
{
  • "artifact_refs": [
    ],
  • "business_refs": [
    ],
  • "error": {
    },
  • "evidence_durability": "pending",
  • "observed_evidence_refs": [
    ],
  • "output": {
    },
  • "partial_reasons": [
    ],
  • "receipt_id": "string",
  • "request_id": "string",
  • "retryable": true,
  • "span_id": "string",
  • "trace_id": "string"
}

Response samples

Content type
application/json
{
  • "created": true,
  • "execute": true,
  • "operation": {
    },
  • "receipt": {
    }
}

Get one durable Receipt

Authorizations:
BearerAuth
path Parameters
receipt_id
required
string

Receipt ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Responses

Response samples

Content type
application/json
{
  • "artifact_refs": [
    ],
  • "attempt": 0,
  • "business_refs": [
    ],
  • "causation_event_ids": [
    ],
  • "conversation_id": "string",
  • "evidence_durability": "pending",
  • "interaction_id": "string",
  • "issued_at": "string",
  • "observed_evidence_refs": [
    ],
  • "operation_id": "string",
  • "operation_key": "string",
  • "owner": {
    },
  • "partial_reasons": [
    ],
  • "receipt_id": "string",
  • "receipt_status": "pending",
  • "request_id": "string",
  • "required": true,
  • "row_version": 0,
  • "schema_version": "string",
  • "terminal_at": "string",
  • "tool_name": "string",
  • "trace_id": "string"
}

List request projections from durable Receipts

Authorizations:
BearerAuth
query Parameters
limit
integer

Page size, 1..100

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "next_cursor": "string"
}

Get one request projection from durable Receipts

Authorizations:
BearerAuth
path Parameters
request_id
required
string

Request ID

header Parameters
x-business-domain
required
string

Deployment-approved business domain

Responses

Response samples

Content type
application/json
{
  • "conversation_id": "string",
  • "interaction_id": "string",
  • "operation_count": 0,
  • "receipt_count": 0,
  • "request_id": "string",
  • "trace_ids": [
    ],
  • "updated_at": "string"
}

evidence

Ingest a BKN Trace 2.2 evidence artifact

Stores authorized business content separately from evidence events. Inline content and snapshot_ref are mutually exclusive.

Request Body schema: application/json
required

BKN Trace 2.2 evidence artifact

agent_or_app
string
application_principal_id
string
artifact_id
string
artifact_type
string (evidencevo.ArtifactType)
Enum: "question" "result" "query" "data_result" "logic_execution" "action_input" "action_result"
as_of
string
bkn.account.id
string
bkn.account.type
string
bkn.request.id
string
bkn.tenant.id
string
business_domain
string
business_refs
Array of strings
claim_id
string
content
any
content_hash
string
content_type
string
effective_subject_id
string
initiator
string
interaction_id
string
knowledge_network_ids
Array of strings
observed_at
string
operation_id
string
schema_version
string
snapshot_ref
string
source_ref
string
source_version
string
trace_id
string

Responses

Request samples

Content type
application/json
{
  • "agent_or_app": "string",
  • "application_principal_id": "string",
  • "artifact_id": "string",
  • "artifact_type": "question",
  • "as_of": "string",
  • "bkn.account.id": "string",
  • "bkn.account.type": "string",
  • "bkn.request.id": "string",
  • "bkn.tenant.id": "string",
  • "business_domain": "string",
  • "business_refs": [
    ],
  • "claim_id": "string",
  • "content": null,
  • "content_hash": "string",
  • "content_type": "string",
  • "effective_subject_id": "string",
  • "initiator": "string",
  • "interaction_id": "string",
  • "knowledge_network_ids": [
    ],
  • "observed_at": "string",
  • "operation_id": "string",
  • "schema_version": "string",
  • "snapshot_ref": "string",
  • "source_ref": "string",
  • "source_version": "string",
  • "trace_id": "string"
}

Response samples

Content type
application/json
{
  • "artifact_id": "string",
  • "artifact_type": "question",
  • "bkn.request.id": "string",
  • "content_hash": "string",
  • "created": true,
  • "trace_id": "string"
}

Get an authorized evidence artifact by ID

Returns an artifact through its own record scope, or through an authorized Interaction when interaction_id is supplied.

path Parameters
artifact_id
required
string

Artifact ID

query Parameters
interaction_id
string

Authorized Interaction ID

Responses

Response samples

Content type
application/json
{
  • "agent_or_app": "string",
  • "application_principal_id": "string",
  • "artifact_id": "string",
  • "artifact_type": "question",
  • "as_of": "string",
  • "bkn.account.id": "string",
  • "bkn.account.type": "string",
  • "bkn.request.id": "string",
  • "bkn.tenant.id": "string",
  • "business_domain": "string",
  • "business_refs": [
    ],
  • "claim_id": "string",
  • "content": null,
  • "content_hash": "string",
  • "content_type": "string",
  • "effective_subject_id": "string",
  • "initiator": "string",
  • "interaction_id": "string",
  • "knowledge_network_ids": [
    ],
  • "observed_at": "string",
  • "operation_id": "string",
  • "schema_version": "string",
  • "snapshot_ref": "string",
  • "source_ref": "string",
  • "source_version": "string",
  • "trace_id": "string"
}

Durably ingest one BKN Trace 3.0 evidence event

Commits the immutable Evidence Ledger record and Projection Outbox in one transaction before returning durable_ack.

Request Body schema: application/json
required

BKN Trace 3.0 evidence event

artifact_refs
Array of strings
attempt
integer
bkn.trace.schema.version
required
string
Array of objects (sessionvo.BusinessRef)
causation_event_ids
Array of strings
Array of objects (sessionvo.Claim)
conversation_id
required
string
emitted_at
required
string
envelope
required
Array of integers
event_id
required
string
event_type
required
string
Array of objects (sessionvo.EvidenceRef)
interaction_id
required
string
observed_at
required
string
Array of objects (sessionvo.OperationBusinessEdge)
operation_id
string
payload_hash
required
string
producer_epoch
required
integer
producer_id
required
string
producer_sequence
required
integer
producer_stream_id
required
string
request_id
string
span_id
string
started_at
required
string
trace_id
string

Responses

Request samples

Content type
application/json
{
  • "artifact_refs": [
    ],
  • "attempt": 0,
  • "bkn.trace.schema.version": "string",
  • "business_refs": [
    ],
  • "causation_event_ids": [
    ],
  • "claims": [
    ],
  • "conversation_id": "string",
  • "emitted_at": "string",
  • "envelope": [
    ],
  • "event_id": "string",
  • "event_type": "string",
  • "evidence_refs": [
    ],
  • "interaction_id": "string",
  • "observed_at": "string",
  • "operation_business_edges": [
    ],
  • "operation_id": "string",
  • "payload_hash": "string",
  • "producer_epoch": 0,
  • "producer_id": "string",
  • "producer_sequence": 0,
  • "producer_stream_id": "string",
  • "request_id": "string",
  • "span_id": "string",
  • "started_at": "string",
  • "trace_id": "string"
}

Response samples

Content type
application/json
{
  • "durable_ack": true,
  • "event_id": "string",
  • "ingest_sequence": 0,
  • "ingested_at": "string",
  • "replayed": true
}

Get an Interaction business semantic graph

Returns the latest immutable assembly revision with precise Claim supports and causal DAG layers. Objective evidence completeness is separate from current-user disclosure completeness; unresolved or unauthorized business refs and their edges are omitted.

path Parameters
interaction_id
required
string

Interaction ID

Responses

Response samples

Content type
application/json
{
  • "assembly": {
    },
  • "assembly_revision": {
    },
  • "conversation_id": "string",
  • "evidence_status": "not_applicable",
  • "execution_status": "active",
  • "interaction_id": "string"
}

traces

List technical trace executions

Returns stable trace summaries with reverse request links, generated from authorized trace evidence.

query Parameters
limit
integer

Page size, 1..200

cursor
string

Opaque pagination cursor

trace_id
string

Exact trace ID; bypasses list projection scan

conversation_id
string

Caller-owned conversation ID

interaction_id
string

One user interaction ID

from
string

Started at or after this RFC3339 timestamp

to
string

Started at or before this RFC3339 timestamp

status
string

Execution status

agent_or_app
string

Agent or application

business_domain
string

Business domain

keyword
string

Trace, request, operation, or error keyword

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "next_cursor": "string",
  • "page": 0,
  • "page_size": 0,
  • "partial": true,
  • "partial_reasons": [
    ],
  • "total": 0,
  • "truncated": true
}

Get one typed technical trace

Returns the authorized trace summary, Span graph, and ordered raw Operation call facts. Operation facts remain visible without Span data; Span nodes remain visible without Operation facts.

path Parameters
trace_id
required
string

Trace ID

Responses

Response samples

Content type
application/json
{
  • "graph": {
    },
  • "operations": [
    ],
  • "partial": true,
  • "partial_reasons": [
    ],
  • "summary": {
    }
}