Base URL and key
API base
Required headers
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.
When using this versioned base, append /domains or /memory/query, not another /api/v1. System routes such as /version live at the host root rather than under the versioned base.
Identity and task scope
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
A configuration fragment in a guide is not a complete request unless labeled as one. Keep application-only settings, trace IDs, executor timing, and private evaluation fields outside the API body unless the selected route explicitly accepts them.
Schema coverage
The checked-in OpenAPI snapshot does not yet describe every learning workflow in these guides. Do not treat a successful validation against a permissive object schema as proof that a learning configuration is supported.
The gaps above describe the checked-in documentation snapshot, not a test of a deployed service. A guide documents an intended contract; it does not replace deployment verification. Before deploying an integration, confirm the selected route against the schema for that deployment and run a dedicated integration test. If the deployment rejects a documented field, keep the validation error and resolve the mismatch rather than silently removing a required learning setting.
When generating a client, distinguish schema-validated fields, guide-documented fields, and live-tested behavior. Do not invent missing request or response models to make client generation pass.
Reading and learning are separate controls
For the documented Domain prediction workflow, the read request uses:Read controls · request fragment
update_memory_state and allow_exploration serve different purposes. Turning exploration off is not a general freeze switch. A retained-use or frozen-evaluation interval also excludes event and feedback writes and checks the applicable learner-state identity or versions when exposed. Trajectory workflows have their own operation semantics; do not copy Domain-query flags into trajectory requests.
Handle the result at two levels
1
Check transport and shape
Check the HTTP status, decode JSON, and validate the fields needed by your application. A
200 response alone does not establish that a learner consumed an observation.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. Missing diagnostics are not success.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 been applied even when the client received no response. The examples therefore do not automatically retry mutations. Do not assume that an event ID or interaction ID provides idempotency unless 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.