# Markovo

Markovo turns files and explicitly authorized public HTTPS pages into clean Markdown and a traceable artifact bundle. PDF to Markdown is available. URL import, DOCX, PPTX, XLSX, Text/Markdown/JSON/XML, HTML, CSV, Image OCR, EPUB, Notion Export ZIP, audio, and video audio-track transcription are authenticated Beta capabilities. Audio accepts MP3/WAV/M4A/AAC/FLAC/OGG/OPUS/WMA; video accepts MP4/MOV/M4V/WebM/MKV/AVI/WMV and does not inspect frames or identify speakers. Never treat Beta as anonymous access.

Canonical origin: https://markovo.net

Public surfaces:
- Converter: `/`
- Pricing: `/pricing`
- Developer documentation: `/docs`
- Word conversion: `/word-to-markdown`
- PowerPoint conversion: `/powerpoint-to-markdown`
- Excel conversion: `/excel-to-markdown`
- Audio conversion: `/audio-to-markdown`
- Video audio-track conversion: `/video-to-markdown`
- Public HTTPS page conversion: `/url-to-markdown`
- Copy-ready developer guide: `/developer.md`
- Capability status and roadmap: `/capabilities.md`
- Account, history, Credits, API keys, and billing: `/app`
- Capability registry: `GET /v1/capabilities`
- Authoritative pricing catalog: `GET /v1/catalog`

Artifact contract:
- `output.md`
- `assets/`
- `metadata.json`
- `source_map.json`
- `quality_report.json`
- `bundle.zip`

Recommended API flow:
1. Send one supported file to `POST /v1/estimates` as multipart `file` with `capability_id` and optional `mode=fast|accurate`.
2. Read `source_units_estimated`, `estimated_credits`, `estimated_runtime_seconds`, `upload_id`, and (for anonymous PDF jobs) `job_token`. PDF responses also include `pages_estimated`.
3. Ask the user to confirm the estimate.
4. Send `upload_id` and a positive `max_credits` to `POST /v1/jobs`. Anonymous requests must also send `x-markovo-job-token`.
5. Poll `GET /v1/jobs/{id}` until `succeeded` or `failed`.
6. Download Markdown or the zip bundle and inspect the quality report before returning a final result.

Public URL Beta uses `POST /v1/url-estimates` with JSON `{"url":"https://...","accept_remote_fetch":true}` instead of multipart upload, then continues with the same confirmation, polling, ownership, History, and Bundle flow. Consent is required before the isolated no-credential sandbox makes a request. Private, signed, credential-bearing, JavaScript-only, paywalled, or access-controlled pages are not supported.

Compatibility shortcut:
- `POST /v1/convert` accepts one or more multipart `file` fields.
- `max_credits` is mandatory. The request is rejected before queueing when the estimate exceeds this ceiling.
- Legacy `PDF2MD_*`, `pdf2md` CLI/MCP commands, and `pdf2md:*` scopes remain compatibility aliases only.
- New API keys use the `mk_live_` prefix and `markovo:convert` scope.

Example:
```bash
export MARKOVO_BASE_URL="https://markovo.net"
export MARKOVO_API_KEY="mk_live_..."

curl -X POST "${MARKOVO_BASE_URL}/v1/convert" \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -F "file=@input.pdf" \
  -F "capability_id=pdf-to-markdown" \
  -F "mode=fast" \
  -F "max_credits=30"

curl "${MARKOVO_BASE_URL}/v1/jobs/{job_id}" \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}"

curl -L "${MARKOVO_BASE_URL}/v1/jobs/{job_id}/download?format=zip" \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -o bundle.zip
```

Limits and lifecycle:
- Anonymous: one job per day, up to 10 pages, result retained for 1 hour.
- Free: 100 Credits per UTC calendar month with no rollover, 1 active API key, up to 5 files per day, result retained for 1 hour.
- Jobs estimated above 12 minutes are rejected in the launch version.
- Source files are deleted after success or terminal failure.
- Plus results are retained for 7 days; Pro results for 30 days.

Pricing:
- Free: $0, 100 Credits per UTC calendar month, no rollover. Historical one-time trial lots remain grandfathered promotions.
- Plus: $8/month, 2,000 Credits; one month of rollover, balance capped at 4,000; API, CLI, and MCP access, with 7-day result retention.
- Pro: $19/month, 6,000 Credits; one month of rollover, balance capped at 12,000; API, CLI, and MCP access, two concurrent jobs, and 30-day result retention.
- Business: waitlist only. Price and limits remain unpublished until margin and production gates pass.
- Credit packs: 2,000/$10, 12,000/$49, 60,000/$199; valid for 365 days.
- Checkout remains in Test Mode; no live charges are accepted.
- No annual, Lifetime, or Unlimited plan is offered at launch.

Credit rules:
- The unified metering feature key is `conversion.credits` for web and API usage.
- Digital PDF and DOCX Beta: 0.1 Credit/measured digital page.
- PPTX Beta: 0.1 Credit/slide.
- XLSX Beta: at least 0.11 Credit, then 0.05 Credit per measured 2,000 non-empty cells with unit-level rounding.
- Image OCR: 0.5 Credit per actual processed page. Server-side route selection never adds Credits beyond the confirmed estimate.
- AI semantic enhancement and chart description: disabled; `quality_level=ai-enhanced` returns `422 quality_level_unavailable` and is not a sold capability.
- CSV: at least 0.07 Credit, then 0.05 Credit per measured 2,000 non-empty cells with unit-level rounding.
- HTML/TXT: at least 0.11 Credit; EPUB: at least 0.07 Credit; Notion: at least 0.06 Credit. Each adds 0.05 Credit per measured 1,000 words with unit-level rounding.
- Audio/video: actual decoded milliseconds with a 0.3 Credit minimum; Audio uses 1 Credit/minute and Video uses 4 Credits/minute. Both have a 50 MiB and 60-minute maximum. Video conversion reads the audio track only.
- Public URL Beta: `max(300, ceil(fetch_ms × 40 / 1,000) + ceil(words × 50 / 1,000)) credit_units`; static public HTTPS HTML/text only.
- These are the active Credit rates. The API uses `1 Credit = 1,000 credit_units`; Creem remains in Test Mode during the production preview.
- The server catalog is authoritative; never trust a client-supplied price or grant amount.

Authentication:
- Same-origin Better Auth endpoint: `/api/auth/*`.
- Google, GitHub, and verified email/password sign-in are available from the web account.
- Google, GitHub, and credential records with the same verified email attach to one Markovo user. That user has one Credits balance, API-key set, and job history. Different emails remain separate accounts.

Quota errors:
- HTTP 402/429 with `error.code=quota_exceeded` can include `action=open_checkout`, `checkout_url`, `required_units`, and `remaining_units`.
- During the production preview, returned checkout URLs are Test Mode only. Retry only after test Credits are available.

CLI and MCP compatibility:
```bash
python -m pip install "https://markovo.net/downloads/markovo-0.1.0-py3-none-any.whl"
export MARKOVO_BASE_URL="https://markovo.net"
export MARKOVO_API_KEY="mk_live_..."
markovo doctor --json
markovo convert input.pdf --out runs/input --mode fast --max-credits 30
markovo url-convert https://example.com/public-report --out runs/public-report --max-credits 1 --accept-remote-fetch
markovo usage
markovo billing  # returns the secure browser billing URL
markovo-mcp
```

The published client requires a positive `max_credits` for every remote conversion. Customer MCP tool discovery does not expose the developer-only local conversion bypass unless `MARKOVO_ENABLE_LOCAL_TOOLS=1` is explicitly set.