Create Evaluation Upload

POST

https://api.captain.dev/v3/collections/:collection_name/evals/uploads

POST

/v3/collections/:collection_name/evals/uploads

import os
import requests
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
COLLECTION_NAME = "customer_forms"
PATH = "payments-eval-2026-09-12.ndjson"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
response = requests.post(
    f"{BASE_URL}/v3/collections/{COLLECTION_NAME}/evals/uploads",
    headers=headers,
    json={
        "filename": PATH,
        "byte_size": os.path.getsize(PATH),
        "content_type": "application/x-ndjson",
    },
    timeout=60.0,
)
upload = response.json()
# Send the file to the minted URL with exactly the headers it returned.
with open(PATH, "rb") as f:
    requests.put(upload["upload_url"], headers=upload["headers"], data=f, timeout=300.0)
print(upload["upload_id"], upload["expires_at"])

{
  "byte_size": 1842,
  "collection_name": "customer_forms",
  "expires_at": "2026-09-12T17:45:00Z",
  "filename": "payments-eval-2026-09-12.ndjson",
  "headers": {
    "Content-Length": "1842",
    "Content-Type": "application/x-ndjson"
  },
  "upload_id": "evu_019b4c2e7a3f70d2a91c4e8b6f1023aa",
  "upload_url": "https://uploads.captainusercontent.com/evals/org_example/evu_019b4c2e7a3f70d2a91c4e8b6f1023aa.ndjson?sig=example"
}

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 cannot point the same upload_id at a different one. Line format and limits are on the Evaluations guide.

Path parameters

collection_namestringRequired

Request

This endpoint expects an object.

byte_sizeintegerRequired1-52428800

Exact number of bytes the PUT will send. Enforced on PUT.

filenamestringRequired8-512 characters

Must end in .ndjson.

content_typeenumOptionalDefaults to application/x-ndjson

Allowed values:

Response

Upload minted. PUT the file to upload_url before expires_at.

byte_sizeinteger

collection_namestring

expires_atstring

filenamestring

headersobject

upload_idstring

upload_urlstring

Signed, PUT-only, single-use URL on *.captainusercontent.com. Opaque.

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error