---
title: "Add files to store in a batch"
method: POST
path: "/v1/stores/{store_identifier}/file_batches"
tags: ["stores"]
---

# Add files to store in a batch

`POST /v1/stores/{store_identifier}/file_batches`

## Request

- Base URL: `https://api.mixedbread.com`
- URL: `https://api.mixedbread.com/v1/stores/{store_identifier}/file_batches`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/mixedbread/apis/mxbai-omni/docs/v1/stores/:store_identifier/file_batches/post.ts> (a function with typed inputs; its response is checked against the schema)

Add already uploaded files to a store in one call, for backfills.

Each item takes one token from a rate limit of its own, at the same limits as file uploads. A
batch never replaces a file: one already in the store (same file ID or external ID), in any
status, comes back with `store_file_already_exists_error`. To retry a failed file, delete it
first; to update a file, use the single-file endpoint. Each item is checked on its own: one
rejected item is reported in `data` without failing the others.

## Path parameters

- `store_identifier` union, required: The ID or name of the store
  - string
  - string, uuid

## Request body

- StoreFileBatchCreateParams: Files to add to a store in one call, billed and queued as backfill.
  - `files` StoreFileBatchItem[], required: Files to add
    - `file_id` string, uuid, required: ID of the file to add
    - `external_id` string, nullable: External identifier for this file in the store
    - `metadata` unknown
    - `config` StoreFileConfig: Configuration for a file.
      - `parsing_strategy` 'fast' | 'high_quality': Strategy for adding a file to a store.

## Response `201`

The outcome of each file

- StoreFileBatch: Outcome of adding a batch of files to a store.
  - `data` StoreFileBatchItemResult[], required: Outcome of each item, in request order
    - `file_id` string, required: ID of the file the item named
    - `external_id` string, nullable: External identifier the item named
    - `status` 'pending' | 'in_progress' | 'cancelled' | 'completed' | 'failed': The lifecycle of a unit of background work. One vocabulary for every job family. The database keeps a separate enum type per table (``parsing_job_status``, ``store_file_status``, ...) but they all carry these values, so the aliases below are this enum rather than copies of it. :class:`SyncStatus` is this set plus ``IDLE`` for connectors, which have a resting state between runs.
    - `error` StoreFileBatchItemError: Why an item was not added, with the error code the single-file endpoint returns.
      - `code` string, required: Error code
      - `message` string, required: Error message
  - `object` 'store.file_batch': Type of the object

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-05** `34178430bca8`: 1 info
  - added the optional property `data/items/external_id` to the response with the `201` status
- **2026-11-05** `8f1e178ecacc`: 1 warning
  - removed the optional property `data/items/store_file_id` from the response with the `201` status
- **2026-11-05** `0590234e8eb7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mixedbread/apis/mxbai-omni/changes/v1/stores/:store_identifier/file_batches/post.md)

---

[API](https://skmtc.dev/mixedbread/apis/mxbai-omni.md) - [All operations](https://skmtc.dev/mixedbread/apis/mxbai-omni/llms.txt) - [OpenAPI document](https://skmtc.dev/mixedbread/apis/mxbai-omni/revisions/6edf057e7503?raw)