Document Conversion

Turn PDFs, Word docs, emails, and ZIP archives 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. 2kw.ai handles format detection, parsing, and text extraction automatically. All you need is an API key.

Pipelines

2kw.ai 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 /v1/convert/source

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

curl -X POST https://api.2kw.ai/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 /v1/convert/file

Upload files directly using multipart/form-data:

curl -X POST https://api.2kw.ai/v1/convert/file \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "files=@document.pdf" \
  -F "files=@notes.docx"

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://api.2kw.ai/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:

Pipeline Options

The nested options.options object tunes the output and the ocr/vlm pipelines. On /file endpoints, send the same object as the options part. Every field is optional; leave one out to use the pipeline's default.

For example, to get only Markdown and HTML back:

{
  "sources": [{ "kind": "http", "url": "https://example.com/report.pdf" }],
  "options": {
    "options": { "outputFormats": ["MD", "HTML"] }
  }
}

Async Conversion

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

Start an Async Job

POST /v1/convert/source/async

Same request body as the sync endpoint. Returns 202 Accepted immediately with a task ID, a Location header pointing at the task (/v1/convert/tasks/{taskId}), and Retry-After: 5:

{
  "taskId": "task-uuid",
  "taskType": "CONVERT",
  "taskStatus": "pending",
  "taskMeta": {
    "numDocs": 2,
    "numProcessed": 0,
    "numSucceeded": 0,
    "numFailed": 0
  }
}

taskStatus is one of pending, processing, success, or failure. failure means the task itself failed; a task that finished is success even when some of its documents could not be converted, so read the result's own status and errors to tell a full from a partial success. taskMeta.numDocs counts the files you sent; once the task has finished, numSucceeded counts the documents returned (an email's attachments count separately) and numFailed the errors.

Poll Task Status

GET /v1/convert/tasks/{taskId}

Check whether the task is still running:

curl https://api.2kw.ai/v1/convert/tasks/{taskId} \
  -H "Authorization: Bearer sk_your_api_key"

The response has the same shape as above. Add ?wait=30 for long polling (at most 60 seconds).

Get the Result

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

Once taskStatus is success or failure, fetch the full result. It has the same shape as a synchronous response:

curl https://api.2kw.ai/v1/convert/tasks/{taskId}/result \
  -H "Authorization: Bearer sk_your_api_key"

Supported Formats

Input

Output

Status Codes