Developer quickstart / REST API

Put document structure inside your product.

One authenticated endpoint turns the files your users already have into clean Markdown for retrieval and structured DocIR JSON for layout-aware product workflows.

Create a free API key Run the first request

Trial includes 20 text-based documents, 200 MB total, and a 20 MB per-file limit. Model-backed image, Fast AI, and Layout-aware modes require an approved paid workspace.

InputMixed documentsPDF, scans, images, Office, HTML, XML, and CSV through one API.
OutputMarkdown + DocIRReadable content and typed blocks, pages, boxes, order, and provenance.
PathInline → asyncPrototype synchronously; add queues, result polling, and webhooks when needed.
01 / First request

Three steps from account to usable output.

No connector setup and no SDK required. Create a scoped secret, send a multipart upload from your backend, and take the output your product needs.

01

Create the key

Create a workspace, open Workspace, and generate a key with parse and read scopes. The secret is shown once.

02

Store it server-side

Set DOCPARSE_API_KEY in your backend environment. Never commit it or expose it in browser code.

03

Send the document

Use ?wait=true for a complete inline response while you prototype.

cURL · synchronous parse
export DOCPARSE_URL="https://docparse.genedai.me"
export DOCPARSE_API_KEY="your_key"

curl -fsS -X POST \
  "$DOCPARSE_URL/v1/parse?wait=true" \
  -H "Authorization: Bearer $DOCPARSE_API_KEY" \
  -F "file=@document.pdf" \
  -F "mode=both" \
  -o result.json

jq -r '.result.markdown' result.json
result.markdownReadable content for chunking, search, and model context.
result.documentDocIR pages and typed blocks for layout-aware logic.
result.manifestRoute, parser versions, warnings, and artifact lineage.
02 / Backend examples

Use the HTTP client already in your stack.

These examples call the REST API directly. They do not depend on a DocParse SDK, so the integration stays explicit and portable.

JavaScript

Node.js 20+ · native fetch

import fs from "node:fs";

const file = await fs.openAsBlob("document.pdf");
const form = new FormData();
form.set("file", file, "document.pdf");
form.set("mode", "both");

const response = await fetch(
  process.env.DOCPARSE_URL +
    "/v1/parse?wait=true",
  {
    method: "POST",
    headers: {
      Authorization:
        "Bearer " + process.env.DOCPARSE_API_KEY
    },
    body: form
  }
);

if (!response.ok) {
  throw new Error(await response.text());
}

const { result } = await response.json();
console.log(result.markdown);

Python

requests · multipart upload

import os
import requests

url = (
    os.environ["DOCPARSE_URL"]
    + "/v1/parse?wait=true"
)
headers = {
    "Authorization": "Bearer "
    + os.environ["DOCPARSE_API_KEY"]
}

with open("document.pdf", "rb") as file:
    response = requests.post(
        url,
        headers=headers,
        files={
            "file": (
                "document.pdf",
                file,
                "application/pdf",
            )
        },
        data={"mode": "both"},
    )

response.raise_for_status()
result = response.json()["result"]
print(result["markdown"])
03 / Production path

Start with one call. Add operational control when it earns its keep.

The request body stays the same. Choose inline or async delivery based on latency, document complexity, and how your product handles background work.

Inline · ?wait=true

Best for the first integration.

The response contains the completed job and all three result artifacts.

  • Prototype and validate output against your own files.
  • Use the returned Markdown immediately in search or RAG.
  • Inspect DocIR and manifest before designing downstream logic.
Async · default

Best for background workloads.

A 202 response returns a job and result link while processing continues.

  • Poll links.result or provide x-webhook-url.
  • Add Idempotency-Key when callers may retry uploads.
  • Use scoped keys, cancellation, lifecycle events, and purge controls.
04 / Request contract

Three input styles. One result contract.

Choose the transport that matches where your file already lives. Trial uploads accept files up to 20 MB; approved paid workspaces accept up to 100 MB. HTTPS imports use tenant allowlists and tighter fetch limits.

multipart/form-data

Upload a file

Use the file field with optional mode and parsing options. This is the simplest default.

application/octet-stream

Stream raw bytes

Send the file body with x-filename and the correct content type.

application/json

Import an HTTPS URL

Pass a permitted URL, name, MIME type, options, and optional webhook URL.

StatusWhat it means
200The inline parse completed, or a completed result was returned.
202The job is queued, running, or retrying. Follow the returned links.
403The workspace or API key is not allowed to use the requested capability. Trial keys cannot request model-backed modes.
409An idempotency key conflicts with a different request, or the requested job was canceled.
422The parser reached a terminal failure. Read the job errors and lifecycle events.
429A tenant quota, concurrency limit, or daily AI capacity boundary was reached. Retry after the returned delay or use deterministic parsing.
Open the OpenAPI 3.1 schema Check service health

Prove the output before rebuilding your ingest layer.

Parse your own files in the console, then create a scoped key and send the same workload through the API.

Create free workspace 20 documents · 200 MB
Deterministic parsing · no payment card