# 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 (the Miriel account's ID token, about an hour) from `POST /api/dashboard/v1/account_login` with HTTP Basic (email/password); the older `/login` answers 410. `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_chunks`, `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}}`.
- Turning App Builder on for an org (one-time; owner/admin): install the Miriel Autodev GitHub App on the org's GitHub, sign in to the build console with the existing Miriel account and *Connect to <org>*; the first `/build` then sets up the `miriel-apps` repo, profile, registry and CI behind a setup card whose Retry advances it. No GitHub → Miriel staff enable a Miriel-hosted repo. `autodev_org_unset` = not connected yet. Full guide: `GET /api/v2/developer/docs/app-builder-setup`.
- Staged workflows (the old `/api/v2/workflows`, now 410): `GET|POST /workflows`, `GET /workflows/templates`, `GET /workflows/metrics`, `GET|PATCH /<app_id>/workflow`, `POST .../workflow/advance`, `POST .../workflow/steps/<key>`, `POST .../workflow/comment`; any app's run summary `GET /<app_id>/summary`. Step approvals are Inbox actions (`workflow_step.approve`).

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

## Cameras — `/api/v2/cameras`

An organization's cameras (recorded and searched by NVIDIA VSS). Credential: an **organization API token** `mir_…` as `x-access-token` (issue: Dashboard → Developers → API tokens, or `POST /api/v2/api-tokens/` `{"name","scopes","expires_at"?}` with a signed-in session + `X-Miriel-Org`; shown once; `GET /api-tokens/scopes`, `GET /api-tokens/`, `DELETE /api-tokens/<id>`). Scopes: `cameras:read`, `cameras:ask`, `cameras:manage`, `alerts:read`, `alerts:manage`, `webhooks:manage`. A token works only on `/api/v2/cameras/*` (403 `token_scope_refused` elsewhere) and dies with its issuer's membership (401 `token_member_gone`).
`GET /cameras/` `{cameras:[{id,name,site,location,role,paused}],can_add}` · `GET /cameras/<id>/thumb` (jpeg) · `POST /cameras/<id>/live` `{url}` · `GET /cameras/<id>/clip?start=&end=` `{url}` (≤5 min, last 24 h) · `GET /cameras/media/<token>` (bytes for any returned media url) · `POST /cameras/search` `{query,camera_ids?,start?,end?}` (last 48 h) · `POST /cameras/question` `{query,camera_ids?,start?,end?,timezone?}` → answer+clips or `{job}` → `GET /cameras/jobs/<id>` · `POST /cameras/assess` · `GET|POST /cameras/rules` `{prompt,camera_ids?}` · `POST /cameras/rules/<id>/stop` · `GET /cameras/alerts?hours=` · `POST /cameras/alerts/<n>/seen` · `GET /cameras/zones` · `PUT /cameras/<id>/zone` · `GET /cameras/activity` · grants `GET /cameras/<id>/grants`, `PUT|DELETE /cameras/<id>/grants/<org>` · `GET /cameras/counts?start=&end=&bin=&camera_ids=` (objects per camera/type/bin, a day at most) · `GET /cameras/tracks?seconds=&at=&camera_ids=` (last position per object, u/v 0..1) · `GET /cameras/<id>/detections?width=` (detector frame, jpeg) · `GET /cameras/health` · `GET /cameras/status?camera_ids=` (recording/index coverage) · `POST /cameras/documents/check` `{document:{name,mime,data},camera_ids?,context?}`.
Rate limits per token per minute: reads 600, media 120, search 60, question/assess 10, writes 30; `429` carries `Retry-After` and `X-RateLimit-*`. Full guide: `GET /api/v2/developer/docs/cameras`; Swagger for this API only: `GET /api/v2/developer/cameras/docs` (spec `/api/v2/developer/cameras/swagger.json`).

## 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, shared sessions, landing pages) use scoped guest JWTs (`Authorization: Bearer` or `?token=`) issued by `POST /api/v2/<area>/public/<slug>/auth` — separate from account auth. A shared session's guest lane is `/api/v2/sessions/public/<id-or-address>/…`; work rooms and GenWeave rooms are sessions now (their old routes answer 410).
