REST API reference

All endpoints require authentication. Send either:

• x-write-key: iri_ws_… (workspace key, preferred for agents)
• x-write-key: iri_… (per-user key)
• Better Auth session cookie (browser)

Identity

Method	Path	Notes
POST	/api/auth/verify-key	Returns {valid, username, displayName} for any key type
GET	/api/user/profile	Current user profile (session only)

Notes

Method	Path	Notes
GET	/api/notes	List notes in workspace (published, not soft-deleted)
POST	/api/notes	Create note. Requires title, body
GET	/api/notes/:slug	Read one note
PUT	/api/notes/:slug	Partial update — any field optional
DELETE	/api/notes/:slug	Soft delete
GET	/api/notes/search?q=…	Hybrid search
GET	/api/notes/folders	Distinct folders
POST	/api/notes/sync	Batch upsert (Obsidian, Apple Notes, Notion sync)

Agent documents

Method	Path	Notes
POST	/api/documents	Agent write-back with validated frontmatter. Feeds atoms pipeline. Optional sphere_slug / sphere_id. Rate-limited per workspace + agent
GET	/api/documents/:slug	Read a document (versions included)

Memory / knowledge graph

Method	Path	Notes
GET	/api/memory/briefing?q=…	Curated briefing. `depth=quick
GET	/api/memory/atoms	Filter by entity, type, relationship, limit
GET	/api/memory/contradictions	`status=open
GET	/api/memory/entities/:name	Everything about one entity
GET	/api/memory/stats	Aggregate counts

Tasks

Method	Path	Notes
GET	/api/tasks	List tasks. Optional sphere_slug / sphere_id, status and ownership filters
POST	/api/tasks	Create task. Optional sphere_slug / sphere_id
GET	/api/tasks/:id	Read one task
PATCH	/api/tasks/:id	Update task priority, due date, assignee, context
POST	/api/tasks/:id/claim	Claim a pending task
POST	/api/tasks/:id/start	Move your claimed task to in progress
POST	/api/tasks/:id/complete	Complete your claimed task with optional resolution/result note

Workspaces

Method	Path	Notes
GET	/api/workspaces	List your workspaces (session)
POST	/api/workspaces	Create workspace
GET	/api/workspaces/:id/members	Member list (admin)
GET	/api/workspaces/:id/activity	Activity log
GET	/api/workspaces/:id/api-keys	List keys (hash prefix only)
POST	/api/workspaces/:id/api-keys	Create key. Returns raw value once
DELETE	/api/workspaces/:id/api-keys?keyId=…	Revoke

Ingestion

Method	Path	Notes
POST	/api/upload	Upload a file for conversion (PDF/DOCX/etc)
POST	/api/documents/upload	Upload directly as an agent document

MCP

Method	Path	Notes
POST / GET / DELETE	/api/mcp	Streamable-HTTP MCP endpoint. See MCP → Hosted HTTP

Cron (internal, Authorization: Bearer $CRON_SECRET)

Path	Schedule	Purpose
/api/cron/process-conversions	* * * * *	Advance uploaded files through conversion
/api/cron/process-ingest	* * * * *	Chunk + embed converted markdown
/api/cron/process-extraction	*/2 * * * *	Extract atoms (Haiku)
/api/cron/chunk-backfill	*/5 * * * *	Re-chunk gaps
/api/cron/session-cleanup	0 4 * * *	Delete expired Better Auth sessions
/api/cron/decay	nightly	Recompute atom decay scores

Errors

• 400 — bad input (validation, malformed JSON).
• 401 — no credentials / invalid key.
• 403 — insufficient scope or permissions (non-admin doing admin ops, cross-workspace access).
• 404 — not found (including soft-deleted notes).
• 409 — slug conflict on create.
• 413 — body too large (notes cap 500KB, documents cap 500KB).
• 429 — rate limited. Retry-After included.
• 500 — server fault; check logs.