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, 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.
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 setting. These files are separate from files you attach in a chat, 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 | 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 | Passed through |
Upload a file
POST /v1/files is a multipart upload. Send the purpose field first, then the file.
curl -s "https://api.privatemind.com/v1/files" \
-H "Authorization: Bearer $PMIND_KEY" \
-F purpose=batch \
-F file=@requests.jsonlfrom 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
{
"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).nullfor 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 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 -s "https://api.privatemind.com/v1/files" \
-H "Authorization: Bearer $PMIND_KEY" \
-F purpose=user_data \
-F visibility=org \
-F file=@notes.txtf = 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.
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
visibilityfield. A Messages batch is private if any request in it references a private file. - Messages and sandboxes 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 -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.txtf = client.files.create(
file=open("notes.txt", "rb"),
purpose="user_data",
expires_after={"anchor": "created_at", "seconds": 86400},
)
print(f.expires_at)- From
expires_aton, 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) unless you set
expires_after. A batch that is still running keeps its input until it ends, even pastexpires_at.
Retrieve metadata
GET /v1/files/{id} returns the file object above, without the content.
curl -s "https://api.privatemind.com/v1/files/file-abc123" \
-H "Authorization: Bearer $PMIND_KEY"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 -s "https://api.privatemind.com/v1/files?purpose=batch" \
-H "Authorization: Bearer $PMIND_KEY"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 -s "https://api.privatemind.com/v1/files/file-out-abc123/content" \
-H "Authorization: Bearer $PMIND_KEY" -o output.jsonlcontent = 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 -s -X DELETE "https://api.privatemind.com/v1/files/file-abc123" \
-H "Authorization: Bearer $PMIND_KEY"client.files.delete("file-abc123")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.
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, 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 earlierexpires_after. - See the Batch API for a batch's request cap and completion window.
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.
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){
"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 thefilepart, and the file is stored asuser_data. mime_typecomes from the file name's extension.- The list is newest first, with
limit(1 to 1000) and thepageorafter_idcursor the SDK passes.before_idis not supported. - Delete returns
{"id": "...", "type": "file_deleted"}. Batch input files are refused with409, 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). The file must be one you can see, and must be text or a PNG, JPEG, GIF or WebP image.
Where next
- Batch API: the main user of
purpose: batchfiles. - Messages API: where
filesources are used. - Errors: status codes and error shapes, including quota and validation rejections.
- Files and sources: the separate, per-conversation attachments in the chat app.