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

# Update Task

> Update an existing task's configuration and reprocess the document

## Endpoint

```
PATCH /api/v1/task/{task_id}/parse
```

## Authentication

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

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

## Path Parameters

<ParamField path="task_id" type="string" required>
  The unique identifier of the task to update
</ParamField>

## Requirements

* Task must have status `Succeeded` or `Failed`
* New configuration must be different from the current configuration
* Task must not be expired

## Request Body

The request body is JSON with optional configuration fields. Any fields not provided will retain their values from the original task configuration.

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

  * `All`: Processes all pages with OCR
  * `Auto`: Selectively applies OCR only to pages with missing or low-quality text
</ParamField>

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

  * `LayoutAnalysis`: Analyzes pages for layout elements
  * `Page`: Treats each page as a single segment
</ParamField>

<ParamField body="high_resolution" type="boolean">
  Whether to use high-resolution images for cropping and post-processing
</ParamField>

<ParamField body="expires_in" type="integer">
  The number of seconds until task is deleted
</ParamField>

<ParamField body="error_handling" type="enum">
  Controls how errors are handled:

  * `Fail`: Stops processing on any error
  * `Continue`: Attempts to continue despite non-critical errors
</ParamField>

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

  <Expandable title="properties">
    <ParamField body="target_length" type="integer">
      The target number of words in each chunk
    </ParamField>

    <ParamField body="ignore_headers_and_footers" type="boolean">
      Whether to ignore headers and footers in the chunking process
    </ParamField>

    <ParamField body="tokenizer" type="string | enum">
      The tokenizer to use for the chunking process
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="segment_processing" type="object">
  Controls the post-processing of each segment type. Each segment type can be configured independently.

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

    <ParamField body="crop_image" type="enum">
      Image cropping strategy
    </ParamField>

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

    <ParamField body="strategy" type="enum">
      Content generation strategy: `Auto` or `LLM`
    </ParamField>

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

    <ParamField body="embed_sources" type="array">
      Content sources to include in the chunk's embed field
    </ParamField>

    <ParamField body="extended_context" type="boolean">
      Use 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
    </ParamField>

    <ParamField body="fallback_strategy" type="enum | object">
      Fallback strategy: `None`, `Default`, or `Model(string)`
    </ParamField>

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

    <ParamField body="temperature" type="number">
      Temperature for LLM generation
    </ParamField>
  </Expandable>
</ParamField>

## Response

The response is identical to the [Create Task](/api/tasks/create) response, with the task in `Starting` or `Processing` state.

<ResponseField name="task_id" type="string">
  The same task ID (tasks are updated in place)
</ResponseField>

<ResponseField name="status" type="enum">
  Will typically be `Starting` or `Processing` after update
</ResponseField>

<ResponseField name="created_at" type="string">
  Original creation timestamp (unchanged)
</ResponseField>

<ResponseField name="started_at" type="string">
  New start timestamp for the reprocessing
</ResponseField>

<ResponseField name="finished_at" type="string">
  Will be null while reprocessing
</ResponseField>

<ResponseField name="configuration" type="object">
  Updated configuration with new settings merged with existing ones
</ResponseField>

<ResponseField name="message" type="string">
  Status message about the update
</ResponseField>

## Status Codes

* **200**: Task updated and reprocessing started successfully
* **400**: Bad request (task cannot be updated, invalid configuration, task in wrong state)
* **404**: Task not found
* **429**: Usage limit exceeded
* **500**: Internal server error

## Examples

<CodeGroup>
  ```bash cURL (Change OCR Strategy) theme={null}
  curl -X PATCH "https://api.chunkr.ai/api/v1/task/123e4567-e89b-12d3-a456-426614174000/parse" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "ocr_strategy": "All"
    }'
  ```

  ```bash cURL (Update Chunking) theme={null}
  curl -X PATCH "https://api.chunkr.ai/api/v1/task/123e4567-e89b-12d3-a456-426614174000/parse" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "chunk_processing": {
        "target_length": 1024,
        "tokenizer": "Cl100kBase"
      }
    }'
  ```

  ```bash cURL (Multiple Changes) theme={null}
  curl -X PATCH "https://api.chunkr.ai/api/v1/task/123e4567-e89b-12d3-a456-426614174000/parse" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "ocr_strategy": "Auto",
      "segmentation_strategy": "LayoutAnalysis",
      "high_resolution": true,
      "chunk_processing": {
        "target_length": 768
      },
      "segment_processing": {
        "Table": {
          "format": "Markdown"
        }
      }
    }'
  ```

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

  task_id = "123e4567-e89b-12d3-a456-426614174000"
  url = f"https://api.chunkr.ai/api/v1/task/{task_id}/parse"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  # Update configuration
  payload = {
      "ocr_strategy": "Auto",
      "chunk_processing": {
          "target_length": 1024,
          "tokenizer": "Cl100kBase"
      }
  }

  response = requests.patch(url, json=payload, headers=headers)
  updated_task = response.json()

  print(f"Task updated: {updated_task['task_id']}")
  print(f"New status: {updated_task['status']}")
  ```

  ```javascript JavaScript theme={null}
  const taskId = '123e4567-e89b-12d3-a456-426614174000';
  const response = await fetch(
    `https://api.chunkr.ai/api/v1/task/${taskId}/parse`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        ocr_strategy: 'Auto',
        chunk_processing: {
          target_length: 1024,
          tokenizer: 'Cl100kBase'
        }
      })
    }
  );

  const updatedTask = await response.json();
  console.log('Task updated:', updatedTask.task_id);
  console.log('New status:', updatedTask.status);
  ```
</CodeGroup>

## Behavior Notes

1. **Partial Updates**: Only specify the fields you want to change. All other configuration values will be preserved from the original task.

2. **Status Requirements**: The task must be in `Succeeded` or `Failed` state. Tasks that are `Starting`, `Processing`, or `Cancelled` cannot be updated.

3. **Reprocessing**: The update triggers a complete reprocessing of the document with the new configuration. The original input file is reused.

4. **Same Task ID**: The task keeps the same ID - it's updated in place rather than creating a new task.

5. **Configuration Validation**: If the LLM processing configuration is outdated or invalid, you'll receive an error asking you to update it.

6. **Cost Implications**: Updating a task counts toward your usage limits as it reprocesses the entire document.

## Common Error Messages

* `"Task not found"` - Task ID doesn't exist or has expired
* `"Task cannot be updated"` - Task is not in `Succeeded` or `Failed` state
* `"Usage limit exceeded"` - Your account has reached its processing limit
* `"The LLM processing configuration is probably outdated"` - LLM configuration needs updating