# Files Upload a dataset once and reference it by id from batch, fine-tuning, and other endpoints. The Files API stores the datasets other endpoints use. Upload a file once and pass its `id` to whatever needs it, so you don't send the same bytes in every request. It is the input side of the [Batch API](https://docs.privatemind.com/batch.html), and fine-tuning and other bulk endpoints read from it too. Files stay within your org, and the key that uploads a file decides [who can see it](https://docs.privatemind.com/files.html#who-can-see-a-file). The API is OpenAI-compatible: point the official client at `https://api.privatemind.com/v1` and `client.files.*` works unchanged. Two additions have no OpenAI equivalent: `/v1/files/usage` and the [`visibility`](https://docs.privatemind.com/files.html#who-can-see-a-file) setting. These files are separate from [files you attach in a chat](https://docs.privatemind.com/files-and-sources.html), which belong to one conversation and never get a file `id`. ## Purposes Every file has a `purpose`, set at upload and fixed for life. It decides how the file is validated and how long it is kept. | Purpose | For | Validated as | |---|---|---| | `batch` | Input for a [batch](https://docs.privatemind.com/batch.html) | JSONL, one request per line | | `fine-tune` | Fine-tuning datasets | JSONL | | `vision` | Images referenced by requests | Passed through (not validated) | | `assistants` | General-purpose reference files | Passed through | | `user_data` | Files referenced from messages, including every upload through the [Messages API shape](https://docs.privatemind.com/files.html#messages-api) | Passed through | ## Upload a file `POST /v1/files` is a multipart upload. Send the `purpose` field first, then the `file`. **cURL** ```bash curl -s "https://api.privatemind.com/v1/files" \ -H "Authorization: Bearer $PMIND_KEY" \ -F purpose=batch \ -F file=@requests.jsonl ``` **Python** ```python from openai import OpenAI client = OpenAI(base_url="https://api.privatemind.com/v1", api_key=PMIND_KEY) f = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch") print(f.id) # file-... ``` The API validates the upload as it streams in and stores nothing that fails, such as malformed JSONL where JSONL is required, or a body over the size limit. The response is a file object. ## The file object ```json { "id": "file-abc123", "object": "file", "bytes": 148923, "created_at": 1730928000, "filename": "requests.jsonl", "purpose": "batch", "status": "processed", "visibility": "private", "expires_at": null } ``` - **`id`**: the handle you pass to other endpoints. - **`bytes`**: size of the stored content. - **`purpose`**: what you declared at upload. - **`visibility`**: who can see the file (below). - **`expires_at`**: when the file is deleted, as a Unix timestamp (see [below](https://docs.privatemind.com/files.html#when-a-file-expires)). `null` for a batch file, which follows its batch. ## Who can see a file Every file is either `private` or shared with your org (`org`). - **`private`**: only the user who uploaded it can see it, through any of their keys. To everyone else it doesn't exist: retrieve, download, delete and change return 404, and lists leave it out. - **`org`**: everyone in your org can see, download and delete it, and use it as a batch input. By default, a file uploaded with an org [application key](https://docs.privatemind.com/key-management-api.html#application-keys) is shared, and one uploaded with any other key, including a Notebook or OpenCode token, is private. To choose, send `visibility` before the `file` field. Sent after it, the request is refused with `400`: **cURL** ```bash curl -s "https://api.privatemind.com/v1/files" \ -H "Authorization: Bearer $PMIND_KEY" \ -F purpose=user_data \ -F visibility=org \ -F file=@notes.txt ``` **Python** ```python f = client.files.create( file=open("notes.txt", "rb"), purpose="user_data", extra_body={"visibility": "org"}, ) ``` The uploader can change it later with `POST /v1/files/{id}`, which returns the updated file object. Anyone else gets 403 for a shared file and 404 for a private one. ```bash curl -s "https://api.privatemind.com/v1/files/file-abc123" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{"visibility": "private"}' ``` - **Batches** take the visibility of their input file when they are created, and a batch's output and error files follow the batch. Batch create refuses a `visibility` field. A Messages batch is private if any request in it references a private file. - **Messages and [sandboxes](https://docs.privatemind.com/containers.html)** can only use files the caller can see. The id of someone else's private file returns 404. - **Files uploaded before this setting existed** are shared with the org, and their uploader can make them private. ## When a file expires A file expires 30 days after upload, or sooner if you set `expires_after` (one hour to 30 days). OpenAI differs: there, a file without `expires_after` is kept until you delete it. Send `expires_after` before the `file` field. Sent after it, or outside that range, it is refused with `400`. **cURL** ```bash curl -s "https://api.privatemind.com/v1/files" \ -H "Authorization: Bearer $PMIND_KEY" \ -F purpose=user_data \ -F 'expires_after[anchor]=created_at' \ -F 'expires_after[seconds]=86400' \ -F file=@notes.txt ``` **Python** ```python f = client.files.create( file=open("notes.txt", "rb"), purpose="user_data", expires_after={"anchor": "created_at", "seconds": 86400}, ) print(f.expires_at) ``` - **From `expires_at` on, the file is gone**: retrieve, download and delete return 404, lists leave it out, and Messages, batches and sandboxes can no longer use it. Its content is deleted within the hour. - **There is no extension.** To keep a file longer, download it and upload it again before it expires. - **Batch files** keep the batch's retention ([below](https://docs.privatemind.com/files.html#limits-and-retention)) unless you set `expires_after`. A batch that is still running keeps its input until it ends, even past `expires_at`. ## Retrieve metadata `GET /v1/files/{id}` returns the file object above, without the content. **cURL** ```bash curl -s "https://api.privatemind.com/v1/files/file-abc123" \ -H "Authorization: Bearer $PMIND_KEY" ``` **Python** ```python f = client.files.retrieve("file-abc123") print(f.filename, f.bytes) ``` ## List files `GET /v1/files` lists the files you can see, newest first: your own and those shared with your org. Filter by purpose with `?purpose=`. **cURL** ```bash curl -s "https://api.privatemind.com/v1/files?purpose=batch" \ -H "Authorization: Bearer $PMIND_KEY" ``` **Python** ```python for f in client.files.list(purpose="batch"): print(f.id, f.filename) ``` ## Download content `GET /v1/files/{id}/content` streams the raw bytes. Use it to download a batch's output and error files. **cURL** ```bash curl -s "https://api.privatemind.com/v1/files/file-out-abc123/content" \ -H "Authorization: Bearer $PMIND_KEY" -o output.jsonl ``` **Python** ```python content = client.files.content("file-out-abc123") content.write_to_file("output.jsonl") ``` ## Delete a file `DELETE /v1/files/{id}` removes a file and its content immediately. **cURL** ```bash curl -s -X DELETE "https://api.privatemind.com/v1/files/file-abc123" \ -H "Authorization: Bearer $PMIND_KEY" ``` **Python** ```python client.files.delete("file-abc123") ``` > [!NOTE] > Files with `purpose: batch` can't be deleted through the Files API: the request gets `409`, so a batch never loses its input. Only retention removes them (below). ## Storage usage `GET /v1/files/usage` shows how much of your org's file storage is in use, so you can check it against a quota before an upload is refused. ```bash curl -s "https://api.privatemind.com/v1/files/usage" \ -H "Authorization: Bearer $PMIND_KEY" ``` If your org has a storage quota, an upload that would go over it is rejected; without one, storage has no limit. Uploaded files, including batch inputs, count until they expire. A batch's output and error files are generated from the run and don't count. ## Limits and retention - **Maximum file size**: 64 MB per file. A larger upload is rejected with `413`. - **Retention**: every file is deleted at its [`expires_at`](https://docs.privatemind.com/files.html#when-a-file-expires), at most 30 days after upload. A batch's input, output and error files are kept for 29 days after the batch reaches a terminal state, then deleted, unless the input was given an earlier `expires_after`. - See the [Batch API](https://docs.privatemind.com/batch.html) for a batch's request cap and completion window. > [!NOTE] > Uploaded files hold your content and are stored on our servers, so a workload that uses them is not eligible for zero-data-retention (ZDR) arrangements. ## Messages API Send an `anthropic-version` header, as the Anthropic SDKs always do, and the same store answers in Anthropic's Files API format. A file uploaded through either format can be listed, read and deleted through either. ```python import anthropic client = anthropic.Anthropic(base_url="https://api.privatemind.com", api_key="PMIND...:...") f = client.files.upload(file=("notes.txt", open("notes.txt", "rb"), "text/plain")) print(f.id, f.mime_type, f.size_bytes) for item in client.files.list(): print(item.id, item.filename) data = client.files.download(f.id).read() client.files.delete(f.id) ``` ```json { "type": "file", "id": "file-abc123", "filename": "notes.txt", "mime_type": "text/plain", "size_bytes": 1024, "created_at": "2026-09-30T02:04:09Z", "downloadable": true, "visibility": "private", "expires_at": "2026-10-30T02:04:09Z" } ``` - **No `purpose`.** The upload takes only the `file` part, and the file is stored as `user_data`. - **`mime_type`** comes from the file name's extension. - **The list** is newest first, with `limit` (1 to 1000) and the `page` or `after_id` cursor the SDK passes. `before_id` is not supported. - **Delete** returns `{"id": "...", "type": "file_deleted"}`. Batch input files are refused with `409`, as above. - **Expiry**: 30 days after upload, shown in `expires_at`. This format has no field to change it. Reference a file from a message with a `file` source on an `image` or `document` block (see [Vision](https://docs.privatemind.com/vision.html#messages-api)). The file must be one you can see, and must be text or a PNG, JPEG, GIF or WebP image. ## Where next - [Batch API](https://docs.privatemind.com/batch.html): the main user of `purpose: batch` files. - [Messages API](https://docs.privatemind.com/messages-api.html): where `file` sources are used. - [Errors](https://docs.privatemind.com/errors.html): status codes and error shapes, including quota and validation rejections. - [Files and sources](https://docs.privatemind.com/files-and-sources.html): the separate, per-conversation attachments in the chat app.