Noema documentation

HTTP API

Authentication, roles, the error envelope, streaming and every route.

Every function of the interface is available over a JSON HTTP API under /api/v1. The machine-readable description is served by the daemon at /api/v1/openapi.json and a copy is published alongside this documentation as openapi.json. A test in the codebase fails if a route is added without being documented.

Authentication

Two credentials are accepted. Bearer API tokens (Authorization: Bearer noema_...) are created per user from the account page, stored hashed, optionally expiring, and revocable. Browser sessions are cookies set by the login form; a session may call the API too, but unsafe methods then require the X-CSRF-Token header carrying the session's token. Anonymous requests get 401.

Roles

Users have one of three roles. Observer can read everything. Operator can additionally act: post messages and observations, create goals and predictions, approve requests, run background jobs, take snapshots, start replays and experiments. Administrator can additionally configure: minds' lifecycle, policies, providers, integrations, users, forks and imports. Every operation in the reference below lists its minimum role; a call below it gets 403.

Conventions

Mind-scoped paths accept a slug or an id in {mind}.
Lists return {"items": [...]} and often a next cursor; cursors are sequence numbers or ids, never offsets.
Errors use one envelope: {"error": {"code": "...", "message": "...", "request_id": "..."}} with 400 for validation, 401/403 for authentication and roles, 404 for missing or out-of-scope resources (a resource belonging to another mind is a 404, not a 403), 409 for conflicts and replays, 429 for rate limits.
Bodies are JSON; unknown fields are rejected on inputs that create or import things.
Long-running operations (replay, experiment run) return 202 immediately and are polled.
Timestamps are RFC 3339; ids are UUIDv7 and sort by time.

Streaming

GET /api/v1/events/stream and GET /api/v1/minds/{mind}/events/stream are server-sent event streams. They accept the same filters as the event list, honour Last-Event-ID to replay missed events from the sequence, send heartbeats, and use per-client bounded buffers so a slow client cannot back-pressure the daemon.

Webhooks

POST /api/v1/webhooks/{id} is the one unauthenticated route. It requires the X-Noema-Timestamp and X-Noema-Signature headers described under integrations and refuses everything else.

Added in 0.2

GET /api/v1/minds/{mind}/assertions and /assertions/actors list what was said to a mind and by whom, apart from what it believes. GET /api/v1/events/{id}/chain returns the bounded causal chain around an event. POST /api/v1/minds/{mind}/redactions (administrators) performs an audited redaction and GET lists the ledger. Experiments accept variants, and snapshot, replay and experiment responses carry the runtime identity and, for replays, the compatibility label and divergence analysis.

Route reference

The table below is generated from the OpenAPI document.

abandon

Method	Path	Minimum role	Operation
`POST`	`/api/v1/minds/{mind}/intentions/{id}/abandon`	operator	intention abandon

agency

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/agency/timeline`	observer	agency timeline
`GET`	`/api/v1/minds/{mind}/research/agency`	observer	research agency

approvals

Method	Path	Minimum role	Operation
`GET`	`/api/v1/approvals`	observer	approvals list
`GET`	`/api/v1/approvals/{id}`	observer	approval get
`POST`	`/api/v1/approvals/{id}/approve`	operator	approval approve
`POST`	`/api/v1/approvals/{id}/deny`	operator	approval deny

attribution

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/events/{id}/attribution`	observer	attribution

audit

Method	Path	Minimum role	Operation
`GET`	`/api/v1/audit`	operator	audit list

calibration

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/research/calibration`	observer	research calibration

cancel

Method	Path	Minimum role	Operation
`POST`	`/api/v1/minds/{mind}/plans/{id}/cancel`	operator	plan cancel

capabilities

Method	Path	Minimum role	Operation
`GET`	`/api/v1/capabilities`	observer	capabilities list

capability-requests

Method	Path	Minimum role	Operation
`GET`	`/api/v1/capability-requests`	observer	capability requests list
`GET`	`/api/v1/capability-requests/{id}`	observer	capability request get
`POST`	`/api/v1/capability-requests/{id}/deny`	operator	capability request deny
`POST`	`/api/v1/capability-requests/{id}/grant`	operator	capability request grant

close

Method	Path	Minimum role	Operation
`POST`	`/api/v1/minds/{mind}/commitments/{id}/close`	operator	commitment close

commitments

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/commitments`	observer	commitments list
`POST`	`/api/v1/minds/{mind}/commitments`	operator	commitment create

