Connect Markovo.

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.

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"

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_API_KEY="mk_live_..."
export MARKOVO_MCP_ROOT="/path/to/dedicated/project"

python -m pip install --force-reinstall "https://markovo.net/downloads/markovo-0.1.1-py3-none-any.whl#sha256=3cd6979c5d31235b78e46f6f5efa55a372f7fe6ecdad27c92c5bdb65e7898414"
	markovo doctor --json
	markovo convert paper.pdf --out runs/paper --mode fast --max-credits 30
	markovo usage

{
  "mcpServers": {
    "markovo": {
      "command": "markovo-mcp",
      "env": {
        "MARKOVO_API_KEY": "${MARKOVO_API_KEY}",
        "MARKOVO_MCP_ROOT": "/path/to/dedicated/project"
      }
    }
  }
}

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

Convert a public link

Use JSON for public links. Supported sources include public HTML/text pages, public Google Docs, Notion pages and bounded databases, GitHub text resources and discussions, Hacker News threads, and downloadable YouTube videos. Private or login-only sources, Tencent Docs account connections, browser-only pages, binary downloads, and remote image downloads are not supported. These HTTP examples use ordinary libraries; no Markovo SDK is required.

curl -X POST https://markovo.net/v1/url-estimates \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/","accept_remote_fetch":true}'

Read the estimate, then replace upl_RETURNED_UPLOAD_ID with its upload_id. Confirm only when estimated_credit_units is within your chosen ceiling; 15,000 units equal 15 Credits. Poll and download the returned job as above.

curl -X POST https://markovo.net/v1/jobs \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_RETURNED_UPLOAD_ID","max_credit_units":15000}'

Ordinary public documents use the URL rate based on measured fetch time and extracted words. YouTube uses audio transcription at 0.5 Credits per decoded minute, with a 0.3-Credit minimum, rather than the URL word rate. A video must be downloadable without login, be at most one hour, and fit within the 32 MB acquired-audio limit and your account's upload limit. Captions are not required; frames are not analyzed. Check speech-recognition output against the recording.

In the Web converter, guests may Fetch and preview within the 5-Credit guest limit; downloading requires sign-in and settlement from account Credits. An anonymous URL estimate returns job_token: the Web flow submits {"estimates":[{"upload_id":"…","job_token":"…"}]} to POST /v1/guest-preview-sessions, preserves the returned session token for claim after sign-in, and uses x-markovo-job-token for job status and preview. This is a preview allowance, not free downloadable Credits. API-key, CLI, and MCP examples use authenticated account conversion.

Formula-dense PDFs

Formula-dense PDFs run through the standard conversion pipeline, which routes scanned and complex pages to the Markovo OCR engine that renders equations as reviewable LaTeX. The legacy layout_fidelity=formula option is still accepted for API compatibility and is handled as standard conversion at the normal page rate — no separate formula charge applies. Compare every equation with the original PDF because symbol, variable, root, subscript, or superscript errors remain possible.

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.

Product API client. The public CLI is pinned to https://markovo.net, loads MARKOVO_API_KEY only from the environment, then polls and downloads the result bundle.

python -m pip install --force-reinstall "https://markovo.net/downloads/markovo-0.1.1-py3-none-any.whl#sha256=3cd6979c5d31235b78e46f6f5efa55a372f7fe6ecdad27c92c5bdb65e7898414"
	export MARKOVO_API_KEY="mk_live_..."

markovo convert paper.pdf --out runs/paper --mode fast --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. If --max-credits is omitted, CLI uses a 15-Credit convenience safety ceiling. Markovo obtains an estimate internally before job creation and rejects work estimated above that ceiling; the client does not pause for user confirmation. Set an explicit bound for deliberate automation. Formula-dense PDFs render equations through the standard pipeline; compare every equation with the original PDF.

For a supported public link, use url-convert with explicit fetch consent and a Credit ceiling. It uses the same source limits and server estimate as the Web and API flows, then polls and downloads without pausing for confirmation.

markovo url-convert https://example.com/ \
  --out runs/public-page --max-credits 15 --accept-remote-fetch

Install the verified website build with the command above. Its SHA-256 fragment makes pip check the downloaded file, and --force-reinstall replaces an older build even when the version number matches. Verify the current filename and SHA-256 in the client manifest before managed deployment.

Remote MCP with OAuth

