API

The HTTP API behind the connector lets you upload documents, read their pages and tables, and delete them.

The base URL is https://api.mdfi.ai, and the server's own OpenAPI reference, with every field, is at https://api.mdfi.ai/docs. The examples below use curl, with your key in $MDFI_API_KEY.

Authentication

Every request sends your API key, which you get on the dashboard's Connect page, as a bearer token:

Authorization: Bearer mdfi_…

Without a valid key the answer is HTTP 401: API key required (no header), Invalid API key format (the key does not start with mdfi_) or Invalid or revoked API key. A valid key whose account has no active plan gets HTTP 402: Subscription required. Choose a plan at …/dashboard/billing.

Documents belong to the account that uploaded them. Another account's document id answers 404, as if it did not exist.

Upload a document

POST /v1/documents takes a form with these fields:

Send the hash first, without the file:

SHA=$(shasum -a 256 report.pdf | cut -d' ' -f1)
curl -s -H "Authorization: Bearer $MDFI_API_KEY" -F sha256=$SHA https://api.mdfi.ai/v1/documents

• 200: your account already has this document. The answer is its current status, with its manifest while it converts or once it is ready (see Read a document). Nothing is charged, and max_tier is ignored.
• 404 upload required: your account does not have it. Send the same request with the file:

curl -s -H "Authorization: Bearer $MDFI_API_KEY" -F sha256=$SHA -F file=@report.pdf https://api.mdfi.ai/v1/documents

• 202: the conversion has started. The answer is {"id": "…", "status": "converting", "source": "report.pdf", "error": null, "manifest": null}. Use the id with the requests below.

Before converting, mdfi checks the upload. A failed check converts nothing and charges nothing:

A conversion that fails is not kept: sending its hash again answers 404 upload required, and uploading the file converts it again. The document is charged once, when its conversion completes.

Read a document

GET /v1/documents/{id} returns the document's status:

curl -s -H "Authorization: Bearer $MDFI_API_KEY" https://api.mdfi.ai/v1/documents/$ID

The manifest:

How it works explains scores and flags, tiers and tables. For example, a ready 3-page report whose third page was re-read by the vision model (a few fields shortened):

{
  "id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
  "status": "ready",
  "source": "report.pdf",
  "error": null,
  "manifest": {
    "page_count": 3,
    "weighted_pages": 7,
    "approx_tokens": 49,
    "pages": [
      {"number": 1, "score": 100.0, "charged_tier": 1, "kept_tier": 1, "flags": [], "state": "ready"},
      {"number": 2, "score": 96.0, "charged_tier": 1, "kept_tier": 1, "flags": [], "state": "ready"},
      {"number": 3, "score": 88.0, "charged_tier": 3, "kept_tier": 3, "flags": ["ocr", "enhanced_tier3"], "state": "ready"}
    ],
    "outline": [
      {"title": "Summary", "level": 1, "start_page": 1, "end_page": 1},
      {"title": "Results", "level": 1, "start_page": 2, "end_page": 3}
    ],
    "warnings": [],
    "tables": [
      {"id": "p2-t1", "start_page": 2, "end_page": 2, "rows": 4, "cols": 3, "uncertain": false, "notes": []}
    ],
    "first_text": "--- page 1 ---\n## Summary\nRevenue grew in every region except the north.\n\n--- page 2 ---\n…",
    "first_text_pages": [1, 2, 3],
    "estimated_seconds_left": null,
    "complete": true
  }
}

While a document converts, PDF, image and PowerPoint pages become ready before the whole document is. The pages of other formats stay converting until it is ready (How it works).

A document mdfi does not have for your account answers 404 Document not found or expired — upload it again with POST /v1/documents: the id is wrong, the document was deleted, or it is older than 7 days.

Read pages

GET /v1/documents/{id}/pages returns the text of some pages. Pass exactly one of:

• range: page numbers and ranges, such as 3,7,9-11;
• section: a title from the outline. A title several entries share is chosen as Parent > Title; the Connector page explains the matching.

curl -s -H "Authorization: Bearer $MDFI_API_KEY" "https://api.mdfi.ai/v1/documents/$ID/pages?range=2-3"
curl -s -G -H "Authorization: Bearer $MDFI_API_KEY" --data-urlencode "section=Results" https://api.mdfi.ai/v1/documents/$ID/pages

The answer lists the pages whose text it holds and the requested pages that are not ready yet (text shortened):

{
  "id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
  "pages": [2, 3],
  "text": "--- page 2 ---\n## Results\n[table p2-t1 — 4 rows × 3 cols]\nRegion\t2024\t2025\n…\n\n--- page 3 ---\nFigures are unaudited.",
  "not_ready": []
}

While the document converts, text holds the requested pages that are ready, and not_ready the rest; ask for those again later. While only the outline exists, every requested page is in not_ready. Reading pages never charges.

Export a table

GET /v1/documents/{id}/tables/{table_id} returns one table, with the id from the manifest's tables or from the table's label in the page text:

curl -s -H "Authorization: Bearer $MDFI_API_KEY" https://api.mdfi.ai/v1/documents/$ID/tables/p2-t1

{
  "id": "p2-t1",
  "start_page": 2,
  "end_page": 2,
  "headers": ["Region", "2024", "2025"],
  "rows": [["North", "12", "11"], ["South", "20", "24"], ["East", "9", "10"], ["West", "15", "17"]],
  "uncertain": false,
  "notes": []
}

A table is returned only once the document is ready, because a page still being converted or re-read can extend it. Exporting never charges.

Delete a document

DELETE /v1/documents/{id} deletes a document at once and answers 204:

curl -s -X DELETE -H "Authorization: Bearer $MDFI_API_KEY" https://api.mdfi.ai/v1/documents/$ID

It removes the document's pages, outline and tables, and the record that recognises the file. Afterwards the id answers 404, and uploading the same file converts and charges it again. An unknown id answers 404 Document not found.

A document deleted while it is still converting is charged for the work already done, and its result is not kept. Data and privacy says what mdfi keeps and for how long.

Error codes

Error answers carry their message in a JSON detail field (for 422, a list of the fields in error). An unexpected 500 may be plain text.

Older endpoints

The server also has the endpoints of mdfi's first API. They convert a whole file, or a web page from a URL, to a single markdown text, without the per-page scores, outline and table ids of /v1/documents:

• POST /convert: converts and answers in the same request.
• POST /jobs, GET /jobs/{id}, GET /jobs, DELETE /jobs/{id}: background conversions, with an optional webhook_url that receives the result.
• POST /batches, GET /batches/{id}, GET /batches, DELETE /batches/{id}: up to 50 files and URLs at once.

On mdfi they read at Tier 1 only, and each conversion counts as one weighted page whatever its size. A request is refused with HTTP 429 when no page is left this month; a batch needs one page per item. Uploads are limited to 100 MB: a larger file answers HTTP 413, File too large (NMB). Maximum is 100MB. (in a batch, File '<name>' too large (NMB). Maximum is 100MB.).

POST /convert waits up to 30 seconds for a free conversion slot. If none frees up, it answers HTTP 503 Server busy converting other documents — use POST /jobs or /v1/documents and poll.

The schema option of these endpoints takes the name of a built-in template and adds the fields it extracts to the result. To do that, it sends the whole converted text to a language model; Data and privacy names the provider. What these endpoints keep, and for how long, is under Older endpoints on the same page.

Use /v1/documents for new work: it is the API the connector uses, and the only one that re-reads poor pages.

Templates (coming soon)

A /v1/templates API is coming soon. Until then, extraction templates are kept on the dashboard (Templates).