---
title: "Initiate a batch upload"
method: POST
path: "/api/v1/datasets/upload/initiate-batch"
tags: ["Dataset"]
---

# Initiate a batch upload

`POST /api/v1/datasets/upload/initiate-batch`

## Request

- The document declares no server URL.
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/adaptionlabs/apis/adaption-api/docs/api/v1/datasets/upload/initiate-batch/post.ts> (a function with typed inputs; its response is checked against the schema)

Initiate a batch upload. A batch must be homogeneous: either all document formats (pdf, docx, pptx, xlsx, html, zip) or all tabular formats (csv, json, jsonl, parquet). Mixed batches are rejected. TXT files are permissive and may be included in either kind of batch (or alone, in which case the dataset is tabular); their contents are converted during complete-batch.

## Request body

- InitiateBatchDto
  - `name` string, required: Human-readable name for the dataset
  - `files` InitiateBatchFileDto[], required: List of files to upload. A single batch must be homogeneous: either all document formats (pdf, docx, pptx, xlsx, html, zip) or all tabular formats (csv, json, jsonl, parquet). Mixing the two is rejected because the two pipelines use different credit models and preprocessing stages. TXT files are permissive: they may be included in either kind of batch (or alone, producing a tabular dataset). complete-batch converts TXT contents to csv/jsonl and merges them into the resulting dataset.
    - `file_name` string, required: Original file name
    - `file_format` 'csv' | 'json' | 'jsonl' | 'parquet' | 'pdf' | 'docx' | 'pptx' | 'xlsx' | 'html' | 'zip' | 'txt', required: Format of the file
    - `file_size_bytes` number, required: File size in bytes

## Response `default`

- InitiateBatchResponseDto
  - `dataset_id` string, required: Dataset ID
  - `uploads` InitiateBatchUploadDto[], required
    - `file_name` string, required: Original file name
    - `upload_url` string, required: Presigned S3 upload URL
    - `s3_key` string, required: S3 key for the uploaded file

## Changes

- **2026-10-20** `7398ff1eeeba`: 1 warning
  - removed the request property `defer_adaption`

[Operation history](https://skmtc.dev/adaptionlabs/apis/adaption-api/changes/api/v1/datasets/upload/initiate-batch/post.md)

---

[API](https://skmtc.dev/adaptionlabs/apis/adaption-api.md) - [All operations](https://skmtc.dev/adaptionlabs/apis/adaption-api/llms.txt) - [OpenAPI document](https://skmtc.dev/adaptionlabs/apis/adaption-api/revisions/d4cf908c19a0?raw)