API Quickstart

Parse your first document with the DocLD API in minutes.

Prerequisites

Create a DocLD account — Sign up for free
Get your API key — Go to Settings → API Keys and create an API key
Set your base URL — Use your deployment URL (e.g., https://your-app.vercel.app)

Parse Your First Document

Option 1: Direct parse (simplest)

Send a file directly to the parse endpoint. DocLD processes it and returns structured JSON with text, tables, and bounding boxes.


curl -X POST "https://your-domain.com/api/parse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"

Replace:

your-domain.com with your deployment URL
YOUR_API_KEY with your API key
document.pdf with your file path

Option 2: Upload, then parse

For workflows where you upload first and parse later, use the upload endpoint and then pass the returned file_id to parse.

Step 1 — Upload:


curl -X POST "https://your-domain.com/api/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"

The response includes a file_id (e.g. docld://abc123).

Step 2 — Parse using the file reference:


curl -X POST "https://your-domain.com/api/parse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "docld://YOUR_DOCUMENT_ID"}'

Replace YOUR_DOCUMENT_ID with the document ID from the upload response.

Option 3: Parse from URL

Parse a document directly from a URL:


curl -X POST "https://your-domain.com/api/parse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "https://example.com/document.pdf"}'

Response

A successful parse returns JSON:


{
  "job_id": "uuid",
  "duration": 2.5,
  "usage": {
    "num_pages": 5,
    "credits": 7.5
  },
  "result": {
    "type": "full",
    "chunks": [
      {
        "content": "# Document Title\n\nDocument content...",
        "page": 1,
        "metadata": {
          "type": "text",
          "confidence": 0.98
        }
      }
    ]
  },
  "studio_link": "https://your-domain.com/documents/abc123"
}

Extract Structured Data

After parsing, extract specific fields using a schema:


curl -X POST "https://your-domain.com/api/extract/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "YOUR_DOCUMENT_ID",
    "config": {
      "fields": [
        {"name": "title", "type": "string"},
        {"name": "date", "type": "date"},
        {"name": "amount", "type": "number"}
      ]
    }
  }'

Chat with Documents

The Chat API is stream-only (SSE). You create a session first, then send messages with a UIMessage shape. For a non-streaming JSON response (e.g. from a server), use the Embed API with action: 'chat'.

Step 1 — Create a knowledge base and add a document:


# Create knowledge base
curl -X POST "https://your-domain.com/api/knowledge-bases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Documents"}'
 
# Add document (use the kb_id from the response)
curl -X POST "https://your-domain.com/api/knowledge-bases/{kb_id}/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "YOUR_DOCUMENT_ID"}'

Step 2 — Create a chat session:


curl -X POST "https://your-domain.com/api/chat/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id": "{kb_id}"}'

The response includes a session_id. Use it in the next step.

Step 3 — Send a message (streamed response):


curl -X POST "https://your-domain.com/api/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "What is this document about?" }]
    },
    "session_id": "SESSION_ID_FROM_STEP_2",
    "knowledge_base_id": "{kb_id}"
  }'

The response is a Server-Sent Events (SSE) stream. Parse text-delta chunks for the reply and tool-output-available for citations. See the Chat API for the full stream format. For a simple JSON { message, citations } response instead, use the Embed API with action: 'chat'.

Next Steps

SDKs — Use the JavaScript or Python SDK instead of raw HTTP
Chat API — Full stream format and session/message contract
Embed API — Non-streaming parse, extract, and chat in one endpoint
MCP & IDE — Use DocLD docs in Cursor, Claude, and other IDEs
Document Parsing — Supported formats and OCR capabilities
Data Extraction — Extract specific fields with schemas
RAG Chat — Chat with your documents
Knowledge Bases — Organize documents
API Reference — Full endpoint documentation