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

# Create Task

> Queue a document for processing and receive a task ID for status polling

## Endpoint

```
POST /api/v1/task/parse
```

## Authentication

This endpoint requires API key authentication via the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

The request body must be JSON with the following schema:

<ParamField body="file" type="string" required>
  The file to be uploaded. Can be a URL or a base64 encoded file.
</ParamField>

<ParamField body="file_name" type="string">
  The name of the file to be uploaded. If not set, a name will be generated.
</ParamField>

<ParamField body="ocr_strategy" type="enum" default="All">
  Controls the Optical Character Recognition (OCR) strategy:

  * `All`: Processes all pages with OCR. (Latency penalty: \~0.5 seconds per page)
  * `Auto`: Selectively applies OCR only to pages with missing or low-quality text. When text layer is present, the bounding boxes from the text layer are used.
</ParamField>

<ParamField body="segmentation_strategy" type="enum" default="LayoutAnalysis">
  Controls the segmentation strategy:

  * `LayoutAnalysis`: Analyzes pages for layout elements (e.g., `Table`, `Picture`, `Formula`, etc.) using bounding boxes. Provides fine-grained segmentation and better chunking.
  * `Page`: Treats each page as a single segment. Faster processing, but without layout element detection and only simple chunking.
</ParamField>

<ParamField body="high_resolution" type="boolean" default={true}>
  Whether to use high-resolution images for cropping and post-processing. (Latency penalty: \~7 seconds per page)
</ParamField>

<ParamField body="expires_in" type="integer">
  The number of seconds until task is deleted. Expired tasks cannot be updated, polled, or accessed via web interface.
</ParamField>

<ParamField body="error_handling" type="enum" default="Fail">
  Controls how errors are handled during processing:

  * `Fail`: Stops processing and fails the task when any error occurs
  * `Continue`: Attempts to continue processing despite non-critical errors (e.g., LLM refusals)
</ParamField>

<ParamField body="chunk_processing" type="object">
  Controls the settings for chunking and post-processing of each chunk.

  <Expandable title="properties">
    <ParamField body="target_length" type="integer" default={512}>
      The target number of words in each chunk. If 0, each chunk will contain a single segment.
    </ParamField>

    <ParamField body="ignore_headers_and_footers" type="boolean" default={true}>
      Whether to ignore headers and footers in the chunking process. This is recommended as headers and footers break reading order across pages.
    </ParamField>

    <ParamField body="tokenizer" type="string | enum" default="Word">
      The tokenizer to use for the chunking process. Can be:

      * Enum values: `Word`, `Cl100kBase`, `xlm-roberta-base`, `bert-base-uncased`
      * String: Any Hugging Face tokenizer model ID (e.g., "Qwen/Qwen-tokenizer", "facebook/bart-large")
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="segment_processing" type="object">
  Controls the post-processing of each segment type. Allows generation of HTML and Markdown from Chunkr models.

  <Expandable title="properties">
    Each segment type (`Title`, `SectionHeader`, `Text`, `ListItem`, `Table`, `Picture`, `Caption`, `Formula`, `Footnote`, `PageHeader`, `PageFooter`, `Page`) can be configured with:

    <ParamField body="crop_image" type="enum">
      Controls whether to crop images to the segment's bounding box:

      * `Auto`: Only crop when needed for post-processing
      * `All`: Always crop (for Picture segments)
    </ParamField>

    <ParamField body="format" type="enum" default="Markdown">
      Output format: `Html` or `Markdown`
    </ParamField>

    <ParamField body="strategy" type="enum">
      Content generation strategy:

      * `Auto`: Use heuristics (default for most segments)
      * `LLM`: Use Chunkr fine-tuned models (default for Table, Formula, Page)
    </ParamField>

    <ParamField body="llm" type="string">
      Custom prompt for LLM model processing
    </ParamField>

    <ParamField body="embed_sources" type="array" default={["Content"]}>
      Array of content sources to include in the chunk's embed field: `Content`, `LLM`
    </ParamField>

    <ParamField body="extended_context" type="boolean" default={false}>
      Use the full page image as context for LLM generation
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="llm_processing" type="object">
  Controls the LLM used for the task.

  <Expandable title="properties">
    <ParamField body="model_id" type="string">
      The ID of the model to use for the task. If not provided, the default model will be used.
    </ParamField>

    <ParamField body="fallback_strategy" type="enum | object" default="Default">
      Fallback strategy for LLM processing:

      * `None`: No fallback
      * `Default`: System default fallback model
      * `Model(string)`: Specific model ID as fallback
    </ParamField>

    <ParamField body="max_completion_tokens" type="integer">
      Maximum number of tokens to generate
    </ParamField>

    <ParamField body="temperature" type="number" default={0.0}>
      Temperature for LLM generation
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  The unique identifier for the task
</ResponseField>

