> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metaphi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Upload, retrieve, list and delete traces for batches.

A `file` is an uploaded trace, for use in a [batch](https://docs.metaphi.ai/kennet/api/batches.md). To twin a single trace, send it to [create a twin](https://docs.metaphi.ai/kennet/api/twins.md#create-a-twin) instead.

## Formats

| Format | Extensions |
| - | - |
| JSON | `.json` |
| JSON Lines | `.jsonl`, `.ndjson` |
| UTF-8 text | Any other, such as `.txt` or `.log` |

A twin keeps its trace's format and extension. Other formats, such as PDFs or archives, return `400 file_unsupported`.

## The file object

```json theme={"dark"}
{
  "id": "file_3a9e...",
  "object": "file",
  "filename": "trace-0001.jsonl",
  "bytes": 482113,
  "created": 1760054400,
  "livemode": true
}
```

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier, prefixed `file_` |
| `object` | string | `file` |
| `filename` | string or null | Name of the uploaded file |
| `bytes` | integer | Size in bytes |
| `created` | integer | Time of upload, in Unix seconds |
| `livemode` | boolean | `false` for a test-mode file |

## Upload a file

`POST /v1/kennet/files`

Uploads one trace. Send `multipart/form-data`. Each file can be used in one batch request.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `file` | file | yes | The trace, in a [supported format](#formats). Max 50 MiB (2 MiB in test mode). Name: 1 to 200 letters, digits, `.`, `-` and `_`, not starting with `.` |

```sh theme={"dark"}
curl https://api.metaphi.ai/v1/kennet/files \
  -H "Authorization: Bearer $API_KEY" \
  -F file=@trace-0001.jsonl
```

**Returns** `200` with a `file` object.

| Status | Code | Cause |
| - | - | - |
| 400 | `invalid_filename` | Invalid file name |
| 400 | `file_empty` | The file is empty |
| 400 | `file_unsupported` | Not JSON, JSON Lines or UTF-8 text |
| 413 | `file_too_large` | Over 50 MiB (2 MiB in test mode). Split the trace and upload each part |

## Retrieve a file

`GET /v1/kennet/files/{id}`

Retrieves a file.

**Returns** a `file` object, or `404 resource_missing`.

## List files

`GET /v1/kennet/files`

Lists files, newest first.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `limit` | integer | no | 1 to 100. Default 10 |
| `starting_after` | string | no | A file ID. Returns the page after it |

**Returns** `{object: "list", data, has_more, url}`, with `file` objects in `data`.

## Delete a file

`DELETE /v1/kennet/files/{id}`

Deletes a file not used in a batch.

**Returns** `{id, object: "file", deleted: true}`.

| Status | Code | Cause |
| - | - | - |
| 404 | `resource_missing` | No such file |
| 409 | `file_in_use` | The file is in a batch |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.