API Integration Guide

1. Authentication

All production requests require an API key that belongs to your Mdtero account. Generate one in your Dashboard.

For local development, you can skip the API key and pass your Elsevier developer key directly.

# Set your Mdtero API key (production)
export MDTERO_API_KEY="mdt_live_..."

# —or— set your Elsevier key (local dev)
export ELSEVIER_API_KEY="your_elsevier_key"

2. Base URL

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

3. Parse a Paper (Async)

Initiate parsing of an Elsevier DOI with POST /tasks/parse.

curl -X POST https://api.mdtero.com/tasks/parse \
  -H "ApiKey: $MDTERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "https://doi.org/10.1016/j.enconman.2026.121230"}'

Response: A JSON object containing a task_id. Parsing is asynchronous — poll for results.

4. Check Task Status & Get Results

Poll GET /tasks/{task_id} until the status is "succeeded".

curl https://api.mdtero.com/tasks/<TASK_ID> \
  -H "ApiKey: $MDTERO_API_KEY"

The result object will contain metadata and URLs to generated assets: Markdown, ZIP Bundle, XML, and Images.

5. Downloading Raw Assets & Images

Fetch images locally for your AI agents to read visual context. Pass your ApiKey header to the proxy endpoint URLs from the task result.

# Download an image from the task result
curl -H "ApiKey: $MDTERO_API_KEY" \
  -o figure1.jpg \
  https://api.mdtero.com/api/v1/downloads/.../image.jpg