# Markovo

Markovo turns files into clean Markdown and a traceable artifact bundle. PDF to Markdown is the first available capability. Do not claim that DOCX, PPTX, spreadsheets, images, audio, or other formats are available until `GET /v1/capabilities` reports them as available.

Canonical origin: https://markovo.net

Public surfaces:
- Converter: `/`
- Pricing: `/pricing`
- Developer documentation: `/docs`
- 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 PDF to `POST /v1/estimates` as multipart `file` with optional `mode=fast|accurate`.
2. Read `pages_estimated`, `estimated_credits`, `estimated_runtime_seconds`, `upload_id`, and (for anonymous jobs) `job_token`.
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.

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.
- Existing `PDF2MD_BASE_URL`, `PDF2MD_API_KEY`, CLI commands, MCP tools, and `pdf2md:*` scopes remain compatibility aliases.
- New API keys use the `mk_live_` prefix and `markovo:convert` scope.

Example:
```bash
export PDF2MD_BASE_URL="https://markovo.net"
export PDF2MD_API_KEY="mk_live_..."

curl -X POST "${PDF2MD_BASE_URL}/v1/convert" \
  -H "Authorization: Bearer ${PDF2MD_API_KEY}" \
  -F "file=@input.pdf" \
  -F "mode=fast" \
  -F "max_credits=30"

curl "${PDF2MD_BASE_URL}/v1/jobs/{job_id}" \
  -H "Authorization: Bearer ${PDF2MD_API_KEY}"

curl -L "${PDF2MD_BASE_URL}/v1/jobs/{job_id}/download?format=zip" \
  -H "Authorization: Bearer ${PDF2MD_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 each calendar month, 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/month.
- Plus: $8/month, 2,000 Credits; one month of rollover, balance capped at 4,000.
- Pro: $19/month, 6,000 Credits; one month of rollover, balance capped at 12,000; API keys, two concurrent jobs, and webhooks.
- Business: $49/month, 15,000 Credits; displayed as a waitlist and not self-serve.
- Enterprise: contact sales.
- Credit packs: 2,000/$10, 12,000/$49, 60,000/$199; valid for 365 days.
- 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, DOCX, PPTX: 1 Credit/page.
- OCR or complex structure: 3 Credits/page or image.
- AI enhancement and chart description: 5 Credits/page.
- XLSX/CSV: 1 Credit per 2,000 non-empty cells.
- HTML/TXT/EPUB: 1 Credit per 1,000 words.
- Minimum: 1 Credit/file.
- The server catalog is authoritative; never trust a client-supplied price or grant amount.

Authentication:
- Same-origin Better Auth endpoint: `/api/auth/*`.
- Google callback: `https://markovo.net/api/auth/callback/google`.
- GitHub callback: `https://markovo.net/api/auth/callback/github`.
- Email verification and password reset use Resend from `auth@markovo.net` after the production API key and domain verification are configured.

Quota errors:
- HTTP 402/429 with `error.code=quota_exceeded` can include `action=open_checkout`, `checkout_url`, `required_units`, and `remaining_units`.
- Open the returned checkout URL, then retry only after Credits are available.

CLI and MCP compatibility:
```bash
pdf2md doctor --json
pdf2md convert input.pdf --out runs/input --mode fast
pdf2md usage
pdf2md billing
pdf2md-mcp
```

Treat production availability as unverified until the deployment checklist confirms the domain, three real login methods, a successful conversion/download, and Creem Sandbox webhook idempotency.