Files API - ZeroGPU

Upload file

POST /v1/files, attach JSONL with purpose=batch.

List files

GET /v1/files, filter by purpose, paginate with after.

Retrieve file

GET /v1/files/{file_id}, metadata only.

Download file

GET /v1/files/{file_id}/content, raw JSONL body.

Delete file

DELETE /v1/files/{file_id}, soft-delete.

Wire-compatible with OpenAI’s /v1/files, with these ZeroGPU specifics:

Only purpose=batch is accepted on upload. Server-written output files (both successes and errors) carry purpose=batch_output; error files are additionally tagged with the ZeroGPU-specific is_error: true flag on the File object.
Authentication uses x-api-key + x-project-id headers instead of a Bearer token.
Files are soft-deleted (the row is preserved for audit; the object is removed from storage immediately).

Endpoint summary

Method	Path	Purpose
POST	`/v1/files`	Upload a JSONL file
GET	`/v1/files`	List your project’s files
GET	`/v1/files/{file_id}`	Retrieve metadata for one file
GET	`/v1/files/{file_id}/content`	Download the raw JSONL body
DELETE	`/v1/files/{file_id}`	Soft-delete a file

Authentication

Every request (except the unauthenticated OPTIONS preflight) must include:

x-api-key:    <your-api-key>
x-project-id: <your-project-uuid>

Missing or invalid headers return 401. Inactive keys or keys that don’t belong to the supplied project return 403. An organization with no balance and no free credits returns 429 with an insufficient_quota error.

The File object

This is the shape returned by upload, retrieve, and (inside data[]) list.

{
  "id":         "file-abc123...",
  "object":     "file",
  "bytes":      12345,
  "created_at": 1736290000,
  "filename":   "input.jsonl",
  "purpose":    "batch",
  "status":     "processed",
  "expires_at": 1738882000
}

For batch error files, an additional is_error flag is set:

{
  "id":         "file-err789...",
  "object":     "file",
  "bytes":      512,
  "created_at": 1736295000,
  "filename":   "batch_01HZX_errors.jsonl",
  "purpose":    "batch_output",
  "status":     "processed",
  "is_error":   true
}

Field	Type	Description
`id`	string	File identifier. Always prefixed `file-`. Legacy `file_` (underscore) ids written before the prefix was normalised remain readable and resolvable.
`object`	string	Always `"file"`.
`bytes`	integer	Size in bytes as measured by the server after upload.
`created_at`	integer	Unix timestamp (seconds).
`filename`	string	Original filename you uploaded, or `{file_id}.jsonl` if none was supplied.
`purpose`	string	`"batch"` for uploads, `"batch_output"` for both batch result and batch error files.
`status`	string	One of `"uploaded"` / `"processed"` / `"error"`. ZeroGPU emits `"processed"` exclusively today; the wider union matches OpenAI’s published type for forward compatibility.
`status_details`	string \| omitted	OpenAI-compatible diagnostic string. Omitted on healthy files.
`expires_at`	integer \| omitted	Unix timestamp at which the file will be removed. Customer uploads expire 30 days after upload. May be absent for server-written files.
`is_error`	boolean \| omitted	ZeroGPU extension. Present and `true` only on batch error files (the ones referenced by `Batch.error_file_id`). Omitted on input and success files. OpenAI SDKs ignore this field unless explicitly read.

POST `/v1/files`: Upload a file

Uploads a JSONL file that will be used as the input to a batch.

Request

POST /v1/files
Content-Type: multipart/form-data
x-api-key:    <key>
x-project-id: <uuid>

Multipart form fields:

Field	Required	Value
`purpose`	Yes	Must be exactly `"batch"`.
`file`	Yes	The JSONL file. Max 100 MB.

Note. JSONL is validated at batch creation, not uploadThe server stores your file as-is. Malformed JSONL will upload successfully but fail with a 400 (and a line field) when you call POST /v1/batches. See the JSONL format page for the exact schema.

Other notes:

The file is retained for 30 days unless you delete it.
The filename you upload is preserved in the filename field of the File object.

Response: `200 OK`