consolidation

Method	Path	Minimum role	Operation
`POST`	`/api/v1/consolidation/pause`	administrator	consolidation pause

decisions

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/decisions`	observer	decisions list

dreams

Method	Path	Minimum role	Operation
`POST`	`/api/v1/dreams/pause`	administrator	dream pause

events

Method	Path	Minimum role	Operation
`GET`	`/api/v1/events/stream`	observer	events stream
`GET`	`/api/v1/events/types`	none	list event types
`GET`	`/api/v1/events/{id}`	observer	event get
`GET`	`/api/v1/events/{id}/chain`	observer	bounded causal chain around an event (recorded links only)
`GET`	`/api/v1/events/{id}/context`	observer	event context

executions

Method	Path	Minimum role	Operation
`GET`	`/api/v1/executions`	observer	executions list

experiments

Method	Path	Minimum role	Operation
`GET`	`/api/v1/experiments`	observer	experiments list
`POST`	`/api/v1/experiments`	operator	experiment create
`DELETE`	`/api/v1/experiments/{id}`	administrator	experiment delete
`GET`	`/api/v1/experiments/{id}`	observer	experiment get
`GET`	`/api/v1/experiments/{id}/export`	observer	experiment export
`POST`	`/api/v1/experiments/{id}/run`	operator	experiment run

grants

Method	Path	Minimum role	Operation
`GET`	`/api/v1/grants`	observer	grants list
`DELETE`	`/api/v1/grants/{id}`	operator	grant revoke

integrations

Method	Path	Minimum role	Operation
`GET`	`/api/v1/integrations`	observer	integrations list
`POST`	`/api/v1/integrations`	administrator	integrations create
`DELETE`	`/api/v1/integrations/{id}`	administrator	integration delete
`GET`	`/api/v1/integrations/{id}`	observer	integration get
`PUT`	`/api/v1/integrations/{id}`	administrator	integration put
`GET`	`/api/v1/integrations/{id}/documents`	observer	integration documents
`POST`	`/api/v1/integrations/{id}/run`	operator	integration run
`GET`	`/api/v1/integrations/{id}/runs`	observer	integration runs

intentions

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/intentions`	observer	intentions list
`GET`	`/api/v1/minds/{mind}/intentions/{id}`	observer	intention get

llm

Method	Path	Minimum role	Operation
`GET`	`/api/v1/llm/calls`	observer	calls list
`GET`	`/api/v1/llm/calls/{id}`	observer	call get
`GET`	`/api/v1/llm/models`	observer	models list
`POST`	`/api/v1/llm/models`	administrator	models create
`DELETE`	`/api/v1/llm/models/{id}`	administrator	model delete
`PUT`	`/api/v1/llm/models/{id}`	administrator	model put
`GET`	`/api/v1/llm/providers`	observer	providers list
`POST`	`/api/v1/llm/providers`	administrator	providers create
`DELETE`	`/api/v1/llm/providers/{id}`	administrator	provider delete
`GET`	`/api/v1/llm/providers/{id}`	observer	provider get
`PUT`	`/api/v1/llm/providers/{id}`	administrator	provider put
`POST`	`/api/v1/llm/providers/{id}/test`	operator	provider test
`GET`	`/api/v1/llm/roles`	observer	roles list
`PUT`	`/api/v1/llm/roles/{role}`	administrator	role put
`GET`	`/api/v1/llm/usage`	observer	usage

me