<ResponseField name="status" type="enum">
  The status of the task: `Starting`, `Processing`, `Succeeded`, `Failed`, or `Cancelled`
</ResponseField>

<ResponseField name="created_at" type="string">
  The date and time when the task was created and queued (ISO 8601 format)
</ResponseField>

<ResponseField name="started_at" type="string">
  The date and time when the task started processing (ISO 8601 format)
</ResponseField>

<ResponseField name="finished_at" type="string">
  The date and time when the task was finished (ISO 8601 format)
</ResponseField>

<ResponseField name="expires_at" type="string">
  The date and time when the task will expire (ISO 8601 format)
</ResponseField>

<ResponseField name="message" type="string">
  A message describing the task's status or any errors that occurred
</ResponseField>

<ResponseField name="task_url" type="string">
  The presigned URL of the task
</ResponseField>

<ResponseField name="configuration" type="object">
  The task configuration including all processing settings and the input file URL
</ResponseField>

<ResponseField name="output" type="object">
  Output data (only present when task is complete)

  <Expandable title="properties">
    <ResponseField name="chunks" type="array">
      Array of processed chunks with segments
    </ResponseField>

    <ResponseField name="file_name" type="string">
      Original file name
    </ResponseField>

    <ResponseField name="page_count" type="integer">
      Number of pages in the document
    </ResponseField>

    <ResponseField name="pdf_url" type="string">
      Presigned URL to access the processed PDF
    </ResponseField>
  </Expandable>
</ResponseField>

## Status Codes

* **200**: Task created successfully
* **400**: Bad request (invalid file, invalid base64 data, unsupported file type)
* **429**: Usage limit exceeded
* **500**: Internal server error

## Examples

<CodeGroup>
  ```bash cURL (URL) theme={null}
  curl -X POST https://api.chunkr.ai/api/v1/task/parse \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "file": "https://example.com/document.pdf",
      "ocr_strategy": "Auto",
      "segmentation_strategy": "LayoutAnalysis",
      "high_resolution": true,
      "chunk_processing": {
        "target_length": 512,
        "ignore_headers_and_footers": true,
        "tokenizer": "Word"
      }
    }'
  ```

  ```bash cURL (Base64) theme={null}
  curl -X POST https://api.chunkr.ai/api/v1/task/parse \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "file": "data:application/pdf;base64,JVBERi0xLjQK...",
      "file_name": "document.pdf",
      "ocr_strategy": "All"
    }'
  ```

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

  url = "https://api.chunkr.ai/api/v1/task/parse"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "file": "https://example.com/document.pdf",
      "ocr_strategy": "Auto",
      "segmentation_strategy": "LayoutAnalysis",
      "high_resolution": True,
      "chunk_processing": {
          "target_length": 512,
          "ignore_headers_and_footers": True,
          "tokenizer": "Word"
      }
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.chunkr.ai/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,
      chunk_processing: {
        target_length: 512,
        ignore_headers_and_footers: true,
        tokenizer: 'Word'
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Notes

* The returned task will typically be in a `Starting` or `Processing` state
* Use the [GET /task/{task_id}](/api/tasks/get) endpoint to poll for completion
* Tasks have a status progression: `Starting` → `Processing` → `Succeeded` or `Failed`
* If a task expires, it cannot be accessed, updated, or viewed via the web interface