All

Data-source schemas

Request, mapping, sampling, preview, and lifecycle contracts for the Data Sources REST API.

These schemas describe JSON exchanged by the Data Sources API. Tables use the serialized JSON field names, including sourceRecords, messageId, kindField, and idField. Fields marked Yes are required. Omitted optional fields use the listed defaults. These contracts reject unknown fields. Explicit JSON null is valid only when included in the type. String lengths count characters; array limits count items. Cross-field validation and lifecycle rules still apply.

Mapping semantics

Mappings use JSON Pointers (/output/message/content), while provider traffic filters use dotted paths (metadata.environment). A blank mapping path explicitly leaves the field unmapped. fallback is another pointer within the same field scope. scope can be current, root, or related.NAME; named related sources require mapping version 2, the span turn layout, and exactly one matching supporting span. Missing or ambiguous required evidence remains held.

A mapping rule must include exactly these ten fields keys:

Key	Purpose	Default pointer
`user`	Stable user identity.	`/metadata/user_id`
`session`	Conversation identity.	`/metadata/session_id`
`input`	User message.	`/input`
`output`	Agent response.	`/output`
`version`	Agent version for evaluation.	`/metadata/agent_version`
`references`	Learnings actually injected into this response.	`/metadata/reflexio/retrieved_learnings`
`source`	Request source label.	`/metadata/environment`
`timestamp`	Event creation timestamp.	`/created`
`completion`	Completion evidence.	`/metrics/end`

These are schema defaults, not a claim that your provider logs those fields. A newly opened unmapped draft can have blank paths instead. Read its definition or explicitly supply all fields. Constants are supported only for source and version.

Transform	Behavior and restrictions
`none`	Use the selected field without conversion.
`string`	Explicit scalar-to-string conversion.
`json`	Decode JSON references; only valid for `references`.
`first_text_block`	Input/output only: first usable direct text block in one message's array.
`text_blocks`	Input/output only: join usable direct text blocks with newlines.

Text-block transforms reject conversation-shaped arrays and arrays over 100 entries. Selected text must fit 100,000 characters; text_blocks also checks the joined result. See text selection and upgrades for block eligibility and draft promotion.

A rule's when predicates are combined with AND; multiple rules matching the same record are a conflict, not first-match-wins. Predicate eq needs one value, in needs at least one, and exists takes no values. Up to 20 values of at most 512 characters are accepted. Named related selectors use current scope to inspect candidate supporting spans; correlations express equality between current and related pointers. They do not join unrelated traces.

`turn_layout`	Meaning
`span`	One response span and its mapped input/output.
`turn_array`	One complete message array. Requires `messages_path`.
`history_ids`	Repeated conversation history with stable message IDs. Requires `messages_path`.
`history_append`	Repeated append-only history. Requires `messages_path`.
`message_event`	Individual message events with sequence/settling controls.

History/event layouts require history_branch_path or an explicit history_unbranched: true. Internal system/tool/function/developer roles cannot be remapped into conversation messages for these layouts. See the conversation format guide for identity, ordering, late-message and history-edit behavior. Preview and canonical admission use the same mapping rules.

Request and response field tables

MappingDefinition and its nested defaults are expanded in the tables below. Large object defaults are described by their schema rather than repeated in every row. Collection status, retry results, evidence and setup-context dictionaries are documented with their endpoints in the API reference.

ConnectionInput

Field	Type	Required	Default	Constraints / meaning
`api_key`	`string`	Yes	—	min length: 1; max length: 4096; format: `password`; Provider read credential; never a Reflexio key.
`public_key`	`string or null`	No	`null`	min length: 1; max length: 4096
`workspace_id`	`string or null`	No	`null`	min length: 1; max length: 512
`provider`	`"braintrust" / "langfuse" / "langsmith"`	No	`"braintrust"`	—
`region`	`"us" / "eu" / "jp" / "hipaa-us"`	No	`"us"`	—
`name`	`string`	Yes	—	min length: 1; max length: 120

RotationInput

