List Files

Retrieve a list of uploaded files.

Endpoint

GET /v1/files

Authentication

Authorization: Bearer gw_prod_...

Query Parameters

Parameter	Type	Required	Description
purpose	string	No	Filter by purpose
status	string	No	Filter by status: uploaded, processing, processed, error
limit	integer	No	Number of results (1-100, default 20)
after	string	No	Cursor for pagination
order	string	No	Sort order: asc or desc (default)

Examples

List All Files

curl https://api.gateflow.ai/v1/files \
  -H "Authorization: Bearer gw_prod_..."

Python

import openai

client = openai.OpenAI(
    base_url="https://api.gateflow.ai/v1",
    api_key="gw_prod_..."
)

files = client.files.list()

for file in files.data:
    print(f"{file.id}: {file.filename} ({file.status})")

Filter by Purpose

curl "https://api.gateflow.ai/v1/files?purpose=document" \
  -H "Authorization: Bearer gw_prod_..."

files = client.files.list(purpose="document")

Filter by Status

curl "https://api.gateflow.ai/v1/files?status=processed" \
  -H "Authorization: Bearer gw_prod_..."

Pagination

# Get first page
files = client.files.list(limit=10)

# Get next page
if files.has_more:
    next_files = client.files.list(
        limit=10,
        after=files.data[-1].id
    )

Combined Filters

curl "https://api.gateflow.ai/v1/files?purpose=document&status=processed&limit=50" \
  -H "Authorization: Bearer gw_prod_..."

Response

{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 1024000,
      "created_at": 1708099200,
      "filename": "document.pdf",
      "purpose": "document",
      "status": "processed",
      "status_details": null,
      "metadata": {
        "client": "acme"
      }
    },
    {
      "id": "file-def456",
      "object": "file",
      "bytes": 512000,
      "created_at": 1708012800,
      "filename": "report.docx",
      "purpose": "document",
      "status": "processed",
      "status_details": null,
      "metadata": {}
    }
  ],
  "has_more": true,
  "first_id": "file-abc123",
  "last_id": "file-def456"
}

Response Fields

Field	Type	Description
object	string	Always "list"
data	array	Array of file objects
has_more	boolean	Whether more results exist
first_id	string	ID of first item
last_id	string	ID of last item

File Object Fields

Field	Type	Description
id	string	Unique file identifier
object	string	Always "file"
bytes	integer	File size in bytes
created_at	integer	Unix timestamp of creation
filename	string	Original filename
purpose	string	File purpose
status	string	Processing status
status_details	string	Error details if failed
metadata	object	Custom metadata

GateFlow Extensions

List with Processing Details

curl "https://api.gateflow.ai/v1/files?include=processing" \
  -H "Authorization: Bearer gw_prod_..."

Response:

{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "filename": "document.pdf",
      "status": "processed",
      "gateflow": {
        "process_id": "proc_xyz789",
        "pages": 15,
        "chunks": 42,
        "vectors_stored": true,
        "pii_detected": 3,
        "classification": "confidential"
      }
    }
  ]
}

List by Collection

curl "https://api.gateflow.ai/v1/files?collection=legal-docs" \
  -H "Authorization: Bearer gw_prod_..."

List by Metadata

curl "https://api.gateflow.ai/v1/files?metadata.client=acme" \
  -H "Authorization: Bearer gw_prod_..."

Errors

Code	Description
400	Invalid query parameters
401	Invalid API key
429	Rate limit exceeded

See Also

• Upload Files - Upload new files
• File Operations - Get, delete, download