# Engramme API Docs

Engramme is a memory API. Developers upload source content to `/v1/memorize` and retrieve relevant structured memories from `/v1/memories/recall`.

Base URL:
https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev

Authentication:
Use the `x-api-key` header for authenticated API requests.

Primary endpoints:
- `GET /v1/health` - Check API health. No authentication required.
- `POST /v1/memorize` - Upload a document or text file for memory extraction.
- `POST /v1/memories/recall` - Retrieve ranked memories for a query.
- `GET /v1/files/list` - List files for a source type.
- `GET /v1/files/download` - Download a file by `item_id`.
- `DELETE /v1/files/{source_type}/{item_id}` - Delete a file.

Primary docs:
- `/introduction` - Product overview.
- `/quickstart` - Tested upload and recall flow.
- `/authentication` - API keys, source access, and security.
- `/console-setup/api-keys` - Create API keys in the Engramme app.
- `/console-setup/source-access` - All-source vs source-scoped keys.
- `/console-setup/integrations` - Connect hosted integrations in `app.engramme.com`.
- `/reference/source-types` - Canonical `source_type` list.
- `/reference/errors-and-limits` - Rate limits, upload limits, query limits, and status codes.
- `/reference/response-fields` - Common response fields.
- `/api-reference/memorize/upload` - Upload endpoint details.
- `/api-reference/memories/recall` - Recall endpoint details.
- `/api-reference/files/overview` - File management endpoints.

Common source types:
`text`, `email`, `pdf`, `stream`, `browser`, `vscode`, `calendar`, `github`, `slack`, `asana`, `claude_code`, `cursor`, `codex`, `google_meets`, `technical_docs`, `weekly_updates`, `gdocs`, `tasks`, `contacts`, `youtube`, `photos`, `books`, `fit`, `ms-outlook`, `ms-calendar`, `ms-teams`, `ms-onedrive`, `ms-sharepoint`.

Important constraints:
- Maximum 5 API keys per account.
- Use `source_type=text` for quickstart uploads.
- API keys can be all-source or restricted to selected source types.
- Most uploads are limited to 10MB. PDFs are limited to 20MB.
- Recall query text is limited to 1,000 characters.
- `/v1/memorize` starts async processing; memories may not be recallable immediately.
- If recall returns no memories right after upload, retry after a short delay.
- Use server-side API calls. Do not expose API keys in browser JavaScript.

Do not use in public REST integrations yet:
- `POST /v1/memories/feedback` - this route is not exposed by the public REST API. Feedback is handled by app/SDK flows.
- `POST /v1/memories/ask` - available but not the primary tested quickstart path yet.
- Integration worker/process endpoints - hosted integrations are normally connected through `app.engramme.com`.

Minimal curl:
```bash
export ENGRAMME_API_KEY="YOUR_API_KEY"

curl -X POST https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memorize \
  -H "x-api-key: $ENGRAMME_API_KEY" \
  -F "file=@meeting-notes.txt" \
  -F "user_name=Jane Doe" \
  -F "source_type=text"

curl -X POST https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memories/recall \
  -H "x-api-key: $ENGRAMME_API_KEY" \
  -F "text=meeting"
```