{
  "id":         "file-0123456789abcdef012345",
  "object":     "file",
  "bytes":      5000,
  "created_at": 1736290000,
  "filename":   "input.jsonl",
  "purpose":    "batch",
  "status":     "processed",
  "expires_at": 1738882000
}

Errors

Status	Code	Cause
`400`	`invalid_content_type`	`Content-Type` was not `multipart/form-data`.
`400`	`invalid_multipart`	The multipart body could not be parsed.
`400`	`invalid_purpose`	`purpose` was anything other than `"batch"`.
`400`	`missing_file`	No `file` field in the multipart body.
`400`	`empty_file`	The uploaded file had zero bytes.
`413`	`file_too_large`	File exceeded 100 MB.
`401` / `403` / `429` / `500`	-	See Errors reference.

Example

curl -X POST https://api.zerogpu.ai/v1/files \
  -H "x-api-key: $ZGPU_API_KEY" \
  -H "x-project-id: $ZGPU_PROJECT_ID" \
  -F purpose=batch \
  -F [email protected]

GET `/v1/files`: List files

Returns the project’s files in reverse-chronological order by default.

Request

GET /v1/files[?purpose=...&order=...&after=...&limit=...]
x-api-key:    <key>
x-project-id: <uuid>

Query parameters (all optional):

Param	Default	Description
`purpose`	(all)	Filter by purpose: `batch` or `batch_output`. When you query `batch_output`, both success and error files are returned (distinguished by `is_error` on each file object).
`order`	`desc`	Sort order on `created_at`. `desc` = newest first, `asc` = oldest first.
`after`	-	Cursor for pagination. Pass the `id` of the last file from the previous page (or use the `last_id` field from the previous response).
`limit`	`10000`	Maximum number of files to return. Must be a positive integer ≤ `10000`.

Response: `200 OK`

{
  "object": "list",
  "data": [
    {
      "id":         "file-abc...",
      "object":     "file",
      "bytes":      5000,
      "created_at": 1736290000,
      "filename":   "input.jsonl",
      "purpose":    "batch",
      "status":     "processed",
      "expires_at": 1738882000
    },
    {
      "id":         "file-out_xyz...",
      "object":     "file",
      "bytes":      12345,
      "created_at": 1736289900,
      "filename":   "file-out_xyz.jsonl",
      "purpose":    "batch_output",
      "status":     "processed"
    }
  ],
  "first_id": "file-abc...",
  "last_id":  "file-out_xyz...",
  "has_more": false
}

Field	Type	Description
`object`	string	Always `"list"`.
`data`	array	File objects in the requested order.
`first_id`	string \| null	The `id` of the first item on the page, or `null` if `data` is empty.
`last_id`	string \| null	The `id` of the last item on the page. Use this as `after` for the next page.
`has_more`	boolean	`true` if more files exist beyond `limit`.

To page forward, pass last_id as after on the next request, keeping the same purpose and order.

Errors

Status	Code	Cause
`400`	`invalid_limit`	`limit` was not a positive integer.
`401` / `403` / `429` / `500`	-	See Errors reference.

Example

curl "https://api.zerogpu.ai/v1/files?purpose=batch&limit=20" \
  -H "x-api-key: $ZGPU_API_KEY" \
  -H "x-project-id: $ZGPU_PROJECT_ID"

GET `/v1/files/{file_id}`: Retrieve a file

Returns the metadata for a single file. Use this to look up filename, bytes, or purpose without downloading the body.

Request

GET /v1/files/{file_id}
x-api-key:    <key>
x-project-id: <uuid>

Response: `200 OK`

Same shape as the File object returned by upload.

Errors

Status	Code	Cause
`404`	`file_not_found`	File does not exist, belongs to another project, or has been deleted. The same `404` is returned in all three cases to avoid leaking file existence across projects.
`401` / `403` / `429` / `500`	-	See Errors reference.

Example

curl https://api.zerogpu.ai/v1/files/file-abc123... \
  -H "x-api-key: $ZGPU_API_KEY" \
  -H "x-project-id: $ZGPU_PROJECT_ID"