Field	Type	Required	Default	Constraints / meaning
`api_key`	`string`	Yes	—	min length: 1; max length: 4096; format: `password`
`public_key`	`string or null`	No	`null`	min length: 1; max length: 4096
`workspace_id`	`string or null`	No	`null`	min length: 1; max length: 512
`revision`	`integer`	Yes	—	minimum: 1; Current connection revision.

RevisionInput

Field	Type	Required	Default	Constraints / meaning
`revision`	`integer`	Yes	—	minimum: 1; Current connection revision for deletion.
`lifecycle_revision`	`integer or null`	No	`null`	minimum: 1; Also supply the current lifecycle revision when deleting an activated source.

StreamInput

Field	Type	Required	Default	Constraints / meaning
`revision`	`integer`	Yes	—	minimum: 1; Current connection revision.
`lifecycle_revision`	`integer or null`	No	`null`	minimum: 1; Inherited field; does not permit editing an activated selection.
`external_project_id`	`string`	Yes	—	min length: 1; max length: 512
`filters`	`array of TrafficFilter`	No	`[]`	max items: 10

TrafficFilter

Field	Type	Required	Default	Constraints / meaning
`path`	`string`	Yes	—	max length: 160; pattern: `^(metadata\.[A-Za-z0-9_.-]+\|span_attributes\.name\|tags)$`
`op`	`"eq" / "in" / "exists"`	Yes	—	—
`values`	`array of string`	No	`[]`	max items: 20

SampleInput

Field	Type	Required	Default	Constraints / meaning
`revision`	`integer`	Yes	—	minimum: 1; Current stream revision.
`lifecycle_revision`	`integer or null`	No	`null`	minimum: 1; Inherited optional field; sampling is checked against the stream revision.
`sample_window`	`SampleWindow or null`	No	`null`	—

SampleWindow

Field	Type	Required	Default	Constraints / meaning
`start`	`string`	Yes	—	format: `date-time`
`end`	`string`	Yes	—	format: `date-time`

Connection

Field	Type	Required	Default	Constraints / meaning
`id`	`string`	Yes	—	—
`project_id`	`string`	Yes	—	—
`name`	`string`	Yes	—	—
`provider`	`"braintrust" / "langfuse" / "langsmith"`	No	`"braintrust"`	—
`region`	`"us" / "eu" / "jp" / "hipaa-us"`	No	`"us"`	—
`revision`	`integer`	Yes	—	—
`credential_version`	`integer`	Yes	—	—
`expires_at`	`number or null`	Yes	—	—

ExternalProject

Field	Type	Required	Default	Constraints / meaning
`id`	`string`	Yes	—	min length: 1; max length: 512
`workspace_id`	`string`	Yes	—	min length: 1; max length: 512
`name`	`string`	Yes	—	—

Discovery

Field	Type	Required	Default	Constraints / meaning
`projects`	`array of ExternalProject`	Yes	—	—
`truncated`	`boolean`	No	`false`	—

Stream

Field	Type	Required	Default	Constraints / meaning
`id`	`string`	Yes	—	—
`connection_id`	`string`	Yes	—	—
`project_id`	`string`	Yes	—	—
`external_project_id`	`string`	Yes	—	min length: 1; max length: 512
`workspace_id`	`string`	Yes	—	min length: 1; max length: 512
`revision`	`integer`	Yes	—	—
`filters`	`array of TrafficFilter`	Yes	—	—
`filter_execution`	`"before_download" / "partial" / "after_download"`	No	`"before_download"`	—
`status`	`"draft"`	No	`"draft"`	Setup marker only; read the status endpoint for lifecycle.
`expires_at`	`number or null`	Yes	—	—

SampleBucket

Field	Type	Required	Default	Constraints / meaning
`start`	`string`	Yes	—	format: `date-time`
`end`	`string`	Yes	—	format: `date-time`
`status`	`"sampled" / "empty" / "unread"`	No	`"unread"`	—
`retained`	`integer`	No	`0`	—
`code`	`string or null`	No	`null`	—

Sample

