HTTP and request contracts

Authenticate, address state, choose a route, and check request and response contracts.

Use the same authenticated HTTP client across Adapt-1 workflows. The task determines the request body and the state it can change.

Base URL and key

API base

https://rei-neuroadapt-api.reilabs.org/api/v1

Required headers

Authorization: Bearer <ADAPT1_API_KEY>
Content-Type: application/json

Set ADAPT1_API_KEY in a server-side environment or secret store. Do not send it to browser clients, include it in prompts, or commit it with examples. The quickstart includes cURL, Python, and server-side JavaScript requests.

Append route suffixes such as /domains or /memory/query to the versioned base. Address system routes such as /version from the host root.

Identity and task scope

Identifier	What it controls
Bearer token	The authenticated owner and effective hosted session identity
domain_id	A task contract and its scoped evidence and learned state
Body session_id	A compatibility placeholder on routes that require it
Episode or interaction ID	An application-defined sequence or interaction boundary

Use "session_id": "ignored" where a request requires the field. The hosted service derives the effective session from the bearer token. Changing the placeholder does not isolate State-gateway records.

Use a fresh domain_id for an independent tutorial run. Keep the same Domain when reconnecting to compatible retained task state. Do not clear an existing Domain as an implicit setup step.

Match the request to the operation

Application operation	Route relative to the API base	Request content
Create a task scope	POST /domains	Domain ID and the task declaration
Submit an observation	POST /domains/{domain_id}/events	Event type and the observed values
Request a current result	POST /domains/{domain_id}/query	Question, applicable context, and requested result fields
Return a measured outcome	POST /domains/{domain_id}/feedback	Outcome and the binding to the executed decision or relevant context
Inspect supporting evidence	POST /domains/{domain_id}/explain	The documented explanation request
Query continuing evidence	POST /memory/query	session_id, user_message, and optional retrieval controls

Use configuration fragments within the complete request shape documented for the route. Keep application-only settings, trace IDs, executor timing, and private evaluation fields in the application record unless the route explicitly accepts them.

Schema coverage

The checked-in OpenAPI snapshot has the coverage gaps listed below. Validate guide-documented fields against the deployment used by your integration.

Surface	Documentation to use
State query, correction, batch storage, and state-summary requests	The corresponding typed schemas and endpoint definitions in the OpenAPI snapshot
Domain learning and Discovery configuration	The relevant Domain guide and its exact configuration example; the snapshot’s Domain-create definition omits learning
Domain query context and learning controls	The relevant workflow guide; the snapshot’s query definition does not enumerate all documented context and learning controls
Decision-bound or context-bound feedback	Feedback guide; the snapshot omits documented fields such as decision_id, relation, policy, and feedback_kind
Numeric trajectory configuration	Machina configuration; trajectory routes are not included in this OpenAPI snapshot

Before deployment, test the selected route with the documented learning settings. If the service rejects a field, preserve the validation error and resolve the contract mismatch before continuing.

Record the source of each client model and which requests have passed deployment tests. Generate models only from confirmed field definitions.

Read controls

For the documented Domain prediction workflow, the read request uses:

Read controls · request fragment

{
  "update_memory_state": false,
  "allow_exploration": false
}

update_memory_state controls the documented read-time state updates; allow_exploration controls exploration. During frozen evaluation, exclude event and feedback writes and verify the applicable learner-state identity or versions when exposed. Configure trajectory workflows with their documented operation controls.

Validate the response

1. Check transport and shape

   Check the HTTP status and decode the JSON response. Validate the fields your application needs before consuming the result.

2. Check the workflow outcome

   For event ingestion, inspect learner eligibility. For a transition prediction, require transition_prediction.status == "predicted" before using predicted values. For feedback, inspect credit_assignment.contextual_learning_applied and the relevant sample count. Treat missing admission diagnostics as unverified learning.

3. Keep the evidence needed to debug

   Preserve sanitized request bodies, response bodies, Domain IDs, admission reasons, and the operation actually executed. Exclude credentials. Treat stored observations and traces as potentially sensitive application data.

Timeouts and retries

Use a finite timeout. A timed-out write may have reached the service, so the examples leave mutation retries to the application’s reconciliation logic. Rely on idempotency only when the route documents that guarantee.

For an ambiguous write, stop the ordered loop, inspect the relevant state, and reconcile the request before submitting it again. See errors and reliability and operations and retries.

First API call

Send a read-only request in your preferred language.

First learned result

Follow a complete observation-to-prediction example.