Request Management

mark_session_outcome

Record an optional external success, failure, or unknown outcome for a session. Use unknown when the domain cannot determine a terminal result; it is an explicit outcome rather than an omitted outcome. Publish at least one request first. Reflexio derives user_id and source from the earliest request ordered by (created_at, request_id); neither is accepted from the caller. source is a non-sensitive producer/workflow label, not a person or free-form description. A non-empty value must match ^[a-z0-9][a-z0-9._:-]{0,127}$ and must not contain user identifiers or PII.

The first finalization wins for the lifetime of the session ID. New canonical rows bind it to an immutable outcome ID and revision, a digest of the server-owned outcome contract, and a digest of the canonical session trajectory at finalization. An exact retry of a canonical row must match the complete caller payload and the current contract and trajectory identities. It returns success=True, recorded=False, and the same outcome_id, outcome_revision, outcome_contract_digest, and finalized_trajectory_digest. Any changed outcome, timestamp, label, value, metadata, contract, or finalized trajectory is rejected with success=False and reason="conflicting_finalization"; the original record is unchanged. The trajectory digest always covers the complete canonical trajectory. Outcome finalization does not truncate or reject a trajectory under the offline tuner's separate 64_000 byte and 8_000 cl100k_base token evidence limits.

During a rolling upgrade, a legacy row may have all four identity fields set to null. An exact retry 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 conflicts; the retry does not fabricate or backfill immutable identity.

response = client.mark_session_outcome(
    session_id="support_ticket_789",
    outcome="success",
    occurred_at=1785196800,
    label="issue_resolved",
    value=5.0,
    metadata={"survey": "post-chat"},
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/session_outcome" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"session_id":"support_ticket_789","outcome":"success","occurred_at":1785196800,"label":"issue_resolved"}'

Sessions may remain unmarked. Outcomes are stored as caller-authored domain facts; they do not update profiles or playbooks. The identity digests are opaque integrity values and are not configuration inputs.

get_session_outcomes

Read outcomes with optional exact filters. value and metadata are returned but are intentionally not filterable. The optional source filter uses the same non-sensitive producer/workflow label contract.

response = client.get_session_outcomes(
    user_id="user_123",
    source="support-agent",
    outcome="success",
    label="issue_resolved",
    start_time=1785110400,
    end_time=1785196800,
    top_k=100,
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_session_outcomes" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"source":"support-agent","outcome":"success","top_k":100}'

See Request Models for request, response, bounds, and pagination fields.

get_requests

Get requests with their associated interactions, grouped by session.

response = client.get_requests(
    user_id="user_123",
    top_k=50
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_requests" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "top_k": 50
}
JSON

delete_request

Delete a request and all its associated interactions.

response = client.delete_request(
    request_id,
    wait_for_response=False
)

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_request" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "request_id": "<request_id>"
}
JSON

delete_session

Delete all requests and interactions in a session.

An external session outcome is intentionally preserved. This keeps first-write-wins durable if a transcript is later removed. Governance erasure is the explicit exception and removes subject-owned markers.

response = client.delete_session(
    session_id,
    wait_for_response=False
)

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_session" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "session_id": "<session_id>"
}
JSON

Bulk Delete Operations

delete_requests_by_ids

Delete multiple requests by their IDs.

response = client.delete_requests_by_ids(request_ids=["req_1", "req_2"])

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_requests_by_ids" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "request_ids": [
    "req_1",
    "req_2"
  ]
}
JSON

Returns: BulkDeleteResponse with success, deleted_count, and message

delete_all_interactions

Delete all requests and their associated interactions.

response = client.delete_all_interactions()

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_all_interactions" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Returns: BulkDeleteResponse with success, deleted_count, and message