REST API

Endpoint index

Every route in the published contract, grouped the way the API groups them, each pointing at the page that explains it.

Every route in the published contract, grouped the way the OpenAPI document groups them, with the page that explains each one. Paths are shown in their /v1 form, which is the one to build against. Each also exists unversioned for the clients already written that way, except where a row says otherwise.

The same list is machine-readable, so you can generate a client rather than hand-write one:

curl https://api.engramdynamics.org/openapi.json -o engram-openapi.json

It is browsable at /docs. To check what a particular key is allowed to reach, call something harmless with it and read the refusal:

curl -i https://api.engramdynamics.org/v1/corpora   -H "Authorization: Bearer <your key>"

A 200 means the credential is live. A 403 names the scope it is missing, and a 401 means the key is revoked, expired or mistyped.

Service and versions

Method	Path	What it does	Explained on
`GET`	`/`	Which contracts this deployment serves	Overview
`GET`	`/v1`	The version document, with any scheduled deprecations	Overview
`GET`	`/v1/status`	Public service status	Conventions
`GET`	`/v1/status/slo`	Published service objectives and how we are tracking	Conventions

Document bases

Method	Path	What it does	Explained on
`POST`	`/v1/corpora`	Create a document base	Document bases
`GET`	`/v1/corpora`	List document bases, paginated	Document bases
`GET`	`/v1/corpora/{id}`	One base, with its readiness counts	Document bases
`DELETE`	`/v1/corpora/{id}`	Delete a base and everything in it	Document bases
`POST`	`/v1/corpora/{id}/documents`	Upload files as multipart form data	Documents and ingest
`GET`	`/v1/corpora/{id}/documents`	List documents, paginated	Documents and ingest
`DELETE`	`/v1/corpora/{id}/documents/{doc_id}`	Delete one document everywhere	Documents and ingest
`POST`	`/v1/corpora/{id}/import`	Import a connected Drive or SharePoint folder	Google Drive
`GET`	`/v1/corpora/{id}/import-status`	Latest import run for this base	Google Drive

Documents and ingest

Method	Path	What it does	Explained on
`POST`	`/v1/corpora/{id}/documents/diff`	Ask which files are new, changed, unchanged or missing	Documents and ingest
`POST`	`/v1/corpora/{id}/documents/upload-urls`	Get presigned PUT URLs for a manifest	Documents and ingest
`PUT`	`/v1/corpora/{id}/documents/raw`	Upload one file body (used where presigning is not available)	Documents and ingest
`POST`	`/v1/corpora/{id}/documents/commit`	Register the manifest and start the work	Documents and ingest
`POST`	`/v1/corpora/{id}/documents/upsert`	Write one document by path, content included	Documents and ingest
`GET`	`/v1/corpora/{id}/sync-runs`	Ingestion history for this base	Documents and ingest
`GET`	`/v1/corpora/{id}/sync-runs/{run_id}`	One ingestion run and its counters	Documents and ingest

Onboarding and jobs

Method	Path	What it does	Explained on
`POST`	`/v1/corpora/{id}/train`	Start onboarding	Onboarding and jobs
`POST`	`/v1/corpora/{id}/cancel`	Cancel the run in flight	Onboarding and jobs
`POST`	`/v1/corpora/{id}/describe`	Regenerate the base's catalog description	Onboarding and jobs
`GET`	`/v1/jobs/{job_id}`	One job, with progress and estimate	Onboarding and jobs
`GET`	`/v1/corpora/{id}/jobs`	The run and its batches, newest first	Onboarding and jobs

Answers, MCP and feedback

Method	Path	What it does	Explained on
`POST`	`/v1/corpora/{id}/chat`	Ask a question, get an answer with sources	Answers and chat
`POST`	`/v1/corpora/{id}/chat/stream`	The same, streamed as server-sent events	Answers and chat
`POST`	`/v1/mcp/{id}/query`	Ask, with sources attributed by pinnable doc id	Answers and chat
`GET`	`/v1/mcp/{id}/meta`	Base identity, status and catalog description	Tools reference
`GET`	`/v1/mcp/{id}/documents`	The base's document inventory	Tools reference
`POST`	`/corpora/{id}/feedback`	Rate an answer. Unversioned path only	Answers and chat

Sources

Method	Path	What it does	Explained on
`POST`	`/v1/corpora/{id}/sources`	Register a bucket, Drive folder or SharePoint library	Sources
`GET`	`/v1/corpora/{id}/sources`	The sources feeding this base	Sources
`PUT`	`/v1/corpora/{id}/sources/{source_id}`	Change a source's inventory configuration	Amazon S3 buckets
`DELETE`	`/v1/corpora/{id}/sources/{source_id}`	Stop pulling from a source	Sources
`POST`	`/v1/corpora/{id}/sources/{source_id}/validate`	Re-check access and report what it saw	Amazon S3 buckets
`POST`	`/v1/corpora/{id}/sources/{source_id}/sync`	Pull now, and return the run to watch	Sources
`GET`	`/v1/sources/s3/setup`	Render the IAM templates for one source	Amazon S3 buckets
`POST`	`/v1/corpora/{id}/upload-credentials`	An hour of S3 credentials scoped to this base	Sources
`GET`	`/v1/platform/info`	Region, egress guidance, accepted file types. Public	What counts as a document

