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:

Authorization: Bearer YOUR_API_KEY

Path Parameters

task_id · string · required

The unique identifier of the task to update

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.

ocr_strategy · 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

segmentation_strategy · enum

Controls the segmentation strategy:

• LayoutAnalysis: Analyzes pages for layout elements
• Page: Treats each page as a single segment

high_resolution · boolean

Whether to use high-resolution images for cropping and post-processing

expires_in · integer

The number of seconds until task is deleted

error_handling · enum

Controls how errors are handled:

• Fail: Stops processing on any error
• Continue: Attempts to continue despite non-critical errors

chunk_processing · object

Controls the settings for chunking and post-processing.

Show properties

target_length · integer

The target number of words in each chunk

ignore_headers_and_footers · boolean

Whether to ignore headers and footers in the chunking process

tokenizer · string | enum

The tokenizer to use for the chunking process

segment_processing · object

Controls the post-processing of each segment type. Each segment type can be configured independently.

Show properties

Each segment type (Title, SectionHeader, Text, ListItem, Table, Picture, Caption, Formula, Footnote, PageHeader, PageFooter, Page) can have:

crop_image · enum

Image cropping strategy

format · enum

Output format: Html or Markdown

strategy · enum

Content generation strategy: Auto or LLM

llm · string

Custom prompt for LLM processing

embed_sources · array

Content sources to include in the chunk’s embed field

extended_context · boolean

Use full page image as context for LLM generation

llm_processing · object

Controls the LLM used for the task.

Show properties

model_id · string

The ID of the model to use

fallback_strategy · enum | object

Fallback strategy: None, Default, or Model(string)

max_completion_tokens · integer

Maximum number of tokens to generate

temperature · number

Temperature for LLM generation

Response

The response is identical to the Create Task response, with the task in Starting or Processing state.

task_id · string

The same task ID (tasks are updated in place)

status · enum

Will typically be Starting or Processing after update

created_at · string

Original creation timestamp (unchanged)

started_at · string

New start timestamp for the reprocessing

finished_at · string

Will be null while reprocessing

configuration · object

Updated configuration with new settings merged with existing ones

message · string

Status message about the update

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

cURL (Change OCR Strategy)

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"
  }'

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