Developer API

Mdtero API for scripts and product integrations

Use the API when Mdtero needs to plug into your own scripts, automations, or product workflows.

Programmatic access

Programmatic access for your own tools.

Best for

Internal research tools, batch pipelines, and product surfaces that need clean paper outputs on demand.

API snapshot

At a glance

API snapshot

At a glance

Use an Mdtero API key for requests and keep licensed retrieval on your own machine.
The local helper is the default path for DOI, URL, and file-based intake.
Parse and translation tasks both return task IDs for polling and downloads.
This page covers auth, helper install, task flow, artifact download, and optional agent handoff.

2. Base URL

Production: https://api.mdtero.com
Auth header: Authorization: ApiKey $MDTERO_API_KEY

API snapshot

At a glance

Use an Mdtero API key for requests and keep licensed retrieval on your own machine.
The local helper is the default path for DOI, URL, and file-based intake.
Parse and translation tasks both return task IDs for polling and downloads.
This page covers auth, helper install, task flow, artifact download, and optional agent handoff.

Contents

Support

Need help with keys, helper setup, or downloads? Contact support@mdtero.com.

Supported sources

What works best today

When needed, keep retrieval on your own machine first, then use the API for parsing and downloads.

Works best

arXiv, PMC / Europe PMC, bioRxiv / medRxiv, PLOS, Springer Open Access, and Elsevier when you have access on your own machine.

May need local browser capture

Some publisher pages, including Springer subscription pages, may ask you to finish capture locally in Chrome or Edge before parsing.

Fallback inputs

If structured full text is not available, you can still continue from a local PDF, EPUB, or another file captured on your machine.

API guide

Reference and setup flow

Keep the full API path in one place: authenticate, install the helper, submit tasks, poll status, and download the artifacts your workflow needs.

1. Authentication

All production requests need an API key from your Mdtero account.

For licensed publisher content such as Elsevier and ScienceDirect, keep retrieval on your own machine with the local helper. Use the browser extension only when a live page must be captured in a browser session.

Open Account

2. Base URL

Production: https://api.mdtero.com
Auth header: Authorization: ApiKey $MDTERO_API_KEY

3. Install the local helper

The normal setup is simple: download the installer, review it locally, then run it. It exposes a runnable mdtero command so DOI, URL, and file-based parsing can start from your own machine, and use the browser extension only when a supported live page requires browser capture.

4. Parse a paper

Use the local helper first for DOI or URL inputs so retrieval stays on your own machine. The helper-first production routes are POST /tasks/parse-fulltext-v2 and POST /tasks/parse-helper-bundle-v2. If you already have a file, captured page, or local helper output, you can continue from that too. Keep direct POST /tasks/parse for already-clean inputs, scripts or automations, and other convenience cases rather than the default long-term path.

Response: the API returns a JSON object with task_id. The local helper may wait briefly and print the completed task payload when parsing finishes quickly.

Note: if the API says local capture is required, finish that step on your own machine first with the helper or Edge extension, then retry from the resulting file or captured output.

5. Translate a parsed Markdown file

Use POST /tasks/translate with the server-side Markdown artifact path returned by a succeeded parse task in result.artifacts.paper_md.path.

Response: the public API returns a JSON object with task_id. The local helper may short-wait and print a completed translation payload when the task finishes quickly.

6. Check task status

Poll GET /tasks/{task_id} until the task becomes succeeded.

The result object returns artifact metadata. Download file contents from the download route. If the helper already returned a completed payload, you can skip this step.

7. Download artifacts

Parse tasks return paper_md by default, plus optional paper_pdf or paper_xml. If inline images cannot be served reliably, the task can also expose paper_bundle as a fallback ZIP. Translation tasks return translated_md.

8. Optional agent handoff

If your coding agent should own the setup, generate a key-bound message in Account and paste it there. Keep this as an optional convenience, not the default path.

9. Pricing

Most researchers can stay on plans: monthly parsing and translation quota already cover the common workflow.

Translation add-on pricing follows your active region. Each pack adds 18 translations.

API pay-as-you-go stays available for product integrations and automation: $0.015 per parse and $0.12 per translation.

10. Public client repository

If you need the installable helper, extension, or public setup references, use the single public repository. Frontend and backend implementation repos are not part of the normal API entry path.

Open doi2md repo