Document Conversion

Turn PDFs, Word docs, and emails into clean text —ready for extraction or any downstream processing.

How It Works

Send a document via URL, base64, or file upload and get back its content as Markdown, plain text, JSON, or HTML. Backbone handles format detection, parsing, and text extraction automatically. All you need is an API key.

Pipelines

Backbone offers three processing pipelines. Choose the one that fits your document type:

The fast pipeline is the default and works for most documents. Use ocr or vlm when you need to process scanned or image-heavy content. Not every format supports every pipeline — see the supported formats table for the full matrix.

Convert from URL

POST /api/v1/convert/source

The primary endpoint. Pass one or more document URLs and get back converted text.

curl -X POST https://backbone.manfred-kunze.dev/api/v1/convert/source \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_api_key" \
  -d '{
    "sources": [
      {
        "kind": "http",
        "url": "https://example.com/document.pdf"
      }
    ]
  }'

Response

{
  "documents": [
    {
      "filename": "document.pdf",
      "mdContent": "# Document Title\n\nExtracted content..."
    }
  ],
  "status": "SUCCESS",
  "errors": [],
  "processingTime": 1.234
}

Source Types

Each source in the sources array needs a kind field:

HTTP source —fetch a document from a URL:

{
  "kind": "http",
  "url": "https://example.com/document.pdf",
  "headers": {
    "Authorization": "Bearer external-token"
  }
}

The optional headers field lets you pass authentication or custom headers to the source server.

Base64 source —send the document content directly:

{
  "kind": "base64",
  "content": "JVBERi0xLjQK...",
  "filename": "document.pdf",
  "mimeType": "application/pdf"
}

Batch Conversion

Convert multiple documents in a single request:

{
  "sources": [
    { "kind": "http", "url": "https://example.com/report.pdf" },
    { "kind": "http", "url": "https://example.com/notes.docx" }
  ],
  "options": {
    "abortOnError": false
  }
}

When abortOnError is false (the default), the API processes all documents even if some fail. Failed documents appear in the errors array, and the status will be PARTIAL_SUCCESS (HTTP 207).

Convert Uploaded Files

POST /api/v1/convert/file

Upload files directly using multipart/form-data:

curl -X POST https://backbone.manfred-kunze.dev/api/v1/convert/file \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "[email protected]" \
  -F "[email protected]"

File Upload Parameters

OCR and VLM Pipelines

For scanned documents, image-heavy PDFs, or complex layouts where the default fast pipeline falls short, use the ocr or vlm pipeline.

curl -X POST https://backbone.manfred-kunze.dev/api/v1/convert/source \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_api_key" \
  -d '{
    "sources": [
      {
        "kind": "http",
        "url": "https://example.com/scanned-document.pdf"
      }
    ],
    "options": {
      "pipeline": "ocr",
      "options": {
        "ocrLanguages": ["en", "de"],
        "tableStructure": true
      }
    }
  }'

When to Use Each Pipeline

Conversion Options

When using the /source endpoint, you can pass an options object:

Top-level options:

Async Conversion

For large documents or batch jobs, use the async endpoints to avoid timeouts.

Start an Async Job

POST /api/v1/convert/source/async

Same request body as the sync endpoint. Returns 202 Accepted immediately with a task ID:

{
  "taskId": "task-uuid",
  "taskType": "CONVERSION",
  "taskStatus": "PENDING",
  "taskPosition": 1
}

Poll Task Status

GET /api/v1/convert/tasks/{taskId}

Check whether the task is still running:

curl https://backbone.manfred-kunze.dev/api/v1/convert/tasks/{taskId} \
  -H "Authorization: Bearer sk_your_api_key"

Add ?wait=30 for long polling.

Get the Result

GET /api/v1/convert/tasks/{taskId}/result

Once taskStatus is COMPLETED, fetch the full result:

curl https://backbone.manfred-kunze.dev/api/v1/convert/tasks/{taskId}/result \
  -H "Authorization: Bearer sk_your_api_key"

Supported Formats

Input

Output

Status Codes