API reference
The Engrym REST API is described by the canonical OpenAPI 3.1 specification at infra/openapi/openapi.json (Engrym REST API v1.0.0). This page is auto-generated from that artifact.
All endpoints are versioned under /v1. Authentication uses bearer tokens; consult the MCP setup and CLI reference pages for higher-level integration paths.
This reference documents the public knowledge-layer API — the operations you or your agents invoke to operate the knowledge layer on your own projects. Endpoints internal to Engrym's own product operations (billing, newsletter, feedback board, dashboard onboarding, operator-only admin, webhook receivers) are intentionally not listed.
Total operations: 101 across 6 resource groups.
Health
Liveness probe for the Engrym REST API. Returns a fixed status payload.
| Method | Path | Summary |
|---|
GET | /v1/health | Liveness + dependency health probe. |
Version
Reports the API version + build metadata.
| Method | Path | Summary |
|---|
GET | /v1/version | API version + deploy metadata. |
Authentication
Signup, signin, signout, and identity introspection. The dashboard signup flow uses the public surface; CLI / SDK consumers use access tokens bound to the project.
| Method | Path | Summary |
|---|
GET | /v1/auth/me | Return the authenticated user profile. |
POST | /v1/auth/signin | Sign in with email + password. |
POST | /v1/auth/signout | Invalidate the active session. |
POST | /v1/auth/signup | Create a fresh account. |
Projects
Project CRUD + nested resources: documents, Brain atoms, decisions, intents, conflicts, sessions, watcher, extraction, mirror, imports, API keys. Nested sub-resources are listed in their own sub-sections below.
Core
Top-level project CRUD + archive.
| Method | Path | Summary |
|---|
GET | /v1/projects | List projects. |
POST | /v1/projects | Create a project. |
GET | /v1/projects/\{projectId\} | Read a project. |
PATCH | /v1/projects/\{projectId\} | Update a project. |
DELETE | /v1/projects/\{projectId\} | Permanently delete a project (grace-then-purge). |
Activity
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/activity | List the project activity feed. |
API keys
Per-project API key CRUD (for CLI / SDK auth).
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/api-keys | List the calling user's API keys. |
POST | /v1/projects/\{projectId\}/api-keys | Issue an API key. |
DELETE | /v1/projects/\{projectId\}/api-keys/\{keyId\} | Revoke an API key. |
Archive
| Method | Path | Summary |
|---|
POST | /v1/projects/\{projectId\}/archive | Archive a project (soft-delete). |
Brain
Knowledge atom CRUD + search + context queries + deprecation + supersedence.
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/brain/atoms | List/query atoms. |
POST | /v1/projects/\{projectId\}/brain/atoms | Create an atom. |
GET | /v1/projects/\{projectId\}/brain/atoms/\{atomId\} | Read an atom. |
PATCH | /v1/projects/\{projectId\}/brain/atoms/\{atomId\} | Update atom metadata (tags, confidence). |
POST | /v1/projects/\{projectId\}/brain/atoms/\{atomId\}/deprecate | Deprecate an atom. |
GET | /v1/projects/\{projectId\}/brain/atoms/\{atomId\}/diff | Before→after diff of an atom over the supersede chain. |
POST | /v1/projects/\{projectId\}/brain/atoms/\{atomId\}/promote | Promote (ratify) a provisional atom. |
POST | /v1/projects/\{projectId\}/brain/atoms/\{atomId\}/reinstate | Reinstate an atom. |
GET | /v1/projects/\{projectId\}/brain/atoms/\{atomId\}/related | List atoms related to an atom. |
GET | /v1/projects/\{projectId\}/brain/atoms/\{atomId\}/source | Cite an atom — its source document + grounding span. |
GET | /v1/projects/\{projectId\}/brain/atoms/\{atomId\}/sources | List an atom’s backing sources (claim-merge audit). |
POST | /v1/projects/\{projectId\}/brain/atoms/\{atomId\}/supersede | Supersede an atom with a successor. |
GET | /v1/projects/\{projectId\}/brain/context | Read the unified team-context payload. |
GET | /v1/projects/\{projectId\}/brain/contradictions | Surface candidate contradictions for a human to judge. |
GET | /v1/projects/\{projectId\}/brain/project-brief | Assemble the cold-start project brief. |
GET | /v1/projects/\{projectId\}/brain/reconciliation/claims | Serve documented claims to verify against the code. |
POST | /v1/projects/\{projectId\}/brain/reconciliation/verdicts | Submit a docs-vs-code reconciliation verdict. |
GET | /v1/projects/\{projectId\}/brain/relevant-knowledge | Surface ambient knowledge for a file or topic. |
GET | /v1/projects/\{projectId\}/brain/search | Search atoms. |
Conflicts
Conflict detection + resolution + dismiss.
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/conflicts | List active conflicts. |
GET | /v1/projects/\{projectId\}/conflicts/arbitration | List conflicts with colliding intents and resolutions (arbitration/read surface). |
POST | /v1/projects/\{projectId\}/conflicts/check | Pre-check: active intents touching the given files. |
POST | /v1/projects/\{projectId\}/conflicts/\{conflictId\}/dismiss | Dismiss a conflict (false positive). |
POST | /v1/projects/\{projectId\}/conflicts/\{conflictId\}/resolve | Resolve a conflict. |
Connected-agents
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/connected-agents | List per-agent connection status. |
Cross-references
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/cross-references | Read cross-project graph neighbours. |
POST | /v1/projects/\{projectId\}/cross-references | Create a cross-project atom reference. |
Decisions
Decision log CRUD + Markdown export.
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/decisions | List decisions. |
POST | /v1/projects/\{projectId\}/decisions | Log a decision. |
GET | /v1/projects/\{projectId\}/decisions/\{decisionId\} | Read a decision. |
Decisions.md
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/decisions.md | Export the canonical decision-log markdown. |
Documents
Project document CRUD + versions + revert.
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/documents | List documents in a project. |
POST | /v1/projects/\{projectId\}/documents | Create a document. |
GET | /v1/projects/\{projectId\}/documents/\{docId\} | Read a document. |
PATCH | /v1/projects/\{projectId\}/documents/\{docId\} | Update a document. |
DELETE | /v1/projects/\{projectId\}/documents/\{docId\} | Soft-delete a document. |
POST | /v1/projects/\{projectId\}/documents/\{docId\}/revert | Revert document to a historical version. |
GET | /v1/projects/\{projectId\}/documents/\{docId\}/versions | List document versions. |
POST | /v1/projects/\{projectId\}/documents/\{documentId\}/reextract-span | Re-extract a single span of one document (PRD-046 P3 — explicit, not auto-on-save). |
Extraction
Project extraction config + bulk re-extraction.
| Method | Path | Summary |
|---|
POST | /v1/projects/\{projectId\}/extraction/agent-submissions | Submit agent-run extraction results (PRD-048 dual-mode). |
GET | /v1/projects/\{projectId\}/extraction/agent-work | Pull documents needing agent extraction (PRD-048 dual-mode). |
GET | /v1/projects/\{projectId\}/extraction/config | Read the per-project extraction config (provider/model/budget/BYOK proof-of-presence). |
PATCH | /v1/projects/\{projectId\}/extraction/config | Update per-project extraction provider/model/budget/BYOK. |
GET | /v1/projects/\{projectId\}/extraction/progress | Project-level extraction progress aggregate. |
GET | /v1/projects/\{projectId\}/extraction/prompt | Fetch the versioned extraction prompt (PRD-048 dual-mode). |
POST | /v1/projects/\{projectId\}/extraction/re-extract-all | Enqueue re-extraction for every document in a project. |
POST | /v1/projects/\{projectId\}/extraction/resume | Resume extraction after a credit pause. |
GET | /v1/projects/\{projectId\}/extraction/runs | List extraction runs (paginated history). |
GET | /v1/projects/\{projectId\}/extraction/status | Per-document latest extraction status. |
Imports
Bulk-import job CRUD.
| Method | Path | Summary |
|---|
POST | /v1/projects/\{projectId\}/imports | Run an import job. |
GET | /v1/projects/\{projectId\}/imports/\{importId\} | Read import job status. |
DELETE | /v1/projects/\{projectId\}/imports/\{importId\} | Cancel a pending or running import job. |
Init-brief
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/init-brief | Assemble the populated-on-arrival first-run init brief. |
Intents
Active intent broadcast + list + retract.
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/intents | List active intents. |
POST | /v1/projects/\{projectId\}/intents | Broadcast an intent. |
DELETE | /v1/projects/\{projectId\}/intents/\{intentId\} | Release an intent (transition active → released). |
Git mirror
Configure, status, test, and force-push the Git mirror.
| Method | Path | Summary |
|---|
POST | /v1/projects/\{projectId\}/mirror/configure | Configure git mirror. |
POST | /v1/projects/\{projectId\}/mirror/push | Trigger an immediate mirror push. |
GET | /v1/projects/\{projectId\}/mirror/status | Read git mirror status. |
POST | /v1/projects/\{projectId\}/mirror/test | Test git mirror connection. |
Restore
| Method | Path | Summary |
|---|
POST | /v1/projects/\{projectId\}/restore | Restore a pending-deletion project (grace window only). |
Sessions
Session lifecycle + active session retrieval.
| Method | Path | Summary |
|---|
POST | /v1/projects/\{projectId\}/sessions | Start a session. |
GET | /v1/projects/\{projectId\}/sessions/latest | Read the caller's latest session for this project. |
PATCH | /v1/projects/\{projectId\}/sessions/\{sessionId\} | Save session state. |
POST | /v1/projects/\{projectId\}/sessions/\{sessionId\}/end | End a session. |
Timeline
| Method | Path | Summary |
|---|
GET | /v1/projects/\{projectId\}/timeline | What changed — the date-bounded knowledge changelog. |
GET | /v1/projects/\{projectId\}/timeline/history | Show the debate — a subject’s supersession/reversal arc. |
Watcher
Watcher insight retrieval + manual run trigger + config.
| Method | Path | Summary |
|---|
PATCH | /v1/projects/\{projectId\}/watcher/config | Update per-project Watcher configuration (503 stub at v1). |
GET | /v1/projects/\{projectId\}/watcher/insights | List Watcher insights for a project (503 stub at v1). |
POST | /v1/projects/\{projectId\}/watcher/run | Trigger an ad-hoc Watcher run (503 stub at v1). |
Teams
Team CRUD + member management + invitations. Teams own projects; members inherit project access through team membership.
| Method | Path | Summary |
|---|
POST | /v1/teams | Create a team. |
POST | /v1/teams/invites/\{inviteId\}/accept | Accept a team invite. |
GET | /v1/teams/\{teamId\} | Read a team. |
PATCH | /v1/teams/\{teamId\} | Update a team. |
POST | /v1/teams/\{teamId\}/invites | Issue a team invite. |
GET | /v1/teams/\{teamId\}/links | List the team's project links. |
POST | /v1/teams/\{teamId\}/links | Link two projects of the team. |
DELETE | /v1/teams/\{teamId\}/links/\{linkId\} | Revoke a project link. |
GET | /v1/teams/\{teamId\}/members | List team members. |
GET | /v1/teams/\{teamId\}/pool | Read the team's shared-knowledge pool project. |
POST | /v1/teams/\{teamId\}/pool | Get-or-create the team's shared-knowledge pool project. |
GET | /v1/teams/\{teamId\}/pool/atoms | Query the team pool. |
POST | /v1/teams/\{teamId\}/pool/entries | Write one knowledge entry into the team pool. |
GET | /v1/teams/\{teamId\}/rollup | Read the portfolio rollup. |
Providers
| Method | Path | Summary |
|---|
GET | /v1/providers | List the provider/model catalog. |