Schemas

Request Models

Data structures for requests and sessions — retrieving and deleting requests.

Request

Represents a container for one or more interactions in a session.

Prop	Type	Default	Description
`request_id`	`string`	`—`	Unique identifier for the request
`user_id`	`string`	`—`	Identifier of the user
`created_at?`	`integer`	`—`	Unix timestamp when request was created. Defaults to the current UTC time.
`source?`	`string`	`""`	Non-sensitive producer/workflow label. A non-empty value must match `^[a-z0-9][a-z0-9._:-]{0,127}$` and must not contain user identifiers or PII. Evaluation source-set comparison groups sessions by the first request source.
`agent_version?`	`string`	`""`	Version of the agent that generated this request
`session_id`	`string`	`—`	Session identifier for related requests.
`evaluation_only?`	`boolean`	`false`	Whether this request is stored for session-level evaluation while being excluded from profile/playbook learning windows. Retrieval-experiment holdouts leave this false so both arms learn normally.
`retrieval_experiment_id?`	`string`	`—`	Retrieval experiment attributed to this published request. Must be provided together with retrieval_experiment_arm, or both fields must be omitted.
`retrieval_experiment_arm?`	`"treatment" \| "holdout"`	`—`	Deterministic user arm attributed to this published request. Must be provided together with retrieval_experiment_id, or both fields must be omitted.

RequestData

Contains a request with its associated interactions.

Prop	Type	Default	Description
`request`	Request	`—`	The request object
`interactions`	array[Interaction]	`—`	List of interactions in this request

Session

Groups multiple requests by session identifier.

Prop	Type	Default	Description
`session_id`	`string`	`—`	The session identifier
`requests`	array[RequestData]	`—`	List of requests in this session

GetRequestsRequest

Request model for getting requests grouped by session.

Prop	Type	Default	Description
`user_id?`	`string`	`—`	Filter by user ID
`request_id?`	`string`	`—`	Filter by specific request ID
`session_id?`	`string`	`—`	Filter by session ID
`source?`	`string`	`—`	Filter by request source
`start_time?`	`datetime`	`—`	Filter by start time
`end_time?`	`datetime`	`—`	Filter by end time
`top_k?`	`integer`	`30`	Maximum number of results to return
`offset?`	`integer`	`0`	Number of results to skip (for pagination)

GetRequestsResponse

Response model for getting requests.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the request was successful
`sessions`	array[Session]	`—`	List of sessions with their requests
`has_more?`	`boolean`	`false`	Whether there are more results available (for pagination)
`msg?`	`string`	`—`	Additional message

DeleteRequestRequest

Request model for deleting a request and all its associated interactions.

Prop	Type	Default	Description
`request_id`	`string`	`—`	Identifier of the request to delete

DeleteRequestResponse

Response model for request deletion requests.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the deletion was successful
`message?`	`string`	`""`	Additional information about the operation

DeleteSessionRequest

Request model for deleting all requests in a session.

Prop	Type	Default	Description
`session_id`	`string`	`—`	Session identifier

DeleteSessionResponse

Response model for session deletion requests.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the deletion was successful
`message?`	`string`	`""`	Additional information about the operation
`deleted_requests_count?`	`integer`	`0`	Number of requests deleted

Records an optional external success, failure, or unknown outcome for an existing session. The server derives user_id and source from the earliest request ordered by (created_at, request_id); callers cannot override either field.

Prop	Type	Default	Description
`session_id`	`string`	`—`	Existing session identifier
`outcome`	`"success" \| "failure" \| "unknown"`	`—`	Caller-authored domain outcome; unknown means the result cannot be determined
`occurred_at`	`integer`	`—`	Unix epoch seconds when the outcome occurred
`label?`	`string`	`—`	Optional non-empty label, at most 128 characters
`value?`	`number`	`—`	Optional finite numeric value
`metadata?`	`object`	`—`	Optional JSON object whose canonical encoding is at most 16 KiB

SetSessionOutcomeResponse

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the request was accepted
`recorded?`	`boolean`	`false`	True when this call stored the outcome: either the session's first finalization, or your report replacing an outcome Reflexio inferred. False for an exact retry
`reason?`	SessionOutcomeFailureReason	`—`	Machine-readable rejection reason when success is false
`message?`	`string`	`""`	Human-readable result
`user_id?`	`string`	`—`	User derived from the session when available
`source?`	`string`	`—`	Non-sensitive producer/workflow label derived from the session when available; it must not contain user identifiers or PII
`outcome_id?`	`string \| null`	`—`	Server-assigned identity for this outcome, when available. Not a stable key for the session: a report that replaces an inferred outcome receives a new id, while a refresh of an inferred outcome keeps it
`outcome_revision?`	`integer \| null`	`—`	Outcome revision; a first outcome is revision 1, and a report that replaces an inferred outcome is revision 2
`outcome_contract_digest?`	`string \| null`	`—`	Lowercase SHA-256 digest of the server-owned outcome contract
`finalized_trajectory_digest?`	`string \| null`	`—`	Lowercase SHA-256 digest of the canonical trajectory at finalization

