> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/lumina-ai-inc/chunkr/llms.txt
> Use this file to discover all available pages before exploring further.

# Processing Documents

> Learn how to process documents with Chunkr's API using various configuration options

Chunkr's document processing API converts PDFs, PowerPoint presentations, Word documents, and images into structured, RAG-ready chunks with layout analysis, OCR, and semantic processing.

## Quick Start

<Steps>
  <Step title="Upload a Document">
    Send a POST request to `/api/v1/task/parse` with your document:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.chunkr.ai/api/v1/task/parse \
        -H "Authorization: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "file": "https://example.com/document.pdf",
          "ocr_strategy": "All",
          "segmentation_strategy": "LayoutAnalysis"
        }'
      ```

      ```python Python theme={null}
      import requests
      import base64

      # Using a URL
      response = requests.post(
          "https://api.chunkr.ai/api/v1/task/parse",
          headers={"Authorization": "YOUR_API_KEY"},
          json={
              "file": "https://example.com/document.pdf",
              "ocr_strategy": "All",
              "segmentation_strategy": "LayoutAnalysis"
          }
      )

      # Or using base64 encoded file
      with open("document.pdf", "rb") as f:
          file_data = base64.b64encode(f.read()).decode()

      response = requests.post(
          "https://api.chunkr.ai/api/v1/task/parse",
          headers={"Authorization": "YOUR_API_KEY"},
          json={
              "file": f"data:application/pdf;base64,{file_data}",
              "file_name": "document.pdf"
          }
      )

      task = response.json()
      task_id = task["task_id"]
      ```

      ```javascript JavaScript theme={null}
      const fs = require('fs');

      // Using a URL
      const response = await fetch('https://api.chunkr.ai/api/v1/task/parse', {
        method: 'POST',
        headers: {
          'Authorization': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          file: 'https://example.com/document.pdf',
          ocr_strategy: 'All',
          segmentation_strategy: 'LayoutAnalysis'
        })
      });

      // Or using base64 encoded file
      const fileData = fs.readFileSync('document.pdf');
      const base64Data = fileData.toString('base64');

      const response = await fetch('https://api.chunkr.ai/api/v1/task/parse', {
        method: 'POST',
        headers: {
          'Authorization': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          file: `data:application/pdf;base64,${base64Data}`,
          file_name: 'document.pdf'
        })
      });

      const task = await response.json();
      const taskId = task.task_id;
      ```
    </CodeGroup>

    The API returns a task object with a `task_id` for polling.
  </Step>

  <Step title="Poll for Completion">
    Use the task ID to check processing status:

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.chunkr.ai/api/v1/task/{task_id} \
        -H "Authorization: YOUR_API_KEY"
      ```

      ```python Python theme={null}
      import time

      while True:
          response = requests.get(
              f"https://api.chunkr.ai/api/v1/task/{task_id}",
              headers={"Authorization": "YOUR_API_KEY"}
          )
          task = response.json()
          
          if task["status"] == "Succeeded":
              print("Processing complete!")
              break
          elif task["status"] == "Failed":
              print("Processing failed")
              break
          
          time.sleep(2)
      ```

      ```javascript JavaScript theme={null}
      async function pollTask(taskId) {
        while (true) {
          const response = await fetch(
            `https://api.chunkr.ai/api/v1/task/${taskId}`,
            { headers: { 'Authorization': 'YOUR_API_KEY' } }
          );
          const task = await response.json();
          
          if (task.status === 'Succeeded') {
            console.log('Processing complete!');
            return task;
          } else if (task.status === 'Failed') {
            throw new Error('Processing failed');
          }
          
          await new Promise(resolve => setTimeout(resolve, 2000));
        }
      }

      const result = await pollTask(taskId);
      ```
    </CodeGroup>
  </Step>

  <Step title="Retrieve Results">
    Once status is `Succeeded`, access the processed output:

    ```python Python theme={null}
    # Access the processed chunks
    for chunk in task["output"]["chunks"]:
        print(f"Chunk ID: {chunk['chunk_id']}")
        print(f"Chunk Length: {chunk['chunk_length']} tokens")
        
        # Access segments within the chunk
        for segment in chunk["segments"]:
            print(f"Type: {segment['segment_type']}")
            print(f"Content: {segment['content']}")
            print(f"Text: {segment['text']}")
    ```
  </Step>
</Steps>

## Configuration Options

### Segmentation Strategy

Controls how the document is analyzed and segmented.

<Tabs>
  <Tab title="LayoutAnalysis">
    **Default strategy** - Analyzes document layout and detects different element types:

    ```json theme={null}
    {
      "segmentation_strategy": "LayoutAnalysis"
    }
    ```

    **Detects:**

    * Title, SectionHeader, Text, ListItem
    * Table, Picture, Caption
    * Formula, Footnote
    * PageHeader, PageFooter

    **Best for:** Most documents requiring accurate structure detection
  </Tab>

  <Tab title="Page">
    Treats each page as a single segment:

    ```json theme={null}
    {
      "segmentation_strategy": "Page"
    }
    ```

    **Best for:** Simple documents or when page-level processing is sufficient
  </Tab>
</Tabs>

### OCR Strategy

Controls optical character recognition processing.

<Tabs>
  <Tab title="All">
    **Default** - Processes all pages with OCR:

    ```json theme={null}
    {
      "ocr_strategy": "All"
    }
    ```

    <Note>
      Adds \~0.5 seconds per page latency
    </Note>
  </Tab>

  <Tab title="Auto">
    Selectively applies OCR only when needed:

    ```json theme={null}
    {
      "ocr_strategy": "Auto"
    }
    ```

    Uses existing text layer when available, applies OCR only to pages with missing or low-quality text.
  </Tab>
</Tabs>

### High Resolution Processing

Enables high-resolution images for better quality cropping and post-processing:

```json theme={null}
{
  "high_resolution": true
}
```

<Warning>
  Adds \~7 seconds per page latency but significantly improves image quality
</Warning>

## Advanced Examples

### Complete Configuration

```python Python theme={null}
import requests
import base64

