> ## 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.

# Quickstart

> Get started with Chunkr in minutes - make your first API request and process documents

# Quickstart Guide

This guide will help you make your first API request to Chunkr and process a document. We'll cover both local deployment and using the Cloud API.

<Info>
  This quickstart assumes you have Chunkr running locally. If you haven't installed it yet, check out the [Installation Guide](/installation).
</Info>

## Prerequisites

<Steps>
  <Step title="Chunkr is Running">
    Ensure your Chunkr services are up and running:

    ```bash theme={null}
    docker compose ps
    ```

    You should see all services in "Up" state.
  </Step>

  <Step title="Access the Services">
    Verify you can access:

    * API: `http://localhost:8000`
    * Web UI: `http://localhost:5173`
  </Step>

  <Step title="LLM Configuration">
    Make sure you've configured at least one LLM in `models.yaml`. See the [Installation Guide](/installation#llm-configuration) for details.
  </Step>
</Steps>

## Making Your First Request

### Using the Web UI

The easiest way to get started is using the built-in web interface:

<Steps>
  <Step title="Open the Web UI">
    Navigate to `http://localhost:5173` in your browser
  </Step>

  <Step title="Upload a Document">
    Click the upload area and select a PDF, Word doc, PowerPoint, or image file
  </Step>

  <Step title="Configure Processing">
    Choose your processing options:

    * **OCR Strategy**: `All` (process all pages) or `Auto` (selective)
    * **Segmentation Strategy**: `LayoutAnalysis` (detailed) or `Page` (simple)
    * **High Resolution**: Enable for better quality (adds \~7s per page)
  </Step>

  <Step title="View Results">
    Watch your document process in real-time and explore the structured output
  </Step>
</Steps>

### Using the API

For programmatic access, use the REST API. Here's how to process a document:

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

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

  # Create a task
  response = requests.post(
      "http://localhost:8000/api/v1/task/parse",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "file": "https://example.com/document.pdf",
          "ocr_strategy": "Auto",
          "segmentation_strategy": "LayoutAnalysis",
          "high_resolution": True
      }
  )

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

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8000/api/v1/task/parse', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file: 'https://example.com/document.pdf',
      ocr_strategy: 'Auto',
      segmentation_strategy: 'LayoutAnalysis',
      high_resolution: true
    })
  });

  const task = await response.json();
  console.log('Task ID:', task.task_id);
  console.log('Status:', task.status);
  ```
</CodeGroup>

<Note>
  For local development without authentication, you can omit the `Authorization` header. Authentication is required when deploying to production.
</Note>

### Using Base64 Encoded Files

You can also upload files directly as base64:

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

# Read and encode file
with open('document.pdf', 'rb') as f:
    file_data = base64.b64encode(f.read()).decode('utf-8')
    file_base64 = f"data:application/pdf;base64,{file_data}"

# Create task with base64 file
response = requests.post(
    "http://localhost:8000/api/v1/task/parse",
    json={
        "file": file_base64,
        "file_name": "document.pdf",
        "ocr_strategy": "Auto",
        "segmentation_strategy": "LayoutAnalysis"
    }
)

task = response.json()
```

## Polling for Results

Document processing is asynchronous. Use the task ID to check status and retrieve results:

