Get API key

Files

View as Markdown

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, 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.jsonl
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). 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 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.txt
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.

cURL
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 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.txt
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) 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 -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.jsonl
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 -s -X DELETE "https://api.privatemind.com/v1/files/file-abc123" \
  -H "Authorization: Bearer $PMIND_KEY"
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.

cURL
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 earlier expires_after.
  • See the Batch API 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). 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: batch files.
  • Messages API: where file sources 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.