mdreel

# docs

API, webhooks & MCP.

mdreel is API-first — everything the UI does is a call you can make yourself. REST for pipelines, webhooks for completion, MCP so an assistant can process a video from inside the IDE.

REST API

base urlhttps://api.mdreel.eu/api/v1authbearer token per keyerrorsRFC 7807 · application/problem+jsonrate limitsper API key
POST/uploadsGet a signed GCS URL + uploadId for a resumable upload.
POST/jobsStart a job from an uploadId. Returns 202 { jobId }.
GET/jobsList your jobs, newest first — the same list the panel shows.
GET/jobs/{id}Poll status: queued · processing (stage, progress) · done · failed.
GET/jobs/{id}/output.mdDownload the Markdown (or output.json for the structured document).
DELETE/jobs/{id}Right-to-erasure: deletes outputs + metadata, audit-logged.
GET/usageHours processed this period and remaining quota.
POST/webhooks/testVerify a webhook endpoint (HMAC signature).
create a jobbash
curl -X POST https://api.mdreel.eu/api/v1/jobs \  -H "Authorization: Bearer $MDREEL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "uploadId": "up_9f2c…",    "options": {      "language_hint": "en",      "retention_days": 0,      "webhook_url": "https://your.app/hooks/mdreel",      "quality": "high"    }  }'# → 202 { "jobId": "job_7a1b…" }

Webhooks

Pass a webhook_url when you create a job and we POST it when the job finishes. Every payload is signed with HMAC-SHA256 over the raw body in an X-Mdreel-Signature header — verify it before trusting the event.

job.completedhttp
POST https://your.app/hooks/mdreelX-Mdreel-Signature: sha256=<hmac>{  "event": "job.completed",  "jobId": "job_7a1b…",  "durationSec": 2832,  "outputUrl": "https://api.mdreel.eu/api/v1/jobs/job_7a1b…/output.md"}# Verify: HMAC-SHA256(body, your signing secret) === header

MCP server

The mdreel MCP server is a thin layer over the same REST API — no separate business logic — so an AI assistant can process a recording and cite its Markdown without leaving the editor. Point your MCP client at it:

.mcp.jsonjson
{  "mcpServers": {    "mdreel": {      "command": "npx",      "args": ["-y", "@mdreel/mcp"],      "env": { "MDREEL_API_KEY": "sk_live_…" }    }  }}# Tools: process_video(uploadId|url), get_job(jobId), get_output(jobId), list_jobs()

tools: process_video(uploadId|url) · get_job(jobId) · get_output(jobId) · list_jobs()

llms.txt

We publish a /llms.txt so an agent can discover what mdreel does and how to call it. If you are building an assistant that recommends tools, this is the machine-readable summary to read first.

Data & residency

All processing runs in EU regions; source video is deleted after processing by default, and DELETE /jobs/{id} is a first-class right-to-erasure endpoint. The honest residency story — EU data residency on Google Cloud, not full sovereignty — is on the trust page.