# Miriel API — condensed reference for AI assistants

> Drop this file into your AI assistant's context (CLAUDE.md, project
> knowledge, system prompt) to let it write correct Miriel API calls.
> Full docs: `GET {API_BASE}/api/v2/developer/docs` or the dashboard's
> Developers page.

Miriel is a context platform: ingest resources ("learn"), keep them fresh
via integrations, query them with retrieval + LLM synthesis, expose them to
AI clients over MCP, and define whole apps in natural language (Workflow
Apps) that run on the platform.

## Basics

- Base URL: `{API_BASE}` (e.g. `https://api.miriel.ai`); preview builds use `https://dev-<branch>-api.builds.miriel.ai`.
- Auth: every request sends header `x-access-token: <API key or session JWT>`. The API key is a UUID from the dashboard's Developers page. No Bearer scheme.
- Session JWT (2-week) from `POST /api/dashboard/v1/login` with HTTP Basic (email/password). `GET /api/dashboard/v1/api_key` returns `{"apiKey"}`.
- Errors: 401 `{"message": "Api key / token is missing!"}` / `{"message": "Token is invalid!"}`; 403 `{"error": "Superadmin access required"}` on gated routes.
- Health check (no auth): `GET /api/v2/health`.
- Interactive spec: Swagger UI `GET /api/v2/docs`, spec `GET /api/v2/swagger.json` (note: some routes, incl. `/learn`, are documented here but absent from the generated spec).

## Ingest (learn)

`POST /api/v2/learn` — JSON or multipart.

```json
{
  "project": ["default"],
  "input": [{"value": "text | https://url | uploaded-filename",
             "upsert_id": "optional-stable-id",
             "expiration_seconds": 86400}],
  "metadata": {"any": "kv"},
  "discoverable": true,
  "chunk_size": 512,
  "recursion_depth": 1
}
```

- File upload: multipart with `files=@file` + form fields `project`, `input` (JSON strings).
- URLs crawl (`recursion_depth`); `rtsp://` / video-stream URLs route to stream ingestion (`streams`, `streaming_options`).
- Async: response carries job ids → `POST /api/v2/get_job_status`, `GET /api/v2/jobs/<job_id>/timeline`.
- `POST /api/v2/upload_files` = multipart alias of learn.

Resources/projects: `POST /api/v2/get_all_documents`, `get_resource`, `stream_resource`, `remove_resource`, `resource_versions`, `restore_resource_version`, `edit_content` (+ `edit_csv|image|docx_content|pptx_content|3d_model|file_metadata`), `get_projects`, `create_project`, `delete_project`, `set_resource_access`. Types: `GET /api/v2/get_supported_types`. Providers manifest: `GET /api/v2/providers/`.

## Query

`POST /api/v2/query/`

```json
{"query": "question", "project": "default", "num_results": 8,
 "want_vector": true, "want_graph": true, "want_llm": true,
 "model": "optional-model-override",
 "conversation_mode": "<previous query_id for multi-turn>",
 "streaming": false, "voice_mode": false,
 "use_hyde": false, "context_distillation": false,
 "output_type": "optional", "publish_options": {}, "results_storage": {}}
```

Returns ranked passages with sources + LLM answer. Stored results:
`GET /api/v2/query/` (history, paged), `GET /api/v2/query/<query_id>`,
`GET /api/v2/query/<query_id>/download` (presigned URL),
`POST /api/v2/query/timed` (stage timings), `POST /api/v2/query/recall`
(precision/recall eval), `POST /api/v2/format_query_result`.

Knowledge graph: `POST /api/v2/graph/relationships|traverse|stats|merge|delete`.

## Integrations & sources

- OAuth per provider: `GET /api/v2/oauth/<provider>/authorize`, `GET .../status`, `POST .../disconnect`; `GET /api/v2/oauth/connections`. Providers: google, microsoft, slack, discord, dropbox, github, notion, salesforce, zoom, addepar, replit, blink (affinity via `/credentials`).
- Browse before configuring: `/oauth/google/drives|calendars|labels`, `/microsoft/drives|mail_folders|calendars`, `/slack/channels`, `/discord/guilds`, `/github/repos`, `/dropbox/folders`, `/salesforce/objects`, `/zoom/recordings`.
- Sources (unified ingestion): `GET|POST /api/v2/sources/`, `GET|PATCH|DELETE /api/v2/sources/<id>`, `POST .../backfill`, `POST .../pause`, `POST .../resume`, `GET .../status`.
- Legacy: watchers (`/api/v2/watchers/` + `/start|stop|restart|snapshot|test-connection|introspect|status`), sync configs (`/api/v2/sync/` + `/<id>/trigger|status`).
- Inbound webhook ingest (no header auth): `POST /api/v2/webhooks/ingest/<watcher_id>`.
- Git repos: `POST /api/v2/git_repos/sync_git_repo`, `remove_git_repo`; `GET /api/v2/git_repos/git_repos`.
- Local bidirectional project sync (metadata only): `GET /api/v2/project/<project>/resources?modified_since=`, `PUT|DELETE /api/v2/project/<project>/resource`, `GET /api/v2/project/<project>/changes?since=`.
- Org-shared credentials (admin): `/api/v2/org-credentials/` + `POST /share` + grants.

