Neumera API reference
Base URL: https://api.neumera.io. Public routes are versioned under /v1/*.
Credentials are passed via X-API-Key. Route-family admissions are governed by entitlement class and access layer.
Canonical onboarding starts at Start, with authentication details at /start/authentication.
Exposure matrix
| Route family | Exposure | Min entitlement | Min access layer | Description |
|---|---|---|---|---|
admin_control_plane | permanently_private | sandbox | 0 | Governance, key lifecycle, and control-plane read surfaces. |
admin_ops | permanently_private | institutional | 0 | Operational control-plane mutation surfaces. |
artifacts | layer0_public | sandbox | 0 | Generated report and artifact retrieval. |
assays | layer1_public | institutional | 1 | Assay execution surfaces available for institutional witness/evaluation workflows. |
assays_research | planned_layer2 | strategic | 2 | Future research-grade assay status/summary readouts where stable platform methods exist. |
dossiers | layer2_public | strategic | 2 | Core/full dossier generation with artifact-oriented evidence export. |
external_action_execution | layer2_public | strategic | 2 | Approval-gated bounded outbound action approval/rejection/execution surfaces. |
external_action_proposal | layer2_public | strategic | 2 | Bounded outbound action proposal, dry-run, and read ledger surfaces. |
external_event_ingress | layer0_public | institutional | 0 | Inbound-only connector-neutral external event ingress. |
external_reconciliation | layer1_public | institutional | 1 | External event reconciliation witness and continuity inspection. |
intentionality | layer1_public | institutional | 1 | Intentional thread and aboutness witness inspection surfaces. |
membrane_basic | layer0_public | institutional | 0 | Runtime and assay natural-language rendering. |
membrane_witness | layer1_public | institutional | 1 | Membrane renderers for commitment/repair/aboutness/evidence witness payloads. |
membrane_world_render | layer0_public | sandbox | 0 | Build-safe world membrane rendering. |
proofs | layer2_public | strategic | 2 | Bounded proof status/summary/check surfaces for external research labs. |
repair_witness | layer1_public | institutional | 1 | Repair request/state/certificate/repairability witness readouts. |
research_future | planned_layer2 | strategic | 2 | Research/adversarial and substrate-level inspection families. |
restricted_partner_future | planned_layer3 | strategic | 3 | Restricted mechanics-adjacent partner workflows. |
runtime_basic | layer0_public | sandbox | 0 | Build-safe runtime continuity/status and summary surfaces. |
runtime_witness | layer1_public | institutional | 1 | Structured runtime witness reports including continuity, affect, and development readouts. |
scenarios | layer2_public | strategic | 2 | Named scenario discovery and bounded execution for reproducible research runs. |
sessions | layer0_public | sandbox | 0 | Communicative session creation, stepping, and inspection. |
shared_contexts | layer0_public | sandbox | 0 | High-level shared context and workflow summaries. |
shared_contexts_witness | layer1_public | institutional | 1 | Shared commitment/disagreement/evidence/aboutness witness inspection. |
substrate_assay | layer2_public | strategic | 2 | Substrate assay execution surfaces. |
substrate_build | layer2_public | strategic | 2 | Substrate deployment/build and artifact inspection surfaces. |
substrate_observation | layer2_public | strategic | 2 | Substrate observation and render surfaces. |
substrate_recognition | layer2_public | strategic | 2 | Substrate motif recognition surfaces. |
substrate_seeding | layer2_public | strategic | 2 | Substrate seeding validation/compilation surfaces. |
witness_future | planned_layer1 | institutional | 1 | Witness-facing internal continuity and affective surfaces. |
worlds_basic | layer0_public | sandbox | 0 | Build-safe world object/state/history inspection. |
worlds_mutation | layer0_public | institutional | 0 | Bounded world task mutation for operators. |
Implementation-first route examples
Hosted API is the active integration path. Use X-API-Key for authenticated routes.
POST /v1/access/request
Required fields: name, email, intended_use. Optional fields: none on the public surface.
curl -X POST https://api.neumera.io/v1/access/request -H "Content-Type: application/json" -d '{"name":"Example Builder","email":"builder@example.com","intended_use":"Prototype a persistent research workspace"}'{"api_key":"nm_sandbox_xxx","entitlement":"sandbox","access_layer":"layer0_public","limits":{"requests_per_minute":60,"daily_quota":1000}}Common failure: duplicate email returns 409 with a conflict error. Idempotency: not idempotent for the same email.
POST /v1/sessions
Required fields: none. Optional fields: continuity_mode (for example preserve).
curl -sS https://api.neumera.io/v1/sessions -H "X-API-Key: $NEUMERA_API_KEY" -H "Content-Type: application/json" -d '{"continuity_mode":"preserve"}'{"ok":true,"payload":{"session_id":"sess.example","created_at":"2026-04-15T00:00:00Z"}}Common failure: missing/invalid API key returns 401. Idempotency: non-idempotent; each call creates a new session.
POST /v1/sessions/{session_id}/step
Required fields: input_packet.command. Optional fields: input_packet.args.
curl -sS https://api.neumera.io/v1/sessions/sess.example/step -H "X-API-Key: $NEUMERA_API_KEY" -H "Content-Type: application/json" -d '{"input_packet":{"command":"list_objects","args":{}}}'{"ok":true,"payload":{"session_id":"sess.example","continuity":{"identity_stable":true}}}Common failure: unknown session id returns 404. Idempotency: non-idempotent; each step advances state.
GET /v1/runtime/summary
Required fields: none. Optional query: session_id when you want session-focused summary output.
curl -sS "https://api.neumera.io/v1/runtime/summary?session_id=sess.example" -H "X-API-Key: $NEUMERA_API_KEY"{"ok":true,"payload":{"session_id":"sess.example","state":"active","summary":"..."}}Common failure: invalid API key returns 401. Pagination: not paginated on current public surface.
GET /v1/worlds/state
Required fields: none. Optional query parameters depend on access layer and current schema.
curl -sS https://api.neumera.io/v1/worlds/state -H "X-API-Key: $NEUMERA_API_KEY"{"ok":true,"payload":{"world_state":{"objects":[],"history_head":"evt_001"}}}Common failure: entitlement boundary can return 403 on restricted world surfaces. Pagination: use endpoint-specific paging fields where present in schema.
Health endpoints
Unauthenticated liveness/readiness checks.
| Method | Path | Description |
|---|---|---|
GET | /healthz | Public API endpoint |
GET | /readyz | Public API endpoint |
Access endpoints
Public sandbox key issuance and onboarding routes.
| Method | Path | Description |
|---|---|---|
POST | /v1/access/request | Request sandbox access |
Runtime endpoints
Continuity and runtime witness surfaces.
| Method | Path | Description |
|---|---|---|
GET | /v1/runtime/affect | Get affective witness readout |
GET | /v1/runtime/continuity | Get runtime continuity witness report |
GET | /v1/runtime/development | Get developmental witness summary |
GET | /v1/runtime/integrated-self-world | Get integrated self-world witness report |
GET | /v1/runtime/self-report | Get runtime structured self report |
GET | /v1/runtime/status | Get runtime continuity and status |
GET | /v1/runtime/summary | Get build-safe runtime summary |
Intentionality endpoints
Intentional thread and aboutness witness surfaces.
| Method | Path | Description |
|---|---|---|
GET | /v1/aboutness | Inspect aboutness for a handle |
GET | /v1/intentionality/threads | List intentional threads |
GET | /v1/intentionality/threads/{thread_id} | Inspect intentional thread |
Platform endpoints
Top-level platform summaries for builders.
| Method | Path | Description |
|---|---|---|
GET | /v1/platform/summary | Get build-safe platform summary |
Session endpoints
Communicative/session lifecycle routes.
| Method | Path | Description |
|---|---|---|
POST | /v1/sessions | Create communicative session |
GET | /v1/sessions/{session_id} | Inspect communicative session |
POST | /v1/sessions/{session_id}/step | Step communicative session |
World endpoints
World/task/object and world-state surfaces.
| Method | Path | Description |
|---|---|---|
GET | /v1/worlds/external-state | Inspect reconciled external state by world object |
GET | /v1/worlds/history | Get world history summary |
GET | /v1/worlds/objects | List world objects |
GET | /v1/worlds/objects/{object_id} | Inspect world object |
GET | /v1/worlds/objects/{object_id}/relationships | Inspect world object relationships |
GET | /v1/worlds/state | Observe world state |
POST | /v1/worlds/tasks | Create a world task |
PATCH | /v1/worlds/tasks/{task_id} | Update world task state |
Shared-context endpoints
Shared workflow and commitment context reads.
| Method | Path | Description |
|---|---|---|
GET | /v1/shared-contexts/{context_id} | Inspect shared context |
GET | /v1/shared-contexts/{context_id}/aboutness | Inspect shared aboutness witness |
GET | /v1/shared-contexts/{context_id}/commitments | Inspect shared commitments witness |
GET | /v1/shared-contexts/{context_id}/disagreement | Inspect shared disagreement witness |
GET | /v1/shared-contexts/{context_id}/evidence | Inspect shared evidence witness |
GET | /v1/shared-contexts/{context_id}/external-reconciliation | Inspect shared-context external reconciliations |
GET | /v1/shared-contexts/{context_id}/workflow-summary | Get shared workflow summary |
Repair endpoints
Repair request/state/certificate and repairability witness routes.
| Method | Path | Description |
|---|---|---|
GET | /v1/repair/certificate | Get repair certificate witness |
POST | /v1/repair/request | Request bounded repair on an object |
GET | /v1/repair/state | Get latest repair witness state |
GET | /v1/repairability/{object_id} | Inspect repairability for object |
External-event endpoints
Inbound external event ingress and reconciliation surfaces.
| Method | Path | Description |
|---|---|---|
GET | /v1/external-events/history | Inspect external event ingress history |
POST | /v1/external-events/ingest | Ingest connector-neutral external event |
POST | /v1/external-events/ingest-batch | Ingest a batch of connector-neutral external events |
GET | /v1/external-events/reconciliation/{event_id} | Inspect external event reconciliation output |
GET | /v1/external-events/{event_id} | Inspect external event envelope |
External-action endpoints
Bounded outbound action contract lifecycle.
| Method | Path | Description |
|---|---|---|
POST | /v1/external-actions/dry-run | Dry-run bounded outbound action contract |
GET | /v1/external-actions/history | List bounded outbound action ledger history |
POST | /v1/external-actions/propose | Propose bounded outbound action contract |
GET | /v1/external-actions/{action_id} | Inspect bounded outbound action |
POST | /v1/external-actions/{action_id}/approve | Approve bounded outbound action |
POST | /v1/external-actions/{action_id}/execute | Execute bounded outbound action |
POST | /v1/external-actions/{action_id}/reject | Reject bounded outbound action |
Substrate endpoints
Validate/compile/deploy/observe/assay/recognize/render plus registry inspection.
| Method | Path | Description |
|---|---|---|
GET | /v1/substrates/artifacts/{artifact_id} | Inspect substrate build/deployment artifact |
POST | /v1/substrates/assay | Run assay pack against deployed substrate environment |
GET | /v1/substrates/certification-packs | List official certification starter packs |
GET | /v1/substrates/certification-packs/{pack_id} | Inspect official certification starter pack |
POST | /v1/substrates/compile | Compile seeded substrate environment spec |
POST | /v1/substrates/deploy | Deploy/bind seeded substrate environment |
GET | /v1/substrates/deployments | List substrate deployment records |
GET | /v1/substrates/deployments/{deployment_id} | Inspect substrate deployment record |
GET | /v1/substrates/envelopes | List official constitutional envelopes |
GET | /v1/substrates/envelopes/{envelope_id} | Inspect official constitutional envelope |
POST | /v1/substrates/observe | Observe deployed substrate environment state |
POST | /v1/substrates/recognize | Inspect motif recognition outputs for deployed substrate environments |
GET | /v1/substrates/recognizers | List official motif recognizer packs |
GET | /v1/substrates/recognizers/{recognizer_id} | Inspect official motif recognizer pack |
POST | /v1/substrates/render | Render substrate/world manifests and summaries |
GET | /v1/substrates/scaffolds | List official scaffold packages |
GET | /v1/substrates/scaffolds/{scaffold_id} | Inspect official scaffold package |
POST | /v1/substrates/validate | Validate seeded substrate environment spec |
Assay endpoints
Social/cultural assay execution surfaces.
| Method | Path | Description |
|---|---|---|
POST | /v1/assays/social/run | Run social/cultural assay |
Proof endpoints
Bounded proof status/summary/check routes.
| Method | Path | Description |
|---|---|---|
POST | /v1/proofs/checks | Run bounded proof checks |
GET | /v1/proofs/status | Get bounded proof certification status |
GET | /v1/proofs/summary | Get proof-layer summary |
Scenario endpoints
Scenario listing and execution.
| Method | Path | Description |
|---|---|---|
GET | /v1/scenarios | List named research scenarios |
POST | /v1/scenarios/run | Run a named research scenario |
Dossier endpoints
Core/full evidence exports.
| Method | Path | Description |
|---|---|---|
POST | /v1/dossiers/core | Build core dossier |
POST | /v1/dossiers/full | Build full dossier |
Membrane endpoints
Canonical protocol normalization and renderers.
| Method | Path | Description |
|---|---|---|
POST | /v1/membrane/render/aboutness | Render aboutness witness payload |
POST | /v1/membrane/render/assay | Render assay payload through membrane |
POST | /v1/membrane/render/commitment | Render commitment witness payload |
POST | /v1/membrane/render/evidence | Render evidence witness payload |
POST | /v1/membrane/render/repair | Render repair witness payload |
POST | /v1/membrane/render/runtime | Render runtime state through membrane |
POST | /v1/membrane/render/world | Render world state through membrane |
Continuous-ops endpoints
Checkpoint and long-run runtime operations.
| Method | Path | Description |
|---|---|---|
POST | /v1/continuous-ops/checkpoint | Create runtime checkpoint |
Artifact retrieval endpoints
Machine-readable and rendered artifact access.
| Method | Path | Description |
|---|---|---|
GET | /v1/artifacts/{artifact_path:path} | Fetch generated artifact/report |
GET | /v1/artifacts/{artifact_path:path}/raw | Fetch full artifact bytes/text |
Admin key management endpoints
API key lifecycle, rotation, usage and governance controls.
| Method | Path | Description |
|---|---|---|
GET | /v1/admin/access-layers | Get access-layer governance summary (admin) |
GET | /v1/admin/audit | Get control-plane audit rows (admin) |
GET | /v1/admin/entitlements | Get entitlement classes and usage posture (admin) |
GET | /v1/admin/keys | List keys by tenant or organization (admin) |
POST | /v1/admin/keys/create | Create API key (admin) |
POST | /v1/admin/keys/rotate | Rotate API key (admin) |
POST | /v1/admin/keys/status | Set API key status (admin) |
GET | /v1/admin/organizations | List organizations (admin) |
POST | /v1/admin/organizations/create | Create organization (admin) |
POST | /v1/admin/organizations/status | Set organization status (admin) |
GET | /v1/admin/overview | Get operational overview summary (admin) |
GET | /v1/admin/policies | List quota policies (admin) |
POST | /v1/admin/policies/create | Create quota policy (admin) |
POST | /v1/admin/policies/status | Set policy status (admin) |
GET | /v1/admin/principals | List principals (admin) |
POST | /v1/admin/principals/create | Create principal (admin) |
POST | /v1/admin/principals/status | Set principal status (admin) |
GET | /v1/admin/projects | List projects (admin) |
POST | /v1/admin/projects/create | Create project (admin) |
POST | /v1/admin/projects/status | Set project status (admin) |
POST | /v1/admin/prune-ledgers | Prune old service-side ledger rows (admin) |
GET | /v1/admin/requests | List durable request ledger rows (admin) |
GET | /v1/admin/service-events | List service event ledger rows (admin) |
GET | /v1/admin/service-health | Get service/runtime backend health state (admin) |
GET | /v1/admin/usage | Get aggregated durable usage rollups (admin) |
GET | /v1/admin/usage/{key_id} | Get key usage stats (admin) |