Method	Path	Minimum role	Operation
`GET`	`/api/v1/me`	observer	me
`GET`	`/api/v1/me/sessions`	observer	my sessions
`DELETE`	`/api/v1/me/sessions/{id}`	observer	my session revoke
`GET`	`/api/v1/me/tokens`	observer	my tokens
`POST`	`/api/v1/me/tokens`	observer	my token create
`DELETE`	`/api/v1/me/tokens/{id}`	observer	my token revoke

measurements

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/research/measurements`	observer	research measurements

measures

Method	Path	Minimum role	Operation
`GET`	`/api/v1/research/measures`	observer	research measures

minds

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds`	observer	minds list
`POST`	`/api/v1/minds`	administrator	minds create
`POST`	`/api/v1/minds/import`	administrator	mind import
`POST`	`/api/v1/minds/import-archive`	administrator	mind import archive
`GET`	`/api/v1/minds/{mind}`	observer	mind get
`PATCH`	`/api/v1/minds/{mind}`	administrator	mind patch
`POST`	`/api/v1/minds/{mind}/ask`	operator	ask
`GET`	`/api/v1/minds/{mind}/assertions`	observer	list assertions: who took what stance on which proposition
`GET`	`/api/v1/minds/{mind}/assertions/actors`	observer	summarise asserting actors
`GET`	`/api/v1/minds/{mind}/beliefs`	observer	beliefs list
`POST`	`/api/v1/minds/{mind}/beliefs`	operator	beliefs create
`GET`	`/api/v1/minds/{mind}/beliefs/stats`	observer	beliefs stats
`GET`	`/api/v1/minds/{mind}/beliefs/{id}`	observer	belief get
`POST`	`/api/v1/minds/{mind}/beliefs/{id}/alternatives`	operator	belief alternative
`POST`	`/api/v1/minds/{mind}/beliefs/{id}/evidence`	operator	belief evidence
`POST`	`/api/v1/minds/{mind}/beliefs/{id}/retract`	operator	belief retract
`GET`	`/api/v1/minds/{mind}/capabilities`	observer	mind capabilities
`POST`	`/api/v1/minds/{mind}/clone`	administrator	mind clone
`GET`	`/api/v1/minds/{mind}/compare/{other}`	observer	mind compare
`GET`	`/api/v1/minds/{mind}/consolidation`	observer	consolidation jobs
`POST`	`/api/v1/minds/{mind}/consolidation/reject`	operator	consolidation reject
`POST`	`/api/v1/minds/{mind}/consolidation/run`	operator	consolidation run
`GET`	`/api/v1/minds/{mind}/conversations`	observer	conversations list
`POST`	`/api/v1/minds/{mind}/conversations`	operator	conversations create
`GET`	`/api/v1/minds/{mind}/conversations/{id}`	observer	conversation get
`POST`	`/api/v1/minds/{mind}/conversations/{id}/messages`	operator	message post
`GET`	`/api/v1/minds/{mind}/corrections`	observer	corrections list
`POST`	`/api/v1/minds/{mind}/corrections`	operator	corrections create
`POST`	`/api/v1/minds/{mind}/cycle`	operator	workspace cycle
`GET`	`/api/v1/minds/{mind}/dreams`	observer	dreams list
`POST`	`/api/v1/minds/{mind}/dreams/hypotheses/{id}/promote`	operator	dream review
`POST`	`/api/v1/minds/{mind}/dreams/hypotheses/{id}/reject`	operator	dream review
`POST`	`/api/v1/minds/{mind}/dreams/run`	operator	dream run
`POST`	`/api/v1/minds/{mind}/dreams/settings`	administrator	dream settings
`GET`	`/api/v1/minds/{mind}/entities`	observer	entities list
`GET`	`/api/v1/minds/{mind}/entities/{id}`	observer	entity get
`PATCH`	`/api/v1/minds/{mind}/entities/{id}`	operator	entity patch
`POST`	`/api/v1/minds/{mind}/entities/{id}/distinct`	operator	entity distinct
`POST`	`/api/v1/minds/{mind}/entities/{id}/merge`	operator	entity merge
`POST`	`/api/v1/minds/{mind}/entities/{id}/relationships`	operator	entity relate
`GET`	`/api/v1/minds/{mind}/events`	observer	events list
`GET`	`/api/v1/minds/{mind}/events/stats`	observer	events stats
`GET`	`/api/v1/minds/{mind}/events/stream`	observer	events stream
`GET`	`/api/v1/minds/{mind}/export`	operator	mind export
`GET`	`/api/v1/minds/{mind}/goals`	observer	goals list
`POST`	`/api/v1/minds/{mind}/goals`	operator	goals create
`GET`	`/api/v1/minds/{mind}/goals/{id}`	observer	goal get
`PATCH`	`/api/v1/minds/{mind}/goals/{id}`	operator	goal patch
`GET`	`/api/v1/minds/{mind}/graph`	observer	graph get
`POST`	`/api/v1/minds/{mind}/invoke`	operator	invoke
`GET`	`/api/v1/minds/{mind}/memories`	observer	memories list
`POST`	`/api/v1/minds/{mind}/memories`	operator	memories create
`GET`	`/api/v1/minds/{mind}/memories/stats`	observer	memories stats
`GET`	`/api/v1/minds/{mind}/memories/{id}`	observer	memory get
`POST`	`/api/v1/minds/{mind}/memories/{id}/relationships`	operator	memory relate
`POST`	`/api/v1/minds/{mind}/memories/{id}/retract`	operator	memory retract
`POST`	`/api/v1/minds/{mind}/mode`	operator	workspace mode
`GET`	`/api/v1/minds/{mind}/narrative`	observer	narrative get
`GET`	`/api/v1/minds/{mind}/notifications`	observer	notifications list
`POST`	`/api/v1/minds/{mind}/observations`	operator	observation create
`GET`	`/api/v1/minds/{mind}/personality`	observer	personality get
`PUT`	`/api/v1/minds/{mind}/personality`	administrator	personality put
`GET`	`/api/v1/minds/{mind}/personality/brief`	observer	personality brief
`GET`	`/api/v1/minds/{mind}/personality/diff`	observer	personality diff
`POST`	`/api/v1/minds/{mind}/personality/template`	administrator	personality template
`GET`	`/api/v1/minds/{mind}/personality/versions`	observer	personality versions
`GET`	`/api/v1/minds/{mind}/personality/versions/{n}`	observer	personality version
`POST`	`/api/v1/minds/{mind}/personality/versions/{n}/restore`	administrator	personality restore
`GET`	`/api/v1/minds/{mind}/predictions`	observer	predictions list
`POST`	`/api/v1/minds/{mind}/predictions`	operator	predictions create
`GET`	`/api/v1/minds/{mind}/predictions/calibration`	observer	predictions calibration
`GET`	`/api/v1/minds/{mind}/predictions/{id}`	observer	prediction get
`POST`	`/api/v1/minds/{mind}/predictions/{id}/resolve`	operator	prediction resolve
`GET`	`/api/v1/minds/{mind}/redactions`	operator	list the redaction ledger
`POST`	`/api/v1/minds/{mind}/redactions`	administrator	redact a row's content irreversibly (event, memory, message, llm_call, belief, assertion), optionally cascading to derived rows
`GET`	`/api/v1/minds/{mind}/reflections`	observer	reflections list
`POST`	`/api/v1/minds/{mind}/reflections/run`	operator	reflection run
`GET`	`/api/v1/minds/{mind}/replays`	observer	replays list
`POST`	`/api/v1/minds/{mind}/replays`	operator	replay start
`POST`	`/api/v1/minds/{mind}/reset`	operator	workspace reset
`GET`	`/api/v1/minds/{mind}/selfmodel`	observer	mind self model
`GET`	`/api/v1/minds/{mind}/snapshots`	observer	snapshots list
`POST`	`/api/v1/minds/{mind}/snapshots`	operator	snapshot create
`GET`	`/api/v1/minds/{mind}/state`	observer	state get
`PUT`	`/api/v1/minds/{mind}/state/drives/{name}`	administrator	drive set
`POST`	`/api/v1/minds/{mind}/state/reset`	operator	state reset
`GET`	`/api/v1/minds/{mind}/workspace`	observer	workspace get

