---
title: "Create Evaluation Upload"
method: POST
path: "/v3/collections/{collection_name}/evals/uploads"
tags: ["file-search"]
---

# Create Evaluation Upload

`POST /v3/collections/{collection_name}/evals/uploads`

Mint a single-use upload URL for an evaluation set. PUT the raw `.ndjson` bytes to `upload_url` with exactly the returned `headers` (no `Authorization`); the URL accepts one PUT of exactly `byte_size` bytes, then expires. Files are at most 10,000 lines and 50 MB. The upload is bound to this collection, so a later [Create Eval](/reference/evals/create) cannot point the same `upload_id` at a different one. Line format and limits are on the [Evaluations](/guides/evaluations) guide.

## Path parameters

- `collection_name` string, required

## Request body

- EvalUploadRequestV3
  - `byte_size` integer, required — Exact number of bytes the PUT will send. Enforced on PUT.
  - `content_type` 'application/x-ndjson' | 'application/jsonl' | 'application/octet-stream'
  - `filename` string, required — Must end in `.ndjson`.

## Response `200`

Upload minted. PUT the file to `upload_url` before `expires_at`.

- EvalUploadResponseV3
  - `byte_size` integer, required
  - `collection_name` string, required
  - `expires_at` string, required
  - `filename` string, required
  - `headers` EvalUploadHeadersV3, required
    - `Content-Length` string, required
    - `Content-Type` string, required
  - `upload_id` string, required
  - `upload_url` string, required — Signed, PUT-only, single-use URL on *.captainusercontent.com. Opaque.

## Other responses

- `401` — Missing or invalid authentication.
- `403` — API key does not have the query permission for this collection.
- `404` — Collection not found (or an eval / upload that belongs to another organization: no existence oracle).
- `422` — The body failed validation: `filename` does not end in `.ndjson` or is outside 8 to 512 characters, `byte_size` is outside 1 to 52,428,800, or `content_type` is not an accepted value.
- `429` — Too many unconsumed upload URLs for this collection (`TOO_MANY_PENDING_UPLOADS`); PUT to one or let it expire.

## Changes

- **2026-09-24** `61a9364ad042` — 4 breaking, 18 info
  - the response's body type changed from no type to `object` for status `401`
  - the response's body type changed from no type to `object` for status `403`
  - the response's body type changed from no type to `object` for status `404`
  - the response's body type changed from no type to `object` for status `429`
  - …18 more
- **2026-09-16** `e82391fa5b0b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/runcaptain/apis/api-reference/changes/v3/collections/:collection_name/evals/uploads/post.md)

---

[API](https://skmtc.dev/runcaptain/apis/api-reference.md) · [All operations](https://skmtc.dev/runcaptain/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/runcaptain/apis/api-reference/revisions/ac61e472bb7d?raw)