Skip to main content
Stateful integrations need explicit isolation, ordering, stable identifiers, and careful retry behavior. Use stable identifiers on event and feedback writes when the request schema accepts metadata:
run_id isolates a workflow, trial_id identifies one outcome unit, and event_id identifies one logical write. Relation and policy fields keep feedback scoped when that workflow uses them.

​
Online-policy ordering

For Adaptive Policies:
Concurrent workers against the same domain/session can interleave observations and change the result. Do not reset state between interactions that share learning. Reset policy state only for a new state history or a rebuild from a known record. Record each reset in the application log.

​
Retryable failures

Handle 429, 502, 503, and 504 as transient. Use exponential backoff with jitter and a bounded retry count.
Do not automatically retry 400, 401, 403, 404, or 422; correct the request first.

​
Domain query timeouts

Large Domain queries can exceed the gateway time limit. Treat a timed-out /query call as a failed selection. Do not fabricate a selected policy or decision_id. Policy feedback can still enter learning when it supplies a valid target_memory_id or explicit structured context. These bindings preserve feedback admission. They do not perform Domain policy selection, exploration, or sealed decision attribution. Continue to monitor /query availability separately from feedback-policy sample admission. Use bounded retries for a timed-out query. Keep the request context and selection settings unchanged so a later response remains comparable. For read-only evaluation, also keep allow_exploration: false and update_memory_state: false.

​
Ambiguous writes

A gateway failure can occur after an upstream write was accepted. Until a route explicitly documents idempotency, treat failed event and feedback writes as ambiguous:
  1. Send stable run_id and event/trial identifiers.
  2. Check the available state or audit response before resubmitting when a duplicate would affect the result.
  3. Checkpoint the last confirmed identifier.
  4. Resume from the last confirmed write.
POST /api/v1/domains/{domain_id}/adapt/predict reads current adaptive state without adding an observation and can be repeated safely according to its documented contract.

​
Read-only state inspection

A route name does not specify if the route changes state. Use the documented state-change contract for the selected endpoint. If the route supports allow_exploration and update_memory_state, set both fields to false. Record the learner-state hash and applicable versions before the calls. Compare the values after the calls. The values must not change. The two fields control different functions. allow_exploration: false does not prevent state updates. Store the complete response and the required query context. If a query changes a learner version, stop the inspection. Identify the endpoint or process that changed the version.

​
Reset and clear

Choose the route that owns the intended state boundary. For a completely cold Domain evaluation, delete and recreate the Domain; also clear memory if the same identity holds unrelated test memories.

​
API paths and production identity

The canonical versioned prefix is /api/v1. Two compatibility prefixes are also available:
  • /public/rei-ai-bowtie/v4
  • /rei-ai-bowtie/v4
Use canonical /api/v1 routes for new integrations. The production app maps the bearer token to the effective Neuroadapt identity. A body session_id is useful for request compatibility and client-side correlation, but it cannot access another API key’s state. When returned, treat session_identity.effective_session_id as authoritative. Domain definitions, evidence, decisions, policy state, transition state, structural state, and adaptive state are owner-scoped. Use a separate API key or agent identity when state must be independently isolated.

​
Production integration checklist

  • Keep API keys server-side and use canonical /api/v1 routes.
  • Persist memory IDs and sealed Domain decision IDs when later correction, deletion, feedback, or historical explanation is required.
  • Set update_memory_state: false for read-only evaluation and replay.
  • Check learner eligibility and abstention fields instead of assuming every stored event trained a learner.
  • Use the dedicated adaptive routes for adaptive output and validate Vision grounding before acting on a point.
  • Record every reset boundary and choose its scope deliberately.