Files

The Files API mirrors OpenAI’s surface so SDKs work unchanged. Gatewyse stores file metadata in a tenant-scoped 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.

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 tenant metadata.

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.

The translation is tenant-scoped. A file uploaded by one tenant cannot be referenced by another.

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