Webhooks

Method	Path	What it does	Explained on
`POST`	`/v1/webhooks`	Subscribe an endpoint and receive its signing secret	Subscribe an endpoint
`GET`	`/v1/webhooks`	The workspace's endpoints and their last delivery	Subscribe an endpoint
`DELETE`	`/v1/webhooks/{webhook_id}`	Unsubscribe	Subscribe an endpoint

Keys, sign-on and network

Method	Path	What it does	Explained on
`POST`	`/v1/api-keys`	Mint a key. The secret is shown once	Overview and authentication
`GET`	`/v1/api-keys`	The workspace's keys, revoked ones included	API keys and scopes
`DELETE`	`/v1/api-keys/{key_id}`	Revoke a key, effective on the next request	API keys and scopes
`GET`	`/v1/enterprise/sso`	Read the single sign-on configuration	Single sign-on
`PUT`	`/v1/enterprise/sso`	Configure single sign-on	Single sign-on
`DELETE`	`/v1/enterprise/sso`	Turn single sign-on off	Single sign-on
`POST`	`/v1/enterprise/sso/test`	Test the configuration before enforcing it	Single sign-on
`GET`	`/v1/enterprise/ip-allowlist`	Read the workspace IP allowlist	IP allowlist
`PUT`	`/v1/enterprise/ip-allowlist`	Set the workspace IP allowlist	IP allowlist
`GET`	`/v1/enterprise/kms-key`	Read the customer-managed encryption key	Your own KMS key
`PUT`	`/v1/enterprise/kms-key`	Set the customer-managed encryption key	Your own KMS key

Audit, exports and erasure

Method	Path	What it does	Explained on
`GET`	`/v1/audit`	The append-only audit trail	Audit log
`GET`	`/v1/audit/deletions`	Deletion receipts, tier by tier	Data lifecycle and deletion
`GET`	`/v1/audit/export`	Download the audit log	Exports
`GET`	`/v1/usage/export`	Download usage for the workspace	Exports
`GET`	`/v1/platform/erasure-timeline`	How long each copy of a deleted document lives	Data lifecycle and deletion

Plans, billing and legal

Method	Path	What it does	Explained on
`GET`	`/v1/plans`	The published plans and what each includes	Plans and allowances
`GET`	`/v1/billing/status`	This workspace's plan, subscription state and entitlements	Plans and allowances
`POST`	`/v1/billing/checkout`	Start checkout for a plan	Checkout and portal
`POST`	`/v1/billing/portal`	Open the billing portal	Checkout and portal
`POST`	`/v1/billing/change-plan`	Move between plans	Checkout and portal
`GET`	`/v1/legal/status`	Which agreements this workspace has accepted	Terms and DPA acceptance
`POST`	`/v1/legal/accept`	Accept the current version of an agreement	Terms and DPA acceptance
`GET`	`/v1/legal/{document}`	Read an agreement. Public	Terms and DPA acceptance
`GET`	`/v1/legal/{document}/receipt`	The acceptance receipt for an agreement	Terms and DPA acceptance

Accounts

Method	Path	What it does	Explained on
`POST`	`/v1/auth/login`	Sign in and receive a session token	Security overview
`POST`	`/v1/auth/register`	Create an account and a workspace	Your first document base
`GET`	`/v1/auth/me`	The signed-in user and their workspace	Security overview
`GET`	`/v1/auth/config`	Which sign-in methods this workspace allows	Single sign-on
`POST`	`/v1/auth/sso/start`	Begin a single sign-on login	Single sign-on
`POST`	`/v1/auth/forgot-password`	Send a reset link	Security overview
`POST`	`/v1/auth/reset-password`	Complete a reset	Security overview
`POST`	`/v1/auth/resend-verification`	Resend the email confirmation link	Security overview
`POST`	`/v1/auth/invite-info`	Read an invite before accepting it	Security overview
`POST`	`/v1/auth/accept-invite`	Join a workspace from an invite	Security overview

What is not in this index

Some routes exist on the service and are deliberately left out here, because building against them would be building against something that is allowed to move:

Our operations. Platform administration, the serving-hardware controls, the internal job callbacks and the Prometheus metrics endpoint. None of them belong to a workspace.
Payment and email receivers. The Stripe and email-event webhook endpoints are called by those providers, never by you.
The console's own surfaces. The onboarding wizard, the connector browse and picker routes, the model catalog, member and invite administration, and the comparison and economics demos. They change with the app, so they are not published as a contract. What they do is reachable another way: connectors through Sources, members and invites through the app.

If you are wiring an agent rather than a backend, start at MCP. If you want to be told when work finishes rather than polling for it, start at Webhooks.