API Reference

Use the Python CLI for normal research workflows. This reference is for clients that integrate directly with Mdtero's stable task API.

Base URL And Authentication

https://api.mdtero.com

Authenticate API calls with an API key created in Mdtero Account:

Authorization: Bearer mdtero_...
Content-Type: application/json

Keep API keys out of shell history, logs, and chat. mdtero setup is the preferred secure sign-in flow.

Task Lifecycle

The public lifecycle is consistent across the CLI, browser extension, dashboard, and direct API clients:

1. Submit a DOI, URL, or permitted local file.
2. Poll the task until it succeeds or needs user action.
3. Download Markdown or a bundle.
4. Optionally translate the Markdown or import it into a project.

Task responses provide a task_id, status, quality information when available, a preferred download, and a user-facing next action on failure. Implementation-specific acquisition and parser details are not part of the public API contract.

Parse A DOI Or URL

POST /api/v1/tasks/parse

POST /api/v1/tasks/parse
Authorization: Bearer mdtero_...
Content-Type: application/json

{"input":"10.48550/arXiv.1706.03762"}

input may be a DOI, arXiv identifier, or article URL. The response contains a task id for polling.

CLI equivalent:

mdtero parse <doi-or-url> --wait --timeout 300 --json

Upload A File

POST /api/v1/tasks/upload

POST /api/v1/tasks/upload
Authorization: Bearer mdtero_...
Content-Type: multipart/form-data

Field	Required	Description
paper_file	yes	PDF, EPUB, HTML, XML, JATS/NXML, or TEI file.
source_doi	no	DOI associated with the file.
source_input	no	Original DOI or URL.
artifact_kind	no	pdf, epub, html, or structured_xml.

Use upload for a saved file, including material obtained through your own browser session or institutional access.

mdtero parse --file <paper.pdf|paper.epub|paper.html|paper.xml> --wait --timeout 600 --json

Check Status And Download

GET /api/v1/tasks/{task_id}

Poll a parse or translation task. Typical states are queued, running, succeeded, and failed.

GET /api/v1/tasks/{task_id}/download/{artifact}

Common artifacts:

Artifact	Content
paper_md	Primary Markdown output.
paper_bundle	Markdown and supporting assets in a ZIP bundle.
translated_md	Markdown produced by a translation task.

mdtero status <task-id> --wait --timeout 300 --json
mdtero download <task-id> paper_md --output-dir ./mdtero-output --json

Discover And Translate

GET /api/v1/discovery/search

Search the Mdtero discovery catalog.

Parameter	Description
query	Required search text.
limit	Result limit.
year_from, year_to	Optional year filters.
open_access_only	Limit results to open-access records.

POST /api/v1/tasks/translate

Translate Markdown stored in a completed task or provide Markdown text directly. Use target_language such as zh-CN; mode is optional and defaults to full. Then poll the returned task and download translated_md.

mdtero translate <parse-task-id> --to zh-CN --wait --timeout 600 --json

Projects And Cited Answers

POST /api/v1/projects

Create a project to organize processed papers.

POST /api/v1/projects/{project_id}/tasks/{task_id}/import

Add the Markdown from a succeeded parse task to a project.

GET /api/v1/projects/{project_id}/rag/status

Check whether a project is ready for questions.

POST /api/v1/projects/{project_id}/rag/build

Build the project index after importing documents.

POST /api/v1/projects/{project_id}/rag/query

Ask a project question:

{"question":"What are the strongest findings?","limit":5}

Use the returned citations when presenting research conclusions. The CLI can manage the complete project flow:

mdtero rag query "What are the strongest findings?" --build-if-needed --json

Errors

HTTP	Meaning	Next step
400 / 422	Invalid or incomplete input.	Correct the request and retry.
401	Sign-in or API key required.	Run mdtero setup or sign in again.
403	The resource belongs to another account, or the source requires your authorization.	Use the right account or upload a file you are permitted to use.
404	Task, project, or artifact was not found.	Check the id and account.
413	File is too large.	Reduce the file size.
429 / 503	Temporary capacity or upstream availability issue.	Wait and retry later.

For local use, prefer the CLI: it handles sign-in, polling, downloads, and clear next actions without exposing implementation details.