Add https://markovo.net/mcp to an MCP client that supports Streamable HTTP and OAuth. The client discovers Markovo's OAuth 2.1 endpoints, opens the normal account sign-in and an explicit consent screen, and receives only the approved markovo:read and markovo:convert scopes. You do not create or paste an API key for this connection.

The remote server exposes nine focused tools for capabilities, Credit usage, owned jobs, public-HTTPS URL conversion, verified result images, short-lived asset links, and billing help. It has no local-file, arbitrary network, shell, credential, payment, or administrator tool. Every URL conversion requires a positive max_credit_units ceiling. Markovo never tops up Credits, opens Checkout, or changes a plan automatically; low-balance responses point the account owner to Billing. Read the copy-ready Remote MCP guide.

Remote MCP URL: https://markovo.net/mcp
Transport: Streamable HTTP
Authentication: OAuth 2.1 Authorization Code + PKCE

Remote markovo_convert_url takes {"url":"https://example.com/","max_credit_units":15000}. Calling it authorizes fetching that public link. It uses the same source limits and YouTube audio pricing described above; it cannot read a file on your computer.

Local stdio MCP

The customer-only MCP package exposes exactly the following account-metered tools over stdio. It contains no local conversion engine. When max_credits is omitted, it uses the same 15-Credit convenience safety ceiling. Markovo obtains an estimate internally before job creation and rejects work estimated above that ceiling; the client does not pause for user confirmation. Set an explicit bound for deliberate automation. REST and direct clients remain explicit.

For URL conversion over stdio, markovo_convert_url takes url, an out_dir inside MARKOVO_MCP_ROOT, accept_remote_fetch: true, and max_credits in Credits. Unlike remote MCP's integer max_credit_units, max_credits: 15 means a 15-Credit ceiling.

• markovo_convert
• markovo_convert_url
• markovo_job_status
• markovo_job_assets
• markovo_asset_url
• markovo_asset_revoke
• markovo_usage
• markovo_capabilities
• markovo_billing
• markovo_bundle_verify
• markovo_doctor

markovo_convert reads and writes local filesystem paths only inside the required MARKOVO_MCP_ROOT. Missing roots, parent-directory escapes, absolute paths outside the root, and symlink escapes fail closed. If an agent has no mounted disk or cannot expose the file inside that dedicated root, use REST multipart upload instead. API keys and the service origin are never MCP tool arguments. For Word, keep the runtime capability ID explicit:

{
  "input_path": "/absolute/path/report.docx",
  "out_dir": "/absolute/path/runs/report",
  "capability_id": "docx-to-markdown",
  "max_credits": 10
}

Asset grant URLs are bearer capabilities that last 60–600 seconds. An expired or revoked grant URL returns not found; request a new grant only while the owned job and asset still exist, and never persist the URL.

python -m pip install --force-reinstall "https://markovo.net/downloads/markovo-0.1.1-py3-none-any.whl#sha256=3cd6979c5d31235b78e46f6f5efa55a372f7fe6ecdad27c92c5bdb65e7898414"
	export MARKOVO_API_KEY="mk_live_..."
	export MARKOVO_MCP_ROOT="/path/to/dedicated/project"
	markovo-mcp
	# or: markovo mcp

{
  "mcpServers": {
    "markovo": {
      "command": "markovo-mcp",
      "env": {
        "MARKOVO_API_KEY": "${MARKOVO_API_KEY}",
        "MARKOVO_MCP_ROOT": "/path/to/dedicated/project"
      }
    }
  }
}

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 require a signed-in account. API, CLI, and MCP conversion requires authentication; supported Web inputs may use a bounded guest preview, with sign-in and account settlement before download. They use the same Credits, ownership, History, API, CLI, MCP, and artifact contract. Other formats remain Planned until their quality and cost gates pass.

• Anonymous users can preview one ordered queue per UTC day, with the Free account file boundary of 25 MB and 25 source units per file. The continuous prefix is capped at 5 estimated Credits, and Download requires account settlement.
• Signed-in Free users receive 25 Credits per UTC calendar month, one active API key, and 5 conversions per UTC day, one file at a time, with 25 MB and 25 pages per file.
• Starter is $3.99/month with 200 Credits, API keys and batches up to 20 files, with 50 MB / 200 pages per file. Paid use continues while Credits remain; short traffic bursts are rate limited for platform safety.
• Pro is $7.99/month with 500 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; Starter after 7 days; Pro after 30 days. Source files are deleted after processing.
• Jobs estimated above 12 minutes are rejected before processing.

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.