Files

The Files API mirrors OpenAI’s surface so SDKs work unchanged. Gatewyse stores file metadata in a registry and assigns a stable gateway file ID (UUID); downstream references (chat content parts, batch input lines, vector-store attachments) use the gateway ID, and the gateway translates to the underlying provider’s file ID at request time.

The registry is deployment-wide. It is not partitioned by organization, department, API key or user. The uploading key and user are recorded on each entry, but list, fetch and delete are resolved against the deployment alone — so any API key on the deployment can list, read and delete any file, and reference any gateway file ID in a request. Treat the file namespace as shared, and do not use it to separate data between organizations.

Required capability: files

Endpoints

Method	Path	Description
POST	/v1/files	Upload a file (multipart or base64 JSON).
GET	/v1/files	List files with cursor pagination.
GET	/v1/files/:fileId	Fetch metadata for a single file.
DELETE	/v1/files/:fileId	Delete from both the gateway registry and the upstream provider.

Upload — multipart

curl https://your-gateway.example.com/v1/files \
  -H "Authorization: Bearer aigw_sk_your_api_key" \
  -F "file=@dataset.jsonl" \
  -F "provider=openai" \
  -F "purpose=batch"

Upload — JSON

curl https://your-gateway.example.com/v1/files \
  -H "Authorization: Bearer aigw_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "filename": "dataset.jsonl",
    "mime_type": "application/jsonl",
    "content_base64": "<base64 bytes>",
    "purpose": "batch"
  }'

Request fields

Field	Type	Required	Description
provider	string	Yes	Provider slug to upload to (openai, anthropic, etc.).
purpose	string	Yes	assistants | batch | fine-tune | vision | user_data.
filename	string	Yes (JSON only)	Original filename. Inferred from multipart file field.
mime_type	string	Yes (JSON only)	MIME type. Inferred from multipart upload.
content_base64	string	Yes (JSON only)	File bytes, base64-encoded.
expires_in_seconds	integer	No	TTL for the gateway registry entry. Defaults to the provider’s own TTL.
metadata	object	No	Free-form metadata stored alongside the entry.

Response

{
  "id": "file-7c8b9d3e-...",
  "object": "file",
  "bytes": 12480,
  "created_at": 1748284800,
  "expires_at": null,
  "filename": "dataset.jsonl",
  "purpose": "batch",
  "status": "processed",
  "provider": "openai"
}

List

curl 'https://your-gateway.example.com/v1/files?purpose=batch&limit=50' \
  -H "Authorization: Bearer aigw_sk_your_api_key"

Returns a paginated list. Use next_cursor to walk the next page.

ID translation

When you embed a gateway file ID anywhere a request body accepts a file reference — chat content parts, batch input lines (input_file_id), vector-store attachments — the gateway automatically translates the gateway UUID to the underlying provider’s file ID before dispatching. Callers never need to track provider IDs.

Translation is resolved against the deployment registry, which every API key on the deployment shares. A gateway file ID issued to one caller resolves for any other.

Limits

Limit	Value
Max upload size	512 MiB (multipart) / 50 MiB (JSON body)
Files per upload	1
Purposes that participate in vector stores	assistants, user_data