Skip to main content
Record the accepted order of stateful calls and checkpoint each confirmed response. A timed-out write may already have changed the state used by the next call. Use stable identifiers on event and feedback writes when the request schema accepts metadata:
run_id labels the workflow for correlation. Use trial_id for an outcome unit and event_id for a logical write. Ownership and Domain identity determine the state scope; include relation and policy fields when the feedback contract requires 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. Apply the operation-specific retry rule below before resending a request, then use exponential backoff with jitter and a bounded retry count. Example client backoff schedule: 0.5s → 1s → 2s → 4s → 8s maximum. Honor Retry-After when returned. The cap applies to each wait; choose an overall retry deadline for the workflow. Do not automatically retry 400, 401, 403, 404, or 422; correct the request first. Inspect a 409 response before retrying: it can report conflicting observation content, a rejected promotion, or an occupied value-training slot. Use the response reason and the operation-specific rule below.

Retry rules by operation

Preserve request identifiers and inspect returned state before retrying an uncertain write. Use the operation-specific rules below to reconcile the outcome and resume the workflow.
The value API reference describes observation identities and model guards. Follow the value-learning lifecycle when checking whether a fit produced a candidate or changed the installed model.

Domain query timeouts

Large Domain queries can exceed the gateway time limit. Record a timed-out /query as an unconfirmed selection and leave the policy and decision_id unset until a response establishes them. Policy feedback can enter learning through a valid target_memory_id or explicit structured context. Record which binding admitted the feedback. Sealed query attribution requires the decision_id returned by the selection call. 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.

Reconcile feedback and partial batches

For an uncertain feedback write, compare feedback_policy.sample_count before and after the request, together with the returned admission diagnostics and your application log. The count tracks retained eligible samples and can be bounded by retention. Concurrent writers can also change it. Identify the accepted logical feedback event through the admission diagnostics and application log alongside the count change. Send 1 to 50 operations per Domain /batch request. Larger requests have been rejected with HTTP 422. A Domain batch that stops at a failed operation can return HTTP 207 with status: partial_failure. Inspect the body before treating a successful HTTP status class as a completed batch. The reported responses had completed_count == failed_index:
  • operations before failed_index were stored;
  • operations after failed_index were not run;
  • if the operation at failed_index timed out, its write status is uncertain.
An operation can report store feedback event: engine_execution_overrun with error_type: timeout inside this 207 response. Apply the same reconciliation rule to that operation before resuming. Keep each operation’s index, ref, and response in the client log. Reconcile the uncertain operation before resuming from the unprocessed portion. Replaying the entire batch can repeat accepted feedback.

Control upload concurrency

Keep ordered state-changing calls serial within a shared Domain/session. Bound concurrency across independent upload streams and reduce it when the service returns engine_execution_overrun. Set concurrency for each workload from service responses and the ordering requirements of the workflow. Increase independent streams gradually while tracking successful admissions and latency. When overruns occur late in a Domain batch, reduce the number of operations per request as well as the number of concurrent streams. Tune batch size using the service responses for that workload, within the public maximum of 50 operations. Native planning has its own budgets, exploration settings, and cache options. See Native planning options when configuring those requests.

Read-only state inspection

Use the selected endpoint’s documented state-change contract when configuring inspection. 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. allow_exploration controls exploration; update_memory_state controls the documented read-time 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.
Record event_count separately from subsystem sample_count when these fields are returned. Stored event totals and retained eligible learner samples measure different state. Policy retention is bounded by learning.context.max_samples. Confirm policy-learning admission through the returned eligibility diagnostics and learner state.If a learner count falls unexpectedly, compare authenticated identity, Domain revision, configuration, retention limits, learner versions, and recorded resets with the last acknowledged writes. Preserve the responses before attempting recovery.For a controlled rebuild, replay approved application records into a fresh diagnostic Domain through the appropriate event and feedback routes. Preserve decision-time context, executed relation and policy, measured outcomes, and episode order. Complete the rebuild by verifying learner admission, fitting, and the resulting policy state before moving traffic.

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. After recreation, obtain fresh decisions before submitting decision-bound feedback. Check that each decision belongs to the current Domain and authenticated identity.

API paths and production identity

The canonical versioned prefix is /api/v1. 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 serves as a request-compatibility placeholder. Use session_identity.effective_session_id as authoritative when returned. 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 to establish whether a stored event entered learning.
  • 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.