notifications

Method	Path	Minimum role	Operation
`GET`	`/api/v1/notifications`	observer	notifications list
`POST`	`/api/v1/notifications/read-all`	observer	notifications read all
`POST`	`/api/v1/notifications/{id}/read`	observer	notification read

personality-templates

Method	Path	Minimum role	Operation
`GET`	`/api/v1/personality-templates`	observer	templates list
`POST`	`/api/v1/personality-templates`	administrator	templates create
`DELETE`	`/api/v1/personality-templates/{id}`	administrator	template delete
`GET`	`/api/v1/personality-templates/{id}`	observer	template get
`PUT`	`/api/v1/personality-templates/{id}`	administrator	template put

plans

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/plans`	observer	plans list
`GET`	`/api/v1/minds/{mind}/plans/{id}`	observer	plan get

policies

Method	Path	Minimum role	Operation
`GET`	`/api/v1/policies`	observer	policies list
`POST`	`/api/v1/policies`	administrator	policies create
`DELETE`	`/api/v1/policies/{id}`	administrator	policy delete

prompts

Method	Path	Minimum role	Operation
`GET`	`/api/v1/prompts`	observer	prompts list
`POST`	`/api/v1/prompts`	administrator	prompts save
`GET`	`/api/v1/prompts/{name}`	observer	prompt get
`PUT`	`/api/v1/prompts/{name}`	administrator	prompts save
`POST`	`/api/v1/prompts/{name}/clone`	administrator	prompt clone
`POST`	`/api/v1/prompts/{name}/test`	operator	prompt test
`GET`	`/api/v1/prompts/{name}/versions`	observer	prompt versions
`POST`	`/api/v1/prompts/{name}/versions/{n}/restore`	administrator	prompt restore

replays

Method	Path	Minimum role	Operation
`GET`	`/api/v1/replays/{id}`	observer	replay get

retry

Method	Path	Minimum role	Operation
`POST`	`/api/v1/minds/{mind}/plans/{id}/steps/{step}/retry`	operator	plan step retry

scoped-grants

Method	Path	Minimum role	Operation
`POST`	`/api/v1/minds/{mind}/scoped-grants`	operator	scoped grant create
`GET`	`/api/v1/scoped-grants`	observer	scoped grants list
`DELETE`	`/api/v1/scoped-grants/{id}`	operator	scoped grant revoke

snapshots

Method	Path	Minimum role	Operation
`DELETE`	`/api/v1/snapshots/{id}`	administrator	snapshot delete
`GET`	`/api/v1/snapshots/{id}`	observer	snapshot get
`GET`	`/api/v1/snapshots/{id}/archive`	operator	snapshot archive
`POST`	`/api/v1/snapshots/{id}/fork`	administrator	snapshot fork

system

Method	Path	Minimum role	Operation
`GET`	`/api/v1/system/status`	observer	system status

users

Method	Path	Minimum role	Operation
`GET`	`/api/v1/users`	administrator	users list
`POST`	`/api/v1/users`	administrator	users create
`PATCH`	`/api/v1/users/{id}`	administrator	users patch

want-conflicts

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/want-conflicts`	observer	want conflicts list

wants

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/wants`	observer	wants list
`GET`	`/api/v1/minds/{mind}/wants/{id}`	observer	want get

webhooks

Method	Path	Minimum role	Operation
`POST`	`/api/v1/webhooks/{id}`	none HMAC-signed delivery	receive a signed webhook delivery

why

Method	Path	Minimum role	Operation
`GET`	`/api/v1/minds/{mind}/why`	observer	why

← Interface tour All sections Command line →

Phone:

Email:

[email protected]