with open("document.pdf", "rb") as f:
    file_data = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.chunkr.ai/api/v1/task/parse",
    headers={"Authorization": "YOUR_API_KEY"},
    json={
        "file": f"data:application/pdf;base64,{file_data}",
        "file_name": "document.pdf",
        "ocr_strategy": "All",
        "segmentation_strategy": "LayoutAnalysis",
        "high_resolution": true,
        "expires_in": 86400,  # 24 hours
        "chunk_processing": {
            "target_length": 512,
            "ignore_headers_and_footers": true,
            "tokenizer": "Word"
        }
    }
)

task = response.json()
print(f"Task ID: {task['task_id']}")
print(f"Status: {task['status']}")
```

### Updating Task Configuration

You can update a completed task to reprocess with different settings:

<Note>
  Task must have status `Succeeded` or `Failed` to be updated
</Note>

```python Python theme={null}
response = requests.patch(
    f"https://api.chunkr.ai/api/v1/task/{task_id}/parse",
    headers={"Authorization": "YOUR_API_KEY"},
    json={
        "ocr_strategy": "Auto",
        "high_resolution": false
    }
)

updated_task = response.json()
```

### Deleting Tasks

```python Python theme={null}
response = requests.delete(
    f"https://api.chunkr.ai/api/v1/task/{task_id}",
    headers={"Authorization": "YOUR_API_KEY"}
)
```

### Canceling Tasks

Cancel a task that hasn't started processing:

```python Python theme={null}
response = requests.get(
    f"https://api.chunkr.ai/api/v1/task/{task_id}/cancel",
    headers={"Authorization": "YOUR_API_KEY"}
)
```

<Note>
  Task must have status `Starting` to be cancelled
</Note>

## Error Handling

### Error Handling Strategy

Control how errors are handled during processing:

<Tabs>
  <Tab title="Fail">
    **Default** - Stops processing on any error:

    ```json theme={null}
    {
      "error_handling": "Fail"
    }
    ```
  </Tab>

  <Tab title="Continue">
    Attempts to continue despite non-critical errors:

    ```json theme={null}
    {
      "error_handling": "Continue"
    }
    ```

    Useful for handling LLM refusals or partial processing failures.
  </Tab>
</Tabs>

### Common Error Responses

| Status Code | Error                 | Description                          |
| ----------- | --------------------- | ------------------------------------ |
| 400         | Bad Request           | Invalid configuration or file format |
| 404         | Not Found             | Task not found or expired            |
| 413         | Payload Too Large     | File size exceeds limits             |
| 429         | Too Many Requests     | Usage limit exceeded                 |
| 500         | Internal Server Error | Processing failed                    |

## Response Structure

See core/src/routes/task.rs:20-48 for complete response schema.

```json theme={null}
{
  "task_id": "uuid",
  "status": "Succeeded",
  "created_at": "2024-01-01T00:00:00Z",
  "started_at": "2024-01-01T00:00:01Z",
  "finished_at": "2024-01-01T00:00:15Z",
  "file_name": "document.pdf",
  "page_count": 10,
  "pdf_url": "https://...",
  "output": {
    "chunks": [
      {
        "chunk_id": "uuid",
        "chunk_length": 256,
        "segments": [
          {
            "segment_id": "uuid",
            "segment_type": "Text",
            "content": "Generated content (HTML or Markdown)",
            "text": "OCR extracted text",
            "html": "HTML representation",
            "markdown": "Markdown representation",
            "bbox": {"left": 0, "top": 0, "width": 100, "height": 50},
            "page_number": 1,
            "page_width": 612,
            "page_height": 792
          }
        ],
        "embed": "Text to be embedded"
      }
    ]
  }
}
```

## Best Practices

<Accordion title="Choose appropriate strategies">
  * Use `LayoutAnalysis` for complex documents with tables, images, and varied layouts
  * Use `Page` strategy for simple text-only documents
  * Use `Auto` OCR strategy to optimize speed when documents have good text layers
</Accordion>

<Accordion title="Optimize for performance">
  * Set `high_resolution: false` for documents without important images
  * Use reasonable `target_length` values (512-1024 tokens)
  * Configure `expires_in` to automatically clean up old tasks
</Accordion>

<Accordion title="Handle task lifecycle">
  * Poll tasks with exponential backoff to avoid rate limits
  * Store task IDs for later retrieval
  * Delete tasks when no longer needed to free resources
</Accordion>

## Next Steps

* Learn about [custom chunking strategies](/guides/custom-chunking)
* Configure [VLM processing](/guides/using-vlm) for enhanced content generation
* Review the [migration guide](/guides/migration-guide) for API changes