---
title: "Get Upload Url"
method: POST
path: "/v1/datasets/upload/url"
tags: ["datasets"]
---

# Get Upload Url

`POST /v1/datasets/upload/url`

## Request

- Base URL: `https://api.fastino.ai`
- URL: `https://api.fastino.ai/v1/datasets/upload/url`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/fastino-ai/apis/pioneer-inference-api/docs/v1/datasets/upload/url/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a reserved dataset row and presigned upload URL.

## Request body

- DatasetUploadUrlRequest: Request to get presigned URL for dataset upload (bypasses API Gateway limits).
  - `column_mapping` object, nullable: Column mapping from source to standard names (e.g., {"sentence": "text", "category": "label"}). Valid standard targets: text, label, labels, entities.
  - `content_length` integer, nullable: Exact size in bytes of the file you will PUT, at most 5 GiB (one S3 PUT). When set, presigned_url is signed for this Content-Length, and storage refuses a body of any other size.
  - `dataset_name` string, required: Name for the dataset, 1 to 128 characters. It must not be blank, contain '/', '\', '<', '>' or control characters, or be '.' or '..': such a name cannot be fetched or deleted by name afterwards.
  - `dataset_type` 'classification' | 'ner' | 'custom' | 'decoder': Type of dataset
  - `experiment_id` string, nullable: Optional Experiment ID (UUID) the upload was started from. The dataset is linked to the experiment when the caller has access.
  - `filename` string, nullable: Original filename (used for format detection if format not provided)
  - `format` 'jsonl' | 'csv' | 'tsv' | 'parquet' | 'json', nullable: File format (auto-detected from filename if not provided)
  - `generation_type` 'upload', nullable: Public uploads are always recorded as upload. Other generation methods are assigned by server-owned workflows.
  - `project_id` string, nullable: Optional project ID (UUID) to assign this dataset to
  - `schema` string, nullable: Expected schema as JSON object (e.g., {"age": "Int64", "name": "Utf8"}). Enforces column types during parsing. Valid types: Int8, Int16, Int32, Int64, UInt8-64, Float32, Float64, Utf8, Boolean, Date, Datetime, Time, Duration, Categorical, Binary
  - `sha256` string, nullable: Hex sha256 of the file you will PUT. When set, presigned_url is signed for its x-amz-checksum-sha256, and storage refuses bytes with another digest.
  - `split_ratio` object, nullable: Split ratio when type is 'split', e.g. {'training': 0.8, 'evaluation': 0.2}
  - `type` 'training' | 'evaluation' | 'benchmark', nullable: Dataset purpose: 'training' (trainable), 'evaluation' (not trainable), 'benchmark' (system-managed, evaluation-only; cannot be trained on or directly accessed).
  - `visibility` 'private' | 'public', nullable: Dataset visibility: 'private' (owner only) or 'public' (anyone can see)

## Response `200`

Successful Response

- DatasetUploadUrlResponse: Response with presigned S3 URL for direct upload.
  - `dataset_id` string, required: Dataset ID for subsequent processing
  - `dataset_name` string, required: Dataset name (for polling status via GET /{name}/{version})
  - `expires_in` integer, required: URL expiration time in seconds
  - `presigned_url` string, required: S3 presigned URL for PUT upload
  - `upload_headers` object, required: Headers the PUT to presigned_url must send, with exactly these values. They are part of the URL's signature, so storage answers 403 when one is missing or different. Always holds Content-Type: application/octet-stream; also Content-Length and x-amz-checksum-sha256 when the request declared content_length and sha256. Most HTTP clients set Content-Length from the body.
  - `upload_instructions` string: Instructions for completing the upload
  - `version_number` string, required: Version number for this dataset

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-17** `81465e18c1d2`: 1 breaking, 1 warning, 2 info
  - request property `visibility/anyOf[subschema #1]/` was restricted to a list of enum values
  - the `dataset_name` request property's maxLength was set to `128`
  - added the new `private` enum value to the request property `visibility/anyOf[subschema #1]/`
  - added the new `public` enum value to the request property `visibility/anyOf[subschema #1]/`
- **2026-10-15** `ef285860f952`: 4 info
  - added the new optional request property `content_length`
  - added the new optional request property `sha256`
  - the `upload_instructions` response's property default value changed from `Upload file via HTTP PUT to presigned_url, then call /datasets/upload/process with dataset_id, format, and schema (if applicable)` to `PUT the raw file bytes to presigned_url and send every header in upload_headers with exactly its value: always Content-Type: application/octet-stream, plus Content-Length and x-amz-checksum-sha256 when listed. A missing or different header is refused with 403. Then call POST /datasets/upload/process with dataset_id.` for the status `200`
  - added the required property `upload_headers` to the response with the `200` status
- **2026-10-12** `43d7e06a824b`: 1 breaking
  - the `dataset_name` request property's minLength was increased from `0` to `1`
- …earlier changes not shown

[Operation history](https://skmtc.dev/fastino-ai/apis/pioneer-inference-api/changes/v1/datasets/upload/url/post.md)

---

[API](https://skmtc.dev/fastino-ai/apis/pioneer-inference-api.md) - [All operations](https://skmtc.dev/fastino-ai/apis/pioneer-inference-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fastino-ai/apis/pioneer-inference-api/revisions/81465e18c1d2?raw)