GET `/v1/files/{file_id}/content`: Download a file’s body

Streams the raw JSONL body. This is how you read both the input file you uploaded and the output / error files produced by a completed batch.

Request

GET /v1/files/{file_id}/content
x-api-key:    <key>
x-project-id: <uuid>

Response: `200 OK`

Content-Type:        application/jsonl
Content-Disposition: attachment; filename="{original_filename}"

<raw JSONL bytes>

The body is streamed; you do not need to fit it in memory.

Errors

Status	Code	Cause
`404`	`file_not_found`	File missing, deleted, or belongs to another project.
`401` / `403` / `429` / `500`	-	See Errors reference.

Example

curl https://api.zerogpu.ai/v1/files/file-out789.../content \
  -H "x-api-key: $ZGPU_API_KEY" \
  -H "x-project-id: $ZGPU_PROJECT_ID" \
  -o output.jsonl

DELETE `/v1/files/{file_id}`: Delete a file

Soft-deletes the file. The stored object is removed from storage immediately; the database row is preserved with a deleted_at timestamp for audit purposes. After a successful delete, the file disappears from list, retrieve, and content endpoints, all three return 404. Deletes cannot be undone via the API.

Request

DELETE /v1/files/{file_id}
x-api-key:    <key>
x-project-id: <uuid>

Response: `200 OK`

{
  "id":      "file-abc123...",
  "object":  "file",
  "deleted": true
}

Errors

Status	Code	Cause
`404`	`file_not_found`	File missing, already deleted, or belongs to another project.
`401` / `403` / `429` / `500`	-	See Errors reference.

Example

curl -X DELETE https://api.zerogpu.ai/v1/files/file-abc123... \
  -H "x-api-key: $ZGPU_API_KEY" \
  -H "x-project-id: $ZGPU_PROJECT_ID"

Quotas, limits, and behavior

Limit	Value
Max single upload	100 MB
Default retention	30 days
Max list `limit`	10,000
Accepted upload `purpose`	`batch` only
Returned `purpose` values	`batch`, `batch_output`

Notes:

There is no rate-limit envelope returned in headers; quota is enforced at the organization level. A request from an organization with no balance and no free credits returns 429 insufficient_quota.
Deleting a file that is the input to an active batch does not stop the batch, the batch reads the input file at creation time, not on demand.
The output and error files produced by a batch are both written with purpose: batch_output. Error files are additionally tagged with is_error: true so you can distinguish them at list time. The Batch object’s error_file_id is the canonical way to discover the error file for a given batch.

Next steps

Batches API reference →

Create, list, retrieve batches; status lifecycle and limits.

JSONL format →

What an input line, an output line, and an error line look like.

Errors reference →

Every HTTP status, every validation message, every JSONL error code.

Documentation Index

Upload file

List files

Retrieve file

Download file

Delete file

​Endpoint summary

​Authentication

​The File object

​POST /v1/files: Upload a file

​Request

​Response: 200 OK

​Errors

​Example

​GET /v1/files: List files

​Request

​Response: 200 OK

​Errors

​Example

​GET /v1/files/{file_id}: Retrieve a file

​Request

​Response: 200 OK

​Errors

​Example

​GET /v1/files/{file_id}/content: Download a file’s body

​Request

​Response: 200 OK

​Errors

​Example

​DELETE /v1/files/{file_id}: Delete a file

​Request

​Response: 200 OK

​Errors

​Example

​Quotas, limits, and behavior

​Next steps

Batches API reference →

JSONL format →

Errors reference →

Endpoint summary

Authentication

The File object

POST `/v1/files`: Upload a file

Request

Response: `200 OK`

Errors

Example

GET `/v1/files`: List files

Request

Response: `200 OK`

Errors

Example

GET `/v1/files/{file_id}`: Retrieve a file

Request

Response: `200 OK`

Errors

Example

GET `/v1/files/{file_id}/content`: Download a file’s body

Request

Response: `200 OK`

Errors

Example

DELETE `/v1/files/{file_id}`: Delete a file

Request

Response: `200 OK`

Errors

Example

Quotas, limits, and behavior

Next steps