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.

Total operations: 73 across 8 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. |

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). |

Billing

| Method | Path | Summary | | ------ | ---- | ------- | | POST | /v1/projects/\{projectId\}/billing/checkout-session | Create a Stripe Checkout Session. | | POST | /v1/projects/\{projectId\}/billing/portal-session | Create a Stripe Customer Portal session. | | GET | /v1/projects/\{projectId\}/billing/subscription | Read the project's Stripe subscription mirror row. |

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. | | 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/search | Search atoms. |

Conflicts

Conflict detection + resolution + dismiss.

| Method | Path | Summary | | ------ | ---- | ------- | | GET | /v1/projects/\{projectId\}/conflicts | List active conflicts. | | 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. |

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. |

Extraction

Project extraction config + bulk re-extraction.

| Method | Path | Summary | | ------ | ---- | ------- | | PATCH | /v1/projects/\{projectId\}/extraction/config | Update per-project extraction provider/model/budget/BYOK. | | POST | /v1/projects/\{projectId\}/extraction/re-extract-all | Enqueue re-extraction for every document in a project. |

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. |

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. |

Onboarding

| Method | Path | Summary | | ------ | ---- | ------- | | GET | /v1/projects/\{projectId\}/onboarding | Read first-run onboarding status. | | POST | /v1/projects/\{projectId\}/onboarding/complete | Complete first-run onboarding. |

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. |

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\}/members | List team members. |

Billing

| Method | Path | Summary | | ------ | ---- | ------- | | POST | /v1/billing/webhook | Stripe webhook receiver (Stripe → server). |

Newsletter

| Method | Path | Summary | | ------ | ---- | ------- | | POST | /v1/newsletter/confirm | Confirm a newsletter signup. | | POST | /v1/newsletter/resend-webhook | Resend delivery-event webhook receiver. | | POST | /v1/newsletter/signup | Subscribe to the newsletter. | | POST | /v1/newsletter/unsubscribe | Unsubscribe from the newsletter. |

Users

| Method | Path | Summary | | ------ | ---- | ------- | | GET | /v1/users/\{userId\}/billing/subscriptions | List the user's Stripe subscriptions. |