Field	Type	Required	Default	Constraints / meaning
`retry_at`	`number`	No	`0`	—
`buckets`	`array of SampleBucket`	No	`[]`	—
`example_ids`	`array of string`	No	`[]`	—
`sample_window`	`SampleWindow or null`	No	`null`	—
`id`	`string`	Yes	—	—
`stream_id`	`string`	Yes	—	—
`project_id`	`string`	Yes	—	—
`status`	`"queued" / "running" / "complete" / "failed" / "expired"`	Yes	—	—
`expires_at`	`number`	Yes	—	—
`records`	`array of object`	No	`[]`	Retained provider evidence, not canonical interactions.
`truncated`	`boolean`	No	`false`	—
`coverage`	`string`	No	`"Bounded recent snapshot; conversation completeness is not established."`	—
`code`	`string or null`	No	`null`	—

Inspection

Field	Type	Required	Default	Constraints / meaning
`connections`	`array of Connection`	Yes	—	—
`streams`	`array of Stream`	Yes	—	—
`samples`	`array of Sample`	Yes	—	Inventory sample summaries; read the sample endpoint for records.
`mapping_available`	`boolean`	No	`true`	—
`activation_available`	`boolean`	No	`true`	—
`sample_row_limit`	`integer`	No	`50`	—
`sample_ttl_seconds`	`integer`	No	`86400`	—

InitializeMappingInput

Field	Type	Required	Default	Constraints / meaning
`expected_revision`	`integer`	No	`0`	minimum: 0
`sample_id`	`string`	Yes	—	min length: 1; max length: 100

MappingWrite

Field	Type	Required	Default	Constraints / meaning
`expected_revision`	`integer`	Yes	—	minimum: 0
`definition`	`MappingDefinition`	Yes	—	—

MappingUpgradeInput

Field	Type	Required	Default	Constraints / meaning
`expected_revision`	`integer`	Yes	—	minimum: 1

PreviewInput

Field	Type	Required	Default	Constraints / meaning
`sample_id`	`string`	Yes	—	min length: 1; max length: 100
`expected_revision`	`integer`	Yes	—	minimum: 0
`definition`	`MappingDefinition or null`	No	`null`	Optional unsaved proposal; preview does not save it.

ValidateInput

Field	Type	Required	Default	Constraints / meaning
`sample_id`	`string`	Yes	—	min length: 1; max length: 100
`expected_revision`	`integer`	Yes	—	minimum: 0
`definition`	`MappingDefinition or null`	No	`null`	Must be omitted (or null); validation rejects a supplied definition.
`sample_digest`	`string`	Yes	—	pattern: `^[a-f0-9]{64}$`

SuggestInput

Field	Type	Required	Default	Constraints / meaning
`sample_id`	`string`	Yes	—	min length: 1; max length: 100
`expected_revision`	`integer`	Yes	—	minimum: 0
`definition`	`MappingDefinition or null`	No	`null`	—
`sample_digest`	`string`	Yes	—	pattern: `^[a-f0-9]{64}$`
`consent`	`boolean`	No	`false`	Must be true to request advisory suggestions.

MappingDefinition

Field	Type	Required	Default	Constraints / meaning
`version`	`1 / 2`	No	`1`	—
`rules`	`array of MappingRule`	No	One default MappingRule	min items: 1; max items: 10; 1–10 rules; omitted value supplies one MappingRule with its defaults.
`unmatched`	`"held" / "excluded"`	No	`"held"`	—
`evaluation_only`	`boolean`	No	`false`	—

MappingRule