## MCP (AI-client access)

- One-call default server: `POST /api/v2/mcp/default` → hosted "Miriel Context Manager" with tools `miriel_learn` + `miriel_query`. Tool usage guide: `GET /api/v2/mcp/default/instructions`.
- Client endpoint: `{API_BASE}/api/v2/mcp/protocol/<endpoint-slug>` — Streamable HTTP + legacy SSE, protocol `2024-11-05`/`2025-03-26`. The slug is the credential (no header). Config: `{"mcpServers": {"miriel": {"url": "<endpoint>"}}}`.
- Custom servers: `GET|POST /api/v2/mcp/`, `GET|PATCH|DELETE /api/v2/mcp/<id>`, `POST /api/v2/mcp/from-query/<query_id>`, `GET|POST /api/v2/mcp/<id>/queries`, `POST /api/v2/mcp/<id>/deploy|undeploy|download`, `POST /api/v2/mcp/merge`, `GET /api/v2/mcp/<id>/invocations|stats|analytics`.

## App builder (Workflow Apps) — `/api/v2/workflow-apps`

Lifecycle: `POST /compile` (NL description → manifest draft) → `POST /` (create) → `POST /<app_id>/activate` (register workflows, provision data structures, kick off AutoDev if UI wanted) → runs.

- Manifest: `kind` ∈ automation|agent|reconciliation|custom_software; `ui.mode` ∈ none|generated_workspace|dashboard_route|custom; workflow step task types: `percept_query`, `classify_or_extract`, `reconcile_record`, `request_input`, `await_event`, `call_tool`, `write_state`, `emit_event`.
- Versions: `GET /<app_id>/versions`, `GET .../versions/diff?from=&to=`, `POST .../amend` (NL change), `POST .../rollback`, `POST .../pause`.
- Data needs: `GET /<app_id>/data-needs`, `POST .../data-needs/<need_id>/resolve`. Grants: `GET|POST /<app_id>/grants`.
- Runtime: `GET /<app_id>/status`; runs `GET|POST /<app_id>/runs`, `GET|PATCH .../runs/<run_id>`; records `GET|POST /<app_id>/records`, `.../records/<id>/candidates`, `POST .../records/<id>/signal`; interactions `GET|POST /<app_id>/interactions`, `POST .../interactions/<id>/respond`; free-text `POST /<app_id>/ask`.
- Agents: `GET /<app_id>/agent/briefing`, `POST /<app_id>/agent/dispatch`; global `POST /api/v2/agent/dispatch` (`{"prompt" | "query_id", "backend": "claude_code|codex|lm_studio|custom_http"}`), `GET /api/v2/agent/backends`.
- AutoDev (generated UIs/previews): `POST /<app_id>/autodev/dispatch`; `GET /<app_id>/autodev/status` → `{status, pr_url, preview_url, agent:{state, session_url}}`.
- Note: `/api/v2/workflows` (no `-apps`) is a different, older coordination feature.

## PerceptDB proxy — `/api/v2/percept`

Direct engine access, Miriel-authenticated (currently superadmin-gated until per-tenant Percept keys land; expect 403 otherwise):
`GET /status`, `GET /indexes`, `POST /search` `{"query","index"?("default"|"images"),"limit"?}`, `POST /vectors/<index>/query` `{"vector"|"vectors","topK"?,"where"?}`, `POST /sql` `{"query"}`. Success wraps as `{"data": ...}`; Percept-side failure → 502 `{"error": ...}`. Prefer `POST /api/v2/query/` unless you need raw engine operations.

## Conventions & gotchas

- Trailing slashes: namespace roots accept both (`/api/v2/query` and `/api/v2/query/`).
- Project listing is `POST /api/v2/get_projects` (not `GET /api/v2/projects`).
- Ingestion is asynchronous; poll job status before expecting query hits.
- Account limits exist (resource counts, daily/monthly queries, monthly tokens); over-limit calls return explanatory errors. `GET /api/v2/limits/`.
- Public share surfaces (data rooms, work rooms, landing pages) use scoped guest JWTs (`Authorization: Bearer` or `?token=`) issued by `POST /api/v2/<area>/public/<slug>/auth` — separate from account auth.