Files API Reference#

The Files API allows you to upload, list, retrieve, and delete documents for use with the Responses API.

Upload a File#

POST /v1/files

Uploads a file to the system. The file must be sent as multipart/form-data.

Request:

POST /v1/files HTTP/1.1
Content-Type: multipart/form-data
Authorization: Bearer <your_api_key>

purpose="assistants"
file=@"document.pdf"

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object": "file",
  "bytes": 1048576,
  "created_at": 1716387200,
  "filename": "document.pdf",
  "purpose": "assistants",
  "status": "processed"
}

List Files#

GET /v1/files

Returns a list of all uploaded files.

Request:

GET /v1/files?purpose=assistants HTTP/1.1
Authorization: Bearer <your_api_key>

Response:

{
  "object": "list",
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "object": "file",
      "bytes": 1048576,
      "created_at": 1716387200,
      "filename": "document.pdf",
      "purpose": "assistants",
      "status": "processed"
    }
  ]
}

Retrieve File Metadata#

GET /v1/files/{file_id}

Returns metadata about a specific file (does not return the file content).

Request:

GET /v1/files/123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Authorization: Bearer <your_api_key>

Response: (Returns the same JSON file object as the Upload response)

Download File Content#

GET /v1/files/{file_id}/content

Returns the raw binary content of the file.

Request:

GET /v1/files/123e4567-e89b-12d3-a456-426614174000/content HTTP/1.1
Authorization: Bearer <your_api_key>

Response: HTTP 200 OK Content-Type: application/octet-stream (Raw binary file bytes)

Delete a File#

DELETE /v1/files/{file_id}

Permanently deletes a file.

Request:

DELETE /v1/files/123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Authorization: Bearer <your_api_key>

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object": "file",
  "deleted": true
}