---
title: "Upload File"
method: POST
path: "/api/file"
tags: ["File"]
---

# Upload File

`POST /api/file`

Upload a file to S3 bucket attached to your dataset. You can select between a naive chunking strategy where the text is extracted with Apache Tika and split into segments with a target number of segments per chunk OR you can use a vision LLM to convert the file to markdown and create chunks per page. You must specifically use a base64url encoding. Auth'ed user must be an admin or owner of the dataset's organization to upload a file.

## Headers

- `TR-Dataset` string, uuid, required

## Request body

- UploadFileReqPayload
  - `base64_file` string, required — Base64 encoded file.
  - `chunkr_create_task_req_payload` CreateFormWithoutFile — Will use [chunkr.ai](https://chunkr.ai) to process the file when this object is defined. See [docs.chunkr.ai/api-references/task/create-task](https://docs.chunkr.ai/api-references/task/create-task) for detailed information about what each field on this request payload does.
    - `chunk_processing` ChunkProcessing — Controls the setting for the chunking and post-processing of each chunk.
      - `ignore_headers_and_footers` boolean — Whether to ignore headers and footers in the chunking process. This is recommended as headers and footers break reading order across pages.
      - `target_length` integer — The target number of words in each chunk. If 0, each chunk will contain a single segment.
      - `tokenizer` union — Specifies which tokenizer to use for the chunking process. This type supports two ways of specifying a tokenizer: 1. Using a predefined tokenizer from the `Tokenizer` enum 2. Using any Hugging Face tokenizer by providing its model ID as a string (e.g. "facebook/bart-large", "Qwen/Qwen-tokenizer", etc.) When using a string, any valid Hugging Face tokenizer ID can be specified, which will be loaded using the Hugging Face tokenizers library.
        - object
          - `Enum` 'Word' | 'Cl100kBase' | 'XlmRobertaBase' | 'BertBaseUncased', required — Common tokenizers used for text processing. These values represent standard tokenization approaches and popular pre-trained tokenizers from the Hugging Face ecosystem.
        - object
          - `String` string, required — Use any Hugging Face tokenizer by specifying its model ID Examples: "Qwen/Qwen-tokenizer", "facebook/bart-large"
    - `error_handling` 'Fail' | 'Continue' — 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 (eg. LLM refusals etc.)
    - `expires_in` integer, nullable — The number of seconds until task is deleted. Expried tasks can **not** be updated, polled or accessed via web interface.
    - `high_resolution` boolean, nullable — Whether to use high-resolution images for cropping and post-processing. (Latency penalty: ~7 seconds per page)
    - `llm_processing` LlmProcessing — Controls the LLM used for the task.
      - `fallback_strategy` union — Specifies the fallback strategy for LLM processing This can be: 1. None - No fallback will be used 2. Default - The system default fallback model will be used 3. Model - A specific model ID will be used as fallback (check the documentation for the models.)
        - 'None' — No fallback will be used
        - 'Default' — Use the system default fallback model
        - object
          - `Model` string, required — Use a specific model as fallback
      - `max_completion_tokens` integer, nullable — The maximum number of tokens to generate.
      - `model_id` string, nullable — The ID of the model to use for the task. If not provided, the default model will be used. Please check the documentation for the model you want to use.
      - `temperature` number, float — The temperature to use for the LLM.
    - `ocr_strategy` 'All' | 'Auto' — 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.
    - `pipeline` 'Azure' | 'Chunkr'
    - `segment_processing` SegmentProcessing — Controls the post-processing of each segment type. Allows you to generate HTML and Markdown from chunkr models for each segment type. By default, the HTML and Markdown are generated manually using the segmentation information except for `Table`, `Formula` and `Picture`. You can optionally configure custom LLM prompts and models to generate an additional `llm` field with LLM-processed content for each segment type. The configuration of which content sources (HTML, Markdown, LLM, Content) of the segment should be included in the chunk's `embed` field and counted towards the chunk length can be configured through the `embed_sources` setting.
      - `Caption` AutoGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM mode
        - `markdown` 'LLM' | 'Auto'
      - `Footnote` AutoGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM mode
        - `markdown` 'LLM' | 'Auto'
      - `Formula` LlmGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM model
        - `markdown` 'LLM' | 'Auto'
      - `ListItem` AutoGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM mode
        - `markdown` 'LLM' | 'Auto'
      - `Page` LlmGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM model
        - `markdown` 'LLM' | 'Auto'
      - `PageFooter` AutoGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM mode
        - `markdown` 'LLM' | 'Auto'
      - `PageHeader` AutoGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM mode
        - `markdown` 'LLM' | 'Auto'
      - `Picture` PictureGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM model
        - `markdown` 'LLM' | 'Auto'
      - `SectionHeader` AutoGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM mode
        - `markdown` 'LLM' | 'Auto'
      - `Table` LlmGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM model
        - `markdown` 'LLM' | 'Auto'
      - `Text` AutoGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM mode
        - `markdown` 'LLM' | 'Auto'
      - `Title` AutoGenerationConfig — Controls the processing and generation for the segment. - `crop_image` controls whether to crop the file's images to the segment's bounding box. The cropped image will be stored in the segment's `image` field. Use `All` to always crop, or `Auto` to only crop when needed for post-processing. - `html` is the HTML output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `llm` is the LLM-generated output for the segment, this uses off-the-shelf models to generate a custom output for the segment - `markdown` is the Markdown output for the segment, generated either through huerstics (`Auto`) or using Chunkr fine-tuned models (`LLM`) - `embed_sources` defines which content sources will be included in the chunk's embed field and counted towards the chunk length. The array's order determines the sequence in which content appears in the embed field (e.g., [Markdown, LLM] means Markdown content is followed by LLM content). This directly affects what content is available for embedding and retrieval.
        - `crop_image` 'All' | 'Auto' — Controls the cropping strategy for an item (e.g. segment, chunk, etc.) - `All` crops all images in the item - `Auto` crops images only if required for post-processing
        - `embed_sources` EmbedSource[]
        - `html` 'LLM' | 'Auto'
        - `llm` string, nullable — Prompt for the LLM mode
        - `markdown` 'LLM' | 'Auto'
    - `segmentation_strategy` 'LayoutAnalysis' | 'Page' — 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. (Latency penalty: ~TBD seconds per page). - `Page`: Treats each page as a single segment. Faster processing, but without layout element detection and only simple chunking.
  - `create_chunks` boolean, nullable — Create chunks is a boolean which determines whether or not to create chunks from the file. If false, you can manually chunk the file and send the chunks to the create_chunk endpoint with the file_id to associate chunks with the file. Meant mostly for advanced users.
  - `description` string, nullable — Description is an optional convience field so you do not have to remember what the file contains or is about. It will be included on the group resulting from the file which will hold its chunk.
  - `file_name` string, required — Name of the file being uploaded, including the extension.
  - `group_tracking_id` string, nullable — Group tracking id is an optional field which allows you to specify the tracking id of the group that is created from the file. Chunks created will be created with the tracking id of `group_tracking_id|<index of chunk>`
  - `link` string, nullable — Link to the file. This can also be any string. This can be used to filter when searching for the file's resulting chunks. The link value will not affect embedding creation.
  - `metadata` unknown
  - `pdf2md_options` Pdf2MdOptions — We plan to deprecate pdf2md in favor of chunkr.ai. This is a legacy option for using a vision LLM to convert a given file into markdown and then ingest it.
    - `split_headings` boolean, nullable — Split headings is an optional field which allows you to specify whether or not to split headings into separate chunks. Default is false.
    - `system_prompt` string, nullable — Prompt to use for the gpt-4o model. Default is None.
    - `use_pdf2md_ocr` boolean, required — Parameter to use pdf2md_ocr. If true, the file will be converted to markdown using gpt-4o. Default is false.
  - `rebalance_chunks` boolean, nullable — Rebalance chunks is an optional field which allows you to specify whether or not to rebalance the chunks created from the file. If not specified, the default true is used. If true, Trieve will evenly distribute remainder splits across chunks such that 66 splits with a `target_splits_per_chunk` of 20 will result in 3 chunks with 22 splits each.
  - `split_avg` boolean, nullable — Split average will automatically split your file into multiple chunks and average all of the resulting vectors into a single output chunk. Default is false. Explicitly enabling this will cause each file to only produce a single chunk.
  - `split_delimiters` string[], nullable — Split delimiters is an optional field which allows you to specify the delimiters to use when splitting the file before chunking the text. If not specified, the default [.!?\n] are used to split into sentences. However, you may want to use spaces or other delimiters.
  - `tag_set` string[], nullable — Tag set is a comma separated list of tags which will be passed down to the chunks made from the file. Tags are used to filter chunks when searching. HNSW indices are created for each tag such that there is no performance loss when filtering on them.
  - `target_splits_per_chunk` integer, nullable — Target splits per chunk. This is an optional field which allows you to specify the number of splits you want per chunk. If not specified, the default 20 is used. However, you may want to use a different number.
  - `time_stamp` string, nullable — Time stamp should be an ISO 8601 combined date and time without timezone. Time_stamp is used for time window filtering and recency-biasing search results. Will be passed down to the file's chunks.
  - `webhook_url` string, nullable — Optional webhook URL to receive notifications for each page processed.

## Response `200`

Confirmation that the file is uploading

- UploadFileResponseBody
  - `file_metadata` File, required
    - `created_at` string, date-time, required
    - `dataset_id` string, uuid, required
    - `file_name` string, required
    - `id` string, uuid, required
    - `link` string, nullable
    - `metadata` unknown
    - `size` integer, required
    - `tag_set` string[], nullable
    - `time_stamp` string, date-time, nullable
    - `updated_at` string, date-time, required

## Other responses

- `400` — Service error relating to uploading the file

---

[API](https://skmtc.net/devflowinc/apis/trieve-api.md) · [All operations](https://skmtc.net/devflowinc/apis/trieve-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/devflowinc/trieve-api/versions/84583e7c9fc1/schema)