Files

Files hold the datasets you train and evaluate on. Upload a JSONL file once, then reference its ID from fine-tuning jobs and evaluations instead of pushing rows over HTTP on every call. A connected source writes its files here automatically, one per refresh, so a system you already run keeps its dataset current for you.

Every uploaded file is validated line by line before it can be used. Validation runs asynchronously: a new file starts in validating and moves to ready or error. Poll Retrieve a dataset until validation completes before submitting a job.

Upload a dataset

POST/v1/filesscope: train

Uploads a JSONL dataset. The request is multipart/form-data, so any HTTP client and most upload libraries work without special handling.

Each line must be a complete JSON object. For fine-tune files in the chat format, every line carries a messages array; validation checks structure, roles and encoding and reports the line number of anything it rejects.

Body (multipart/form-data)

filefilerequired

The JSONL file to upload.

purposestring

What the file is for: fine-tune, evaluation or retrieval. A retrieval file holds the query and passage pairs an embedding or reranking model is fine-tuned on.

project_idstring

Attach the file to a project. Keys bound to a different project cannot read it.

Uploading is not idempotent: retrying a timed-out request can create a duplicate file. Send an Idempotency-Key header if your client retries automatically. See Errors and retries.

curl https://api.nucleus-ai.io/v1/files \
  -H "Authorization: Bearer $NUCLEUS_API_KEY" \
  -F purpose=fine-tune \
  -F [email protected]

201 Created

{
  "id": "file_9fQ2x",
  "bytes": 4823910,
  "lines": 12480,
  "purpose": "fine-tune",
  "status": "validating",
  "created_at": "2026-07-27T09:14:02Z"
}

List datasets

GET/v1/filesscope: read

Returns your uploaded files, newest first. See Pagination for how limit, offset and the cursor object behave across list endpoints.

Query parameters

purposestring

Filter to fine-tune, evaluation or retrieval files.

limitinteger

Maximum number of files to return.

offsetinteger

Number of files to skip from the start of the list.

curl "https://api.nucleus-ai.io/v1/files?purpose=fine-tune" \
  -H "Authorization: Bearer $NUCLEUS_API_KEY"

200 OK

{
  "data": [
    {
      "id": "file_9fQ2x",
      "lines": 12480,
      "status": "ready"
    }
  ],
  "cursor": { "offset": 0, "total_count": 7 }
}

Retrieve a dataset

GET/v1/files/{file_id}scope: read

Returns one file, including its validation state. When validation fails, errors lists each rejected line with its line number and the reason, so you can fix the export script before spending GPU time on a bad dataset.

Path parameters

file_idstringrequired

ID of the file, from the upload response.

curl https://api.nucleus-ai.io/v1/files/file_9fQ2x \
  -H "Authorization: Bearer $NUCLEUS_API_KEY"

200 OK

{
  "id": "file_9fQ2x",
  "status": "error",
  "errors": [
    {
      "line": 812,
      "message": "messages[2].role must be assistant"
    }
  ]
}

Delete a dataset

DELETE/v1/files/{file_id}scope: train

Permanently deletes an uploaded dataset. Use this to honour data-erasure requests: once deleted, the file's contents are gone and its ID can no longer be referenced by new jobs or evaluations.