Embed API

Unified headless API for embedding DocLD into third-party applications. Use a single endpoint with an action to parse, extract, or chat and receive JSON responses (no streaming). Ideal for server-side or API-key–only usage where you want a simple request/response contract.

Endpoint: POST /api/v1/embed

Authentication: Bearer API key required (Authorization: Bearer YOUR_API_KEY).

Request

Content-Type: application/json


{
  "action": "parse",
  "parse": {
    "input": "https://example.com/document.pdf"
  }
}

Field	Type	Required	Description
`action`	string	Yes	One of: `parse`, `extract`, `chat`.
`parse`	object	When `action === 'parse'`	See Parse.
`extract`	object	When `action === 'extract'`	See Extract.
`chat`	object	When `action === 'chat'`	See Chat.

Parse

Parse a document from a URL or DocLD reference. Returns the same shape as Parse API (POST /api/parse, synchronous).

Request:


{
  "action": "parse",
  "parse": {
    "input": "docld://document-uuid"
  }
}

Or from URL:


{
  "action": "parse",
  "parse": {
    "input": "https://example.com/document.pdf"
  }
}

Field	Type	Required	Description
`parse.input`	string	Yes	Document URL (`https://...`) or DocLD reference (`docld://<id>`).

Response:


{
  "action": "parse",
  "data": {
    "job_id": "uuid",
    "duration": 2.5,
    "usage": { "num_pages": 5, "credits": 7.5 },
    "result": { "type": "full", "chunks": [...] },
    "studio_link": "https://your-domain.com/documents/..."
  }
}

Extract

Run extraction on a document. Same behavior as POST /api/extract/run; returns JSON.

Request:


{
  "action": "extract",
  "extract": {
    "document_id": "document-uuid",
    "schema_id": "schema-uuid"
  }
}

Or with URL input (and optional schema):


{
  "action": "extract",
  "extract": {
    "input": "https://example.com/invoice.pdf",
    "schema_id": "schema-uuid"
  }
}

Field	Type	Required	Description
`extract.document_id`	string (UUID)	No*	Document to extract from.
`extract.input`	string	No*	URL or DocLD reference if not using `document_id`.
`extract.schema_id`	string (UUID)	No	Schema to use; optional depending on config.

* One of document_id or input is required.

Response:


{
  "action": "extract",
  "data": { ... }
}

The data shape matches the Extract API run response.

Chat

Get a non-streaming chat response: send a plain text message and receive JSON with the assistant reply and citations. The Embed API creates a session if needed, calls the streaming Chat API internally, and returns the accumulated message and citations.

Request:


{
  "action": "chat",
  "chat": {
    "message": "What are the payment terms in this contract?",
    "knowledge_base_id": "kb-uuid",
    "session_id": "session-uuid",
    "mode": "quick"
  }
}

Field	Type	Required	Description
`chat.message`	string	Yes	User message text.
`chat.knowledge_base_id`	string (UUID)	Yes	Knowledge base to search.
`chat.session_id`	string (UUID)	No	Existing session; if omitted, a new session is created for this request.
`chat.mode`	string	No	`quick`, `deep`, or `code`. Default `quick`.

Response:


{
  "action": "chat",
  "data": {
    "message": "The payment terms state that...",
    "citations": [
      {
        "chunk_id": "...",
        "document_id": "...",
        "content": "...",
        "metadata": { ... }
      }
    ]
  }
}

For streaming chat (e.g. in a UI), use the Chat API directly.

Example

Chat (no session):


curl -X POST "https://your-domain.com/api/v1/embed" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "chat",
    "chat": {
      "message": "Summarize this document.",
      "knowledge_base_id": "your-kb-uuid",
      "mode": "quick"
    }
  }'

Parse from URL:


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

Errors

Errors follow the same format as other DocLD APIs:


{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable message",
    "details": {}
  }
}

Common cases: missing or invalid action, missing required params for the chosen action, invalid UUIDs, or upstream errors from parse/extract/chat.

Embed API

Endpoint: POST /api/v1/embed

Authentication: Bearer API key required (Authorization: Bearer YOUR_API_KEY).

Request

Content-Type: application/json


{
  "action": "parse",
  "parse": {
    "input": "https://example.com/document.pdf"
  }
}

Field	Type	Required	Description
`action`	string	Yes	One of: `parse`, `extract`, `chat`.
`parse`	object	When `action === 'parse'`	See Parse.
`extract`	object	When `action === 'extract'`	See Extract.
`chat`	object	When `action === 'chat'`	See Chat.

Parse

Parse a document from a URL or DocLD reference. Returns the same shape as Parse API (POST /api/parse, synchronous).

Request:


{
  "action": "parse",
  "parse": {
    "input": "docld://document-uuid"
  }
}

Or from URL:


{
  "action": "parse",
  "parse": {
    "input": "https://example.com/document.pdf"
  }
}

Field	Type	Required	Description
`parse.input`	string	Yes	Document URL (`https://...`) or DocLD reference (`docld://<id>`).

Response:


{
  "action": "parse",
  "data": {
    "job_id": "uuid",
    "duration": 2.5,
    "usage": { "num_pages": 5, "credits": 7.5 },
    "result": { "type": "full", "chunks": [...] },
    "studio_link": "https://your-domain.com/documents/..."
  }
}

Extract

Run extraction on a document. Same behavior as POST /api/extract/run; returns JSON.

Request:


{
  "action": "extract",
  "extract": {
    "document_id": "document-uuid",
    "schema_id": "schema-uuid"
  }
}

Or with URL input (and optional schema):


{
  "action": "extract",
  "extract": {
    "input": "https://example.com/invoice.pdf",
    "schema_id": "schema-uuid"
  }
}

Field	Type	Required	Description
`extract.document_id`	string (UUID)	No*	Document to extract from.
`extract.input`	string	No*	URL or DocLD reference if not using `document_id`.
`extract.schema_id`	string (UUID)	No	Schema to use; optional depending on config.

* One of document_id or input is required.

Response:


{
  "action": "extract",
  "data": { ... }
}

The data shape matches the Extract API run response.

Chat

Request:


{
  "action": "chat",
  "chat": {
    "message": "What are the payment terms in this contract?",
    "knowledge_base_id": "kb-uuid",
    "session_id": "session-uuid",
    "mode": "quick"
  }
}

Field	Type	Required	Description
`chat.message`	string	Yes	User message text.
`chat.knowledge_base_id`	string (UUID)	Yes	Knowledge base to search.
`chat.session_id`	string (UUID)	No	Existing session; if omitted, a new session is created for this request.
`chat.mode`	string	No	`quick`, `deep`, or `code`. Default `quick`.

Response:


{
  "action": "chat",
  "data": {
    "message": "The payment terms state that...",
    "citations": [
      {
        "chunk_id": "...",
        "document_id": "...",
        "content": "...",
        "metadata": { ... }
      }
    ]
  }
}

For streaming chat (e.g. in a UI), use the Chat API directly.

Example

Chat (no session):


curl -X POST "https://your-domain.com/api/v1/embed" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "chat",
    "chat": {
      "message": "Summarize this document.",
      "knowledge_base_id": "your-kb-uuid",
      "mode": "quick"
    }
  }'

Parse from URL:


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

Errors

Errors follow the same format as other DocLD APIs:


{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable message",
    "details": {}
  }
}

Common cases: missing or invalid action, missing required params for the chosen action, invalid UUIDs, or upstream errors from parse/extract/chat.