Field	Type	Required	Default	Constraints / meaning
`related_sources`	`object of RelatedSource`	No	`{}`	max keys: 5
`name`	`string`	No	`"Response"`	min length: 1; max length: 100
`when`	`array of Predicate`	No	`[]`	max items: 10
`layout`	`"standard" / "nested"`	No	`"standard"`	—
`authority`	`"unresolved" / "current" / "root"`	No	`"unresolved"`	—
`fields`	`object of FieldRule`	No	See mapping semantics	Exactly the ten keys listed above; defaults use the listed pointers.
`kindField`	`string`	No	`"/kind"`	max length: 512; pattern: `^(\|/.*)$`
`idField`	`string`	No	`"/learning_id"`	max length: 512; pattern: `^(\|/.*)$`
`reference_response_id_path`	`string`	No	`""`	max length: 512; pattern: `^(\|/.*)$`
`reference_kind`	`"" / "profile" / "user_playbook" / "agent_playbook"`	No	`""`	—
`turn_layout`	`"span" / "turn_array" / "history_ids" / "history_append" / "message_event"`	No	`"span"`	—
`messages_path`	`string`	No	`""`	max length: 512; pattern: `^(\|/.*)$`
`message_content_path`	`string`	No	`"/content"`	max length: 512; pattern: `^/.*$`
`message_role_path`	`string`	No	`"/role"`	max length: 512; pattern: `^/.*$`
`message_references_path`	`string`	No	`"/retrieved_learnings"`	max length: 512; pattern: `^(\|/.*)$`
`role_map`	`object of "User" / "Agent"`	No	See mapping semantics	max keys: 20; Defaults map user/User to User and assistant/Agent to Agent.
`allow_user_only`	`boolean`	No	`false`	—
`message_id_path`	`string`	No	`"/id"`	max length: 512; pattern: `^/.*$`
`history_branch_path`	`string`	No	`""`	max length: 512; pattern: `^(\|/.*)$`
`history_unbranched`	`boolean`	No	`false`	—
`event_sequence_path`	`string`	No	`"/metadata/message_sequence"`	max length: 512; pattern: `^/.*$`
`event_message_path`	`string`	No	`"/metadata/message"`	max length: 512; pattern: `^/.*$`
`event_settle_seconds`	`integer`	No	`15`	minimum: 0; maximum: 300

FieldRule

Field	Type	Required	Default	Constraints / meaning
`scope`	`string`	No	`"current"`	pattern: `^(current\|root\|related\.[a-z][a-z0-9_]{0,39})$`
`path`	`string`	No	`""`	max length: 512; pattern: `^(\|/.*)$`
`fallback`	`string`	No	`""`	max length: 512; pattern: `^(\|/.*)$`
`transform`	`"none" / "string" / "json" / "text_blocks" / "first_text_block"`	No	`"none"`	—
`constant`	`string`	No	`""`	max length: 1000

Predicate

Field	Type	Required	Default	Constraints / meaning
`scope`	`"current" / "root"`	No	`"current"`	—
`path`	`string`	Yes	—	max length: 512; pattern: `^/.*$`
`op`	`"eq" / "in" / "exists"`	No	`"eq"`	—
`values`	`array of string`	No	`[]`	max items: 20

RelatedSource

Field	Type	Required	Default	Constraints / meaning
`when`	`array of Predicate`	Yes	—	min items: 1; max items: 10
`correlations`	`array of Correlation`	No	`[]`	max items: 10

Correlation

Field	Type	Required	Default	Constraints / meaning
`current_path`	`string`	Yes	—	max length: 512; pattern: `^/.*$`
`related_path`	`string`	Yes	—	max length: 512; pattern: `^/.*$`

MappingDocument

Field	Type	Required	Default	Constraints / meaning
`example_id`	`string or null`	No	`null`	—
`example_ids`	`array of string`	No	`[]`	—
`rule_evidence`	`object of string`	No	`{}`	—
`warnings`	`array of string`	No	`[]`	—
`stream_id`	`string`	Yes	—	—
`revision`	`integer`	Yes	—	—
`definition`	`MappingDefinition`	Yes	—	—
`validated_revision`	`integer or null`	No	`null`	—

PreviewResult

Field	Type	Required	Default	Constraints / meaning
`field_guidance`	`array of FieldGuidance`	No	`[]`	—
`records`	`array of TurnProposal`	Yes	—	—
`ready`	`integer`	Yes	—	—
`held`	`integer`	Yes	—	—
`excluded`	`integer`	Yes	—	—
`sourceRecords`	`integer`	Yes	—	—
`messages`	`integer`	Yes	—	—
`sample_digest`	`string`	Yes	—	—
`mapping_revision`	`integer`	Yes	—	—
`mapping_digest`	`string`	Yes	—	—
`policy_digest`	`string`	Yes	—	—
`blockers`	`array of MappingBlocker`	No	`[]`	—
`rule_coverage`	`array of RuleCoverage`	No	`[]`	—
`advisory`	`boolean`	No	`true`	—

TurnProposal

