Core Endpoints

Docspeed’s public customer contract is intentionally compact:

POST /api/v1/upload
GET /v1/files/{file_id}
GET /v1/files/{file_id}/pages/{page_index}/image
POST /api/v1/parse
POST /v1/layout
POST /v1/ocr
POST /v1/classify
POST /v1/split
POST /v1/tables
POST /v1/equations
POST /v1/charts
POST /v1/schema/auto
POST /v1/extract
POST /api/v1/ask
POST /api/v1/compare
POST /api/v1/synthesize
POST /api/v1/synthesize/one
POST /api/v1/synthesize/set
GET /v1/agents/tools
POST /v1/agents
GET /v1/jobs/{job_id}
GET /v1/jobs/{job_id}/result

Workflow map

| Workflow | Use when | Endpoint | | --- | --- | --- | | Upload | You need a reusable file reference for PDFs or images | POST /api/v1/upload | | File metadata and page images | You need stored file details or a rendered source page | GET /v1/files/{file_id}, GET /v1/files/{file_id}/pages/{page_index}/image | | Parse | You need markdown plus drawable page regions and chunks | POST /api/v1/parse | | OCR and Layout | You need line geometry or ordered page components | POST /v1/ocr, POST /v1/layout | | Classify and Split | You need document/page routing or packet boundaries | POST /v1/classify, POST /v1/split | | Tables, Equations, Charts | You need specialized visual extraction | POST /v1/tables, POST /v1/equations, POST /v1/charts | | Schema Builder | You need a Schema V2 extraction contract | POST /v1/schema/auto | | Extract | You need schema-driven JSON and grounding evidence | POST /v1/extract | | Ask | You need grounded answers over one or more documents | POST /api/v1/ask | | Compare | You need grounded 2-way or 3-way document matching | POST /api/v1/compare | | Synthesize | You need generated test documents or document sets | POST /api/v1/synthesize/one, POST /api/v1/synthesize/set | | Agents | You need the public tool registry or a saved agent definition | GET /v1/agents/tools, POST /v1/agents | | Async Jobs | You submitted async work and need status/results | GET /v1/jobs/{job_id}, GET /v1/jobs/{job_id}/result |

POST /api/v1/upload accepts PDF, PNG, JPEG/JPG, TIFF/TIF, WebP, BMP, and GIF files. The multipart field name is repeated files; the response shape is { "files": [...] }, and each item contains the reusable file_id.

cURL

curl -sS -X POST "https://api.docspeed.ai/api/v1/parse" \
  -H "Authorization: Bearer ${DOCSPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"file_id": "file_123"},
    "execution_mode": "sync",
    "profile": "grounded",
    "grounding": "regions"
  }'

Python

import requests

response = requests.post(
    "https://api.docspeed.ai/api/v1/parse",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "input": {"file_id": "file_123"},
        "execution_mode": "sync",
        "profile": "grounded",
        "grounding": "regions",
    },
    timeout=600,
)
print(response.json())

TypeScript

const response = await fetch("https://api.docspeed.ai/api/v1/parse", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: { file_id: "file_123" },
    execution_mode: "sync",
    profile: "grounded",
    grounding: "regions",
  }),
});

console.log(await response.json());

Example parse response fragment

{
  "doc_id": "doc_123",
  "version": "0.1.0",
  "markdown": "# Invoice\n\nTotal Due: 1240.00",
  "pages": [
    {
      "page_index": 0,
      "width": 1200,
      "height": 1600,
      "image_ref": "/api/v1/files/file_123/pages/0/image"
    }
  ],
  "regions": [
    {
      "region_id": "p1_total",
      "page_index": 0,
      "label": "key_value_lines",
      "display_label": "1. TEXT BLOCK",
      "shape": {"type": "bbox", "x": 80, "y": 320, "w": 420, "h": 80}
    }
  ],
  "chunks": [
    {
      "chunk_id": "p1_total",
      "type": "text",
      "label": "key_value_lines",
      "display_label": "1. TEXT BLOCK",
      "markdown": "Total Due: 1240.00",
      "page_index": 0,
      "region_ids": ["p1_total"],
      "bbox": [80, 320, 500, 400]
    }
  ],
  "metadata": {"doc_class": "invoice", "page_count": 1}
}

Use the generated API Reference for request schemas, response schemas, and per-endpoint behavior.

Deprecated shapes to avoid

Do not use a multipart upload field named file; use repeated files.
Do not read a top-level upload file_id; read files[0].file_id.
Do not call legacy split chat endpoints; the public Ask endpoint is POST /api/v1/ask.
Agent tool discovery is GET /v1/agents/tools.