API reference · Files
Upload a file (multipart form: file, purpose); validated asynchronously
/v1/files- TypeScript
client.files.upload()- Python
client.files.upload()- CLI
hayonix files upload
Streams the file part to storage. Idempotency-Key applies to the stored content: a retry with the same key, purpose, filename and bytes returns the original file.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the file:create permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
curl -sS "$API_BASE_URL/files" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F "file=@data.jsonl" \
-F "purpose=fine-tune"Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Idempotency-Key | no | Makes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you. |
Body
A multipart form (multipart/form-data).
filefilerequiredThe file (JSON Lines; an evaluation dataset may also be CSV)
purposestringrequired`fine-tune` (training or validation data), `batch` (batch requests) or `evaluation` (an evaluation dataset)
One of
fine-tunebatchevaluation
Response
201 File — The stored file, validation pending
idstringrequiredUnique ID (`file_…`)
ID with prefix file_
objectstringrequiredAlways `file`: the type of this object
One of
filebytesintegerrequiredSize in bytes
created_atintegerrequiredUnix seconds (OpenAI shape)
filenamestringrequiredThe file name given at upload
purposestringrequired`fine-tune`, `batch` or `evaluation` for uploads; `batch_output` and `evaluation_results` for files the platform writes
statusstringrequiredOpenAI-shaped status: processed = valid, error = invalid
One of
uploadedprocessederrorstatus_detailsstring | nullrequiredFor an invalid file, the first error and how many more there are; null otherwise
expires_atinteger | nullrequiredWhen it expires (null: never) (ISO 8601, UTC)
project_idstringrequiredProject it belongs to
ID with prefix prj_
uploaded_atstring (date-time)requiredTime uploaded (ISO 8601, UTC)
sha256string | nullrequiredSHA-256 of the content, hex
content_typestring | nullrequiredMedia type of the uploaded `file` part; null when the upload gave none
validationobjectrequiredWhether the content is usable for its purpose, and why not
ShowHide 2 fields of
validationstatestringrequiredpending → running → valid | invalid
One of
pendingrunningvalidinvalidreportFileValidationReport | any JSON | nullrequiredWhat validation found; null until validation has finished
ShowHide 15 fields of
reportvalidbooleanrequiredTrue when the file has no errors and can be used for its purpose
formatstring | nullrequiredDetected format (every example shares one; `dataset` for evaluation data)
One of
chatprompt_completiontextpreferencebatch_requestsdatasetexamplesintegerrequiredLines holding an example, request or dataset row (blank lines are not counted)
linesintegerrequiredLines read, including blank lines
bytesintegerrequiredSize in bytes
token_estimateintegerrequiredEstimated tokens over all examples (characters / 4, plus template overhead)
max_example_token_estimateintegerrequiredEstimated tokens of the largest single example, to compare with a model's maximum sequence length
token_estimate_methodstringrequiredHow token counts were estimated: characters divided by 4, rounded up
One of
characters_div_4error_countintegerrequiredErrors found in the file, including those not listed in `errors`
errorsarray of objectrequiredThe first 100 errors, with 1-based line numbers
ShowHide 3 fields of
errorslineintegerrequired1-based line number in the file
codestringrequiredMachine-readable code
messagestringrequiredOne sentence for people
warningsarray of stringrequiredProblems that do not make the file invalid, such as very few training examples
truncatedbooleanrequiredValidation stopped early (too many errors)
validated_atstring (date-time)requiredTime validated (ISO 8601, UTC)
datasetobjectEvaluation datasets (purpose `evaluation`): rows and columns
ShowHide 6 fields of
datasetformatstringrequiredJSON Lines or CSV with a header row
One of
jsonlcsvrowsintegerrequiredData rows (a CSV header is not counted)
columnsarray of stringrequiredIn order of first appearance
column_rowsobjectrequiredRows that have each column
column_bytesobjectrequiredUTF-8 bytes of each column's values over all rows
max_row_bytesintegerrequiredUTF-8 bytes of the largest row
requestsobject | nullrequiredBatch files: the models and URLs the valid lines name, with how many lines name each, most used first. Null for training files (and for files validated before this existed).
ShowHide 3 fields of
requestsmodelsarray of objectrequiredModels named in the `body.model` of valid lines
urlsarray of objectrequiredRequest paths named in the `url` of valid lines
truncatedbooleanrequiredMore than 50 distinct models or URLs: only the most used are listed
Example response
{
"id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
"object": "file",
"bytes": 1,
"created_at": 1,
"filename": "string",
"purpose": "fine-tune",
"status": "uploaded",
"status_details": "string",
"expires_at": 1,
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"uploaded_at": "2026-01-01T00:00:00.000Z",
"sha256": "string",
"content_type": "string",
"validation": {
"state": "pending",
"report": {
"valid": true,
"format": "chat",
"examples": 1,
"lines": 1,
"bytes": 1,
"token_estimate": 1,
"max_example_token_estimate": 1,
"token_estimate_method": "characters_div_4",
"error_count": 1,
"errors": [
{
"line": 1,
"code": "string",
"message": "string"
}
],
"warnings": [
"string"
],
"truncated": true,
"validated_at": "2026-01-01T00:00:00.000Z",
"dataset": {
"format": "jsonl",
"rows": 1,
"columns": [
"string"
],
"column_rows": {},
"column_bytes": {},
"max_row_bytes": 1
},
"requests": {
"models": [
{
"model": null,
"lines": null
}
],
"urls": [
{
"url": null,
"lines": null
}
],
"truncated": true
}
}
}
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
409 | conflict_error idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_error idempotency_key_reused | The Idempotency-Key was used with a different request. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |