API reference

Build a pipeline once in the visual builder, then call it programmatically by id. Every API run produces the same full Trace you see in the app — per-step changes, warnings, provenance, duration. Nothing hidden.

Base URL https://markdown4ai.com/api

Authentication

All requests authenticate with an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer <your-api-key>

Generate keys in the app under Settings → developer. Each key is shown once at creation and stored only as a hash; keys are scoped to your account’s data and can be revoked at any time. A key works only on these /v1 endpoints — it can never read or change account settings. Never expose a key in client-side code.

Endpoints

GET /v1/pipelines

List your saved pipelines.

Returns every pipeline you own, so a client can discover the id it needs to run. Scoped to the caller — you only ever see your own pipelines.

Example response

[
  {
    "id": "8f14e45fceea167a",
    "name": "Standard conversion",
    "steps": [
      { "kind": "parse.builtin", "config": {} },
      { "kind": "structure.lists", "config": {} },
      { "kind": "clean.passes", "config": {} },
      { "kind": "export.markdown", "config": {} }
    ],
    "created_at": "2026-01-15T09:24:00+00:00",
    "updated_at": "2026-01-15T09:24:00+00:00"
  }
]

POST /v1/pipelines/{pipeline_id}/run

Run a saved pipeline against a document (PDF, EPUB, HTML, TXT/LOG, or CSV).

Uploads a document (PDF, EPUB, HTML, TXT/LOG, or CSV), runs it through the saved pipeline, records the full Trace, and returns the rendered output. The run is priced per page (one EPUB chapter, 60 lines of plain text, 50 CSV rows, or 4,000 characters of HTML text count as one page) and charged before processing — an empty balance answers 402 and costs nothing. Fetch the complete per-step Trace from GET /v1/runs/{run_id}.

parameter	in	type	notes
`pipeline_id`	path	string	Id of a pipeline you own (from GET /v1/pipelines). required
`file`	form (multipart)	file	The document to process (PDF, EPUB, HTML, TXT/LOG, or CSV). Max 100 MB. required

Example response

{
  "run_id": "3c59dc048e885024",
  "markdown": "# Sample Title\n\nHello world.\n",
  "warnings": []
}

GET /v1/runs/{run_id}

Fetch a run's full Trace.

Returns the complete, per-step Trace: each step's config, change log, warnings, duration, and document snapshot — exactly what the app's run view shows. The Trace is owned by your account; another tenant's run id answers 404.

parameter	in	type	notes
`run_id`	path	string	Id returned in the run response. required

Example response (abbreviated)

{
  "id": "3c59dc048e885024",
  "source_name": "document.pdf",
  "created_at": "2026-01-15T09:24:31+00:00",
  "trace": {
    "steps": [
      {
        "position": 0,
        "kind": "parse.builtin",
        "config": {},
        "changes": [],
        "warnings": [],
        "duration_ms": 41.2,
        "rendered": null
      },
      {
        "position": 1,
        "kind": "export.markdown",
        "config": {},
        "changes": [],
        "warnings": [],
        "duration_ms": 3.6,
        "rendered": "# Sample Title\n\nHello world.\n"
      }
    ],
    "rendered": "# Sample Title\n\nHello world.\n"
  }
}

Errors

Errors return a JSON body {"detail": "…"} with a user-facing message. Failures are fail-secure — no stack traces, no document content, no internal details.

status	meaning
`400`	Bad request — unsupported file type, empty file, or an invalid pipeline step.
`401`	Not authenticated — sign in or supply a valid API key.
`402`	Out of credits — this document costs more than your current balance.
`404`	Not found — no pipeline or run with that id that you own.
`413`	Payload too large — the file exceeds the 100 MB maximum.
`422`	Unprocessable — the document could not be read (corrupt or password-protected).

Build a pipeline in the visual builder, then run it via the API — same Trace, same provenance, headlessly.

GET /v1/pipelines

              
              curl "https://markdown4ai.com/api/v1/pipelines" \
  -H "Authorization: Bearer $M4AI_API_KEY"
              curl -X POST \
  "https://markdown4ai.com/api/v1/pipelines/YOUR_PIPELINE_ID/run" \
  -H "Authorization: Bearer $M4AI_API_KEY" \
  -F "file=@document.pdf"
              curl \
  "https://markdown4ai.com/api/v1/runs/YOUR_RUN_ID" \
  -H "Authorization: Bearer $M4AI_API_KEY"
              
              import os, requests

headers = {"Authorization": f"Bearer {os.environ['M4AI_API_KEY']}"}

resp = requests.get(
    "https://markdown4ai.com/api/v1/pipelines",
    headers=headers,
)
resp.raise_for_status()
pipelines = resp.json()
pipeline_id = pipelines[0]["id"]
print(pipeline_id)
              import os, requests

headers = {"Authorization": f"Bearer {os.environ['M4AI_API_KEY']}"}

with open("document.pdf", "rb") as pdf:
    resp = requests.post(
        f"https://markdown4ai.com/api/v1/pipelines/{pipeline_id}/run",
        headers=headers,
        files={"file": pdf},
    )
resp.raise_for_status()
run = resp.json()
print(run["run_id"])
print(run["markdown"])
              import os, requests

headers = {"Authorization": f"Bearer {os.environ['M4AI_API_KEY']}"}

resp = requests.get(
    f"https://markdown4ai.com/api/v1/runs/{run_id}",
    headers=headers,
)
resp.raise_for_status()
trace = resp.json()["trace"]
for step in trace["steps"]:
    print(step["kind"], step["duration_ms"], "ms")
              
              const base = "https://markdown4ai.com/api";
const headers = { Authorization: `Bearer ${process.env.M4AI_API_KEY}` };

const resp = await fetch(`${base}/v1/pipelines`, { headers });
if (!resp.ok) throw new Error(await resp.text());
const pipelines = await resp.json();
const pipelineId = pipelines[0].id;
              const form = new FormData();
form.append("file", fileInput.files[0]);

const resp = await fetch(
  `${base}/v1/pipelines/${pipelineId}/run`,
  { method: "POST", headers, body: form }
);
if (!resp.ok) throw new Error(await resp.text());
const { run_id, markdown } = await resp.json();
console.log(run_id, markdown);
              const resp = await fetch(
  `${base}/v1/runs/${runId}`,
  { headers }
);
if (!resp.ok) throw new Error(await resp.text());
const { trace } = await resp.json();
trace.steps.forEach(s =>
  console.log(s.kind, s.duration_ms, "ms")
);
            