Field	Type	Required	Default	Constraints / meaning
`id`	`string`	Yes	—	—
`messageId`	`string`	Yes	—	—
`user`	`string`	No	`""`	—
`session`	`string`	No	`""`	—
`input`	`string`	No	`""`	—
`output`	`string`	No	`""`	—
`version`	`string`	No	`""`	—
`source`	`string`	No	`""`	—
`references`	`array of object of string`	No	`[]`	—
`capture`	`"missing" / "empty" / "valid" / "malformed" / "unresolvable" / "ambiguous"`	No	`"missing"`	—
`diagnostics`	`array of string`	No	`[]`	—
`errors`	`array of string`	No	`[]`	—
`provenance`	`object of string`	No	`{}`	—
`messages`	`array of object`	No	`[]`	—
`disposition`	`"ready" / "held" / "excluded"`	No	`"held"`	—
`evaluation_readiness`	`string`	No	`"unknown_version"`	—
`learning_eligibility`	`object`	No	`{}`	—
`rule_name`	`string`	No	`""`	—
`history`	`object`	No	`{}`	—

FieldGuidance

Field	Type	Required	Default	Constraints / meaning
`code`	`string`	Yes	—	—
`message`	`string`	Yes	—	—
`candidates`	`array of object`	No	`[]`	—

MappingBlocker

Field	Type	Required	Default	Constraints / meaning
`code`	`string`	Yes	—	—
`count`	`integer`	Yes	—	—

RuleCoverage

Field	Type	Required	Default	Constraints / meaning
`conflicted`	`integer`	No	`0`	—
`rule_name`	`string`	Yes	—	—
`matched`	`integer`	Yes	—	—
`ready`	`integer`	Yes	—	—
`held`	`integer`	Yes	—	—
`excluded`	`integer`	Yes	—	—

ActivateInput

Field	Type	Required	Default	Constraints / meaning
`revision`	`integer`	Yes	—	minimum: 1; Current stream revision.
`mapping_revision`	`integer`	Yes	—	minimum: 1
`operation_key`	`string`	Yes	—	min length: 1; max length: 100
`history`	`boolean`	No	`true`	—
`history_start`	`number or null`	No	`null`	—
`history_end`	`number or null`	No	`null`	—

HistoryDraftInput

Field	Type	Required	Default	Constraints / meaning
`revision`	`integer`	Yes	—	minimum: 1; Current stream revision; draft only.
`history`	`boolean`	No	`true`	—
`history_start`	`number or null`	No	`null`	—
`history_end`	`number or null`	No	`null`	—

OperationInput

Field	Type	Required	Default	Constraints / meaning
`revision`	`integer`	Yes	—	minimum: 1
`action`	`"pause" / "resume" / "disable" / "enable" / "cancel_backfill"`	Yes	—	—

ExtendBackfillInput

Field	Type	Required	Default	Constraints / meaning
`revision`	`integer`	Yes	—	minimum: 1
`message_limit`	`integer or null`	Yes	—	maximum: 9007199254740991; greater than: 0; New cumulative historical budget; null selects all matching history.

TrafficFiltersInput

Field	Type	Required	Default	Constraints / meaning
`stream_revision`	`integer`	Yes	—	minimum: 1; Current stream revision.
`revision`	`integer`	Yes	—	minimum: 1; Current lifecycle revision.
`filters`	`array of TrafficFilter`	Yes	—	max items: 10

MappingActivationInput

Field	Type	Required	Default	Constraints / meaning
`revision`	`integer`	Yes	—	minimum: 1
`mapping_revision`	`integer`	Yes	—	minimum: 1

RetryInput

Field	Type	Required	Default	Constraints / meaning
`revision`	`integer`	Yes	—	minimum: 1
`mapping_revision`	`integer`	Yes	—	minimum: 1
`record_ids`	`array of string`	Yes	—	min items: 1; max items: 50; Use inbox IDs returned by the held-records endpoint.
`append_late`	`boolean`	No	`false`	Explicit append-as-late confirmation; does not rewrite consumed learning windows.
`preview_digest`	`string or null`	No	`null`	Required by retry execution; obtain from retry-preview for the exact selection.