API, CLI, and MCP docs.

Match the interface to the operator.

From browser trial to production call.

1. Try a fileUse the homepage uploader to confirm output quality.
2. Create an accountSign in with Google, GitHub, or a verified email address.
3. Use your plan limitFree starts with one API key; paid plans add capacity, batches, concurrency, and retention.
4. Generate a keyCopy the key once and store it in your server environment.
5. Open Developer SetupUse the account app snippets for API, CLI, and MCP configuration.
6. Install clientsInstall the verified, immutable Markovo client commit when CLI or MCP should upload local files through the product API.
7. AutomateCall API, CLI, or MCP depending on who operates the workflow.

Set MARKOVO_API_KEY, then upload.

Keep production keys in server or agent secrets. Never place API keys in browser code.

export MARKOVO_API_KEY="mk_live_..."

curl -X POST https://markovo.net/v1/convert \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -F "file=@paper.pdf" \
  -F "file=@appendix.pdf" \
  -F "mode=fast" \
  -F "max_credits=30"

Copy-ready Developer Setup.

The account app shows the same snippets after sign-in. The CLI and MCP package requires Python 3.10 or newer. Replace placeholders with your API key and keep secrets in backend or agent environments.

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

python -m pip install "https://markovo.net/downloads/markovo-0.1.0-py3-none-any.whl"
	markovo doctor --json
	markovo convert paper.pdf --out runs/paper --mode fast --max-credits 30
	markovo usage

{
  "mcpServers": {
    "markovo": {
      "command": "markovo-mcp",
      "env": {
        "MARKOVO_BASE_URL": "https://markovo.net",
        "MARKOVO_API_KEY": "${MARKOVO_API_KEY}"
      }
    }
  }
}

Upload, poll, download.

Use multipart upload for one or more supported files, then poll each returned job until it succeeds. Put API keys in backend environments, not browser code.

curl -X POST https://markovo.net/v1/convert \
  -H "Authorization: Bearer mk_live_..." \
  -F "file=@paper.pdf" \
  -F "file=@appendix.pdf" \
  -F "capability_id=pdf-to-markdown" \
  -F "mode=fast" \
  -F "max_credits=30"

The response includes jobs[]. For backwards compatibility, job_id points to the first queued job.

curl https://markovo.net/v1/jobs/{job_id} \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}"

curl -L "https://markovo.net/v1/jobs/{job_id}/download?format=md" \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -o output.md

Recommended formula enhancement for PDFs

Selecting a PDF turns Formula enhancement on by default, including in PDF batches. Markovo first checks for formula regions: if none are found, it uses standard conversion and adds 0 formula Credits; if regions are found, the estimate shows the region count and price before conversion starts. REST, CLI, and MCP callers opt in with layout_fidelity=formula. The normal PDF charge remains and each detected region adds 700 credit_units (0.7 Credit). Compare every equation with the original PDF because symbol, variable, root, subscript, or superscript errors remain possible. Guests see the toggle on by default but convert with standard settings until they sign in.

curl -X POST https://markovo.net/v1/estimates \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -F "file=@equations.pdf" \
  -F "capability_id=pdf-to-markdown" \
  -F "layout_fidelity=formula"

Use account API keys for production.

Create a key inside the account app after signing in. Plaintext is shown once.

• Header: Authorization: Bearer mk_live_...
• Scope: markovo:convert
• Usage is settled against the single conversion.credits balance.
• Login capability: GET /v1/account/auth/providers reports enabled OAuth providers and email-code signup state.

Remote conversion with account quota.

Product API client. The CLI uploads through MARKOVO_BASE_URL with MARKOVO_API_KEY, then polls and downloads the result bundle.

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 convert paper.pdf --out runs/paper --mode fast --max-credits 30
	markovo convert equations.pdf --out runs/equations --layout-fidelity formula --max-credits 30
	markovo usage
	markovo billing  # returns the secure browser billing URL

Customer workflows use the account-metered markovo convert command, so browser, API, CLI, and MCP activity appears in the same history. CLI and MCP callers must explicitly choose layout_fidelity=formula. Detected formula regions render as LaTeX; compare every equation with the original PDF.

Verify the current filename and SHA-256 in the client manifest before managed deployment.

Agent-callable account tools.

The customer-only MCP package exposes account-metered remote conversion, job status, usage, a secure billing link, and service/API-key diagnostics over stdio. It contains no local conversion engine. Every conversion tool call requires max_credits. PDF callers may explicitly set layout_fidelity to formula; the same 0.7-Credit region price and review warning apply.

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-mcp
	# or: markovo mcp

{
  "mcpServers": {
    "markovo": {
      "command": "markovo-mcp",
      "env": {
        "MARKOVO_BASE_URL": "https://markovo.net",
        "MARKOVO_API_KEY": "${MARKOVO_API_KEY}"
      }
    }
  }
}

One artifact contract, more formats over time.

PDF is live. Public HTTPS URL import, DOCX, PPTX, XLSX, TXT, Markdown, JSON, XML, HTML, CSV, PNG, JPEG, WebP, TIFF, BMP, EPUB, Notion Export ZIP, supported audio, and supported video are authenticated Beta capabilities. They use the same Credits, ownership, History, API, CLI, MCP, and artifact contract. Other formats remain Planned until their quality and cost gates pass.

What is usable now.

Plans control file, page, OCR, and mode access.

• Anonymous users get 1 conversion per UTC day, with 10 MB and 10 pages per file.
• Signed-in Free users receive 100 Credits per UTC calendar month, one active API key, and 5 conversions per UTC day, one file at a time, with 25 MB and 50 pages per file.
• Plus is $8/month with 2,000 Credits, API keys and batches up to 20 files, with 50 MB / 500 pages per file. Paid use continues while Credits remain; short traffic bursts are rate limited for platform safety.
• Pro is $19/month with 6,000 Credits, API keys, two concurrent jobs, and batches up to 50 files, with 50 MB / 500 pages per file. There is no fixed daily conversion count.
• Credit packs add to the current account and expire after 365 days. They do not change the tier's batch or concurrency limits; while an unexpired purchased balance remains, there is no fixed daily conversion count.
• Subscriptions use conversion.credits, roll over at most one month, and cap the balance at twice the monthly grant.
• Anonymous and Free results expire after one hour; Plus after 7 days; Pro after 30 days. Source files are deleted after processing.
• Jobs estimated above 12 minutes are rejected before processing.

Errors are structured for safe retries.

Public API errors include a stable code, a human-readable message, a per-response request_id, a retryable boolean, and a documentation URL. The same request ID is returned in the x-request-id response header.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Not enough credits.",
    "request_id": "…",
    "retryable": false,
    "docs_url": "https://markovo.net/docs#errors"
  }
}

Retry only when retryable is true. For quota, ownership, validation, or Credit-ceiling errors, follow the returned action or fix the request instead of looping.