<CodeGroup>
  ```bash cURL theme={null}
  curl http://localhost:8000/api/v1/task/{task_id} \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  def wait_for_task(task_id):
      url = f"http://localhost:8000/api/v1/task/{task_id}"
      
      while True:
          response = requests.get(url)
          task = response.json()
          
          status = task['status']
          print(f"Status: {status}")
          
          if status == 'Succeeded':
              return task
          elif status == 'Failed':
              raise Exception(f"Task failed: {task.get('message')}")
          
          time.sleep(2)  # Poll every 2 seconds

  # Use it
  result = wait_for_task(task['task_id'])
  print(f"Processed {len(result['output'])} pages")
  ```

  ```javascript JavaScript theme={null}
  async function waitForTask(taskId) {
    const url = `http://localhost:8000/api/v1/task/${taskId}`;
    
    while (true) {
      const response = await fetch(url);
      const task = await response.json();
      
      console.log('Status:', task.status);
      
      if (task.status === 'Succeeded') {
        return task;
      } else if (task.status === 'Failed') {
        throw new Error(`Task failed: ${task.message}`);
      }
      
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }

  // Use it
  const result = await waitForTask(task.task_id);
  console.log(`Processed ${result.output.length} pages`);
  ```
</CodeGroup>

## Understanding the Response

The task response contains rich structured data:

```json theme={null}
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "Succeeded",
  "created_at": "2026-03-02T10:00:00Z",
  "finished_at": "2026-03-02T10:00:15Z",
  "file_name": "document.pdf",
  "page_count": 5,
  "output": [
    {
      "page_number": 1,
      "segments": [
        {
          "segment_id": "seg_001",
          "segment_type": "Title",
          "content": "<h1>Document Title</h1>",
          "text": "Document Title",
          "bbox": {
            "left": 100,
            "top": 50,
            "width": 400,
            "height": 60
          },
          "confidence": 0.98
        },
        {
          "segment_id": "seg_002",
          "segment_type": "Text",
          "content": "<p>This is the document content...</p>",
          "text": "This is the document content...",
          "bbox": {...}
        }
      ]
    }
  ]
}
```

<Accordion title="Response Fields Explained">
  * **task\_id**: Unique identifier for tracking this task
  * **status**: Current state (`Starting`, `Processing`, `Succeeded`, `Failed`)
  * **output**: Array of pages, each containing segments
  * **segments**: Individual layout elements (Title, Text, Table, Picture, etc.)
  * **content**: Generated HTML or Markdown based on configuration
  * **text**: Raw OCR-extracted text
  * **bbox**: Bounding box coordinates (left, top, width, height)
  * **segment\_type**: Element type (Title, SectionHeader, Text, ListItem, Table, Picture, Caption, Formula, Footnote, PageHeader, PageFooter)
</Accordion>

## Configuration Options

### OCR Strategy

Controls how OCR is applied:

* **`All`** (default): Process all pages with OCR (\~0.5s penalty per page)
* **`Auto`**: Selective OCR only where needed; uses existing text layer when available

### Segmentation Strategy

Controls layout analysis:

* **`LayoutAnalysis`** (default): Detect all layout elements with bounding boxes
* **`Page`**: Treat each page as a single segment (faster, less detailed)

### Additional Options

```json theme={null}
{
  "high_resolution": true,        // Use high-res images (~7s per page)
  "expires_in": 3600,             // Task expiration in seconds
  "error_handling": "Fail",       // "Fail" or "Continue" on errors
  "chunk_processing": {           // Configure semantic chunking
    "target_length": 512
  },
  "segment_processing": {         // Per-segment format configuration
    "table": {
      "format": "Markdown",
      "strategy": "LLM"           // Use LLM for table extraction
    },
    "picture": {
      "format": "Html",
      "strategy": "LLM"           // Generate image descriptions
    }
  }
}
```

<Warning>
  High-resolution processing significantly improves quality but adds \~7 seconds per page. Use it for documents requiring precise extraction.
</Warning>

## Common Use Cases

### RAG/LLM Pipeline

Extract chunks for embedding and retrieval:

```python theme={null}
# Process with semantic chunking
response = requests.post(
    "http://localhost:8000/api/v1/task/parse",
    json={
        "file": file_url,
        "chunk_processing": {
            "target_length": 512
        },
        "segment_processing": {
            "text": {"format": "Markdown"}
        }
    }
)

# Extract chunks for embedding
task = wait_for_task(response.json()['task_id'])
for page in task['output']:
    for segment in page['segments']:
        # Embed segment['content'] or segment['text']
        pass
```

### Table Extraction

Extract structured tables with LLM enhancement:

```python theme={null}
response = requests.post(
    "http://localhost:8000/api/v1/task/parse",
    json={
        "file": file_url,
        "segment_processing": {
            "table": {
                "format": "Markdown",
                "strategy": "LLM"  # AI-enhanced structure
            }
        }
    }
)
```

### Image Description

Generate descriptions for images using VLM:

```python theme={null}
response = requests.post(
    "http://localhost:8000/api/v1/task/parse",
    json={
        "file": file_url,
        "segment_processing": {
            "picture": {
                "format": "Html",
                "strategy": "LLM"  # Generate descriptions
            }
        }
    }
)
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference">
    Explore all API endpoints and parameters
  </Card>

  <Card title="Configuration" icon="sliders" href="/configuration">
    Learn about advanced configuration options
  </Card>

  <Card title="Installation" icon="docker" href="/installation">
    Deploy Chunkr to production
  </Card>

  <Card title="Examples" icon="code" href="/examples">
    See more code examples and use cases
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Task fails immediately">
    Check that:

    * Your LLM is configured in `models.yaml`
    * The file URL is accessible or base64 is valid
    * All required services are running (`docker compose ps`)
  </Accordion>

  <Accordion title="Processing is very slow">
    Consider:

    * Using `Auto` OCR strategy instead of `All`
    * Disabling `high_resolution` if not needed
    * Deploying with GPU support (see [Installation](/installation))
    * Scaling up worker replicas in `compose.yaml`
  </Accordion>

  <Accordion title="LLM processing fails">
    Verify:

    * API key is valid in `models.yaml`
    * LLM endpoint is reachable
    * Rate limits aren't exceeded
    * Model supports the OpenAI-compatible format
  </Accordion>
</AccordionGroup>