For a canonical row, an exact retry must match the caller payload, outcome contract, and canonical trajectory. It returns the same identity fields with success=true and recorded=false. A mismatch returns success=false, recorded=false, and reason="conflicting_finalization"; it does not replace the outcome you reported.

Outcomes Reflexio inferred

Where a session has no reported outcome, Reflexio may record one it inferred from its own evaluation of the session, so that playbook tuning has something to learn from. An inferred outcome never overwrites yours, and never takes the place of a report you have already made.

Your report always wins. If you report an outcome for a session Reflexio has already inferred one for, your report replaces it: the call returns success=true, recorded=true, and an outcome_revision of 2. The inferred outcome is retained alongside it for later analysis, and is not returned by the API.

This is the only case in which a stored outcome is replaced. An outcome you reported yourself stays immutable, and a second differing report still returns conflicting_finalization.

A rolling-upgrade row whose four identity fields are all null still compares the caller payload and any available server-derived session context, but it cannot compare the absent contract or trajectory digests. An accepted retry preserves all four identity fields as null. A changed payload or available session context returns conflicting_finalization.

SessionOutcomeRecord

Prop	Type	Default	Description
`outcome_id?`	`string \| null`	`—`	Server-assigned identity for this outcome. Not a stable key for the session: a report that replaces an inferred outcome receives a new id, while a refresh of an inferred outcome keeps it
`outcome_revision?`	`integer \| null`	`—`	Outcome revision; 2 where your report replaced an inferred outcome
`user_id`	`string`	`—`	Derived session owner
`session_id`	`string`	`—`	Session identifier
`outcome`	`"success" \| "failure" \| "unknown"`	`—`	Stored outcome
`occurred_at`	`integer`	`—`	Caller event time in Unix epoch seconds
`source`	`string`	`—`	Non-sensitive producer/workflow label derived from the first request; it must not contain user identifiers or PII
`label?`	`string`	`—`	Optional caller label
`value?`	`number`	`—`	Optional finite caller value
`metadata?`	`object`	`—`	Optional caller metadata
`outcome_contract_digest?`	`string \| null`	`—`	Lowercase SHA-256 digest of the server-owned outcome contract
`finalized_trajectory_digest?`	`string \| null`	`—`	Lowercase SHA-256 digest of the canonical trajectory at finalization
`created_at`	`integer`	`—`	Server receipt time in Unix epoch seconds
`is_inferred?`	`boolean`	`false`	True when Reflexio inferred this outcome instead of you reporting it. An inferred outcome is a placeholder, not a substitute: reporting your own outcome for the session replaces it
`trajectory_through_request_id?`	`string \| null`	`null`	Read-only. For an inferred outcome judged on part of a session, the last request it covers: `finalized_trajectory_digest` is then the digest of the session's requests up to and including this one, plus their interactions. Null means the whole session, which is always the case for an outcome you report

For canonical records, the four identity fields are populated together. Legacy rolling-upgrade records may return all four as null and preserve those nulls on retry; a partial identity is invalid.

GetSessionOutcomesRequest

All supplied filters combine with AND. Results use exact, case-sensitive matches and are ordered by occurred_at DESC, then user_id and session_id ascending.

Prop	Type	Default	Description
`session_ids?`	`array[string]`	`—`	Up to 100 session IDs; duplicates are removed
`user_id?`	`string`	`—`	Exact user filter
`source?`	`string`	`—`	Exact non-sensitive producer/workflow label filter; a non-empty value must match `^[a-z0-9][a-z0-9._:-]{0,127}$`
`outcome?`	`"success" \| "failure" \| "unknown"`	`—`	Exact outcome filter
`label?`	`string`	`—`	Exact label filter
`start_time?`	`integer`	`—`	Inclusive minimum occurred_at
`end_time?`	`integer`	`—`	Inclusive maximum occurred_at
`top_k?`	`integer`	`100`	Maximum records, from 1 to 1000
`offset?`	`integer`	`0`	Records to skip

GetSessionOutcomesResponse

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the read succeeded
`session_outcomes?`	array[SessionOutcomeRecord]	`[]`	Matching outcomes
`message?`	`string`	`""`	Additional information

Client Methods

Interaction Models

Configuration Guide

Searching Learned Context