List Files

List files with pagination and filtering

GET /api/v1/files

cURL

# List all files
curl "https://api.fileguard.io/api/v1/files?page=1&page_size=20" \
  -H "Authorization: Bearer fg_your_api_key"

# Filter by context
curl "https://api.fileguard.io/api/v1/files?context=patient_reports" \
  -H "Authorization: Bearer fg_your_api_key"

# Filter by uploader
curl "https://api.fileguard.io/api/v1/files?uploaded_by=key_abc123" \
  -H "Authorization: Bearer fg_your_api_key"

200 OK

{
  "status": "SUCCESS",
  "data": {
    "data": [
      {
        "file_id": "file_z1x2c3v4b5n6",
        "original_filename": "blood_test.pdf",
        "content_type": "application/pdf",
        "size_bytes": 245678,
        "context_key": "patient_reports",
        "uploaded_by": "key_abc123",
        "uploaded_by_name": "Production Upload Key",
        "download_count": 47,
        "last_downloaded_at": "2026-01-16T10:30:00Z",
        "created_at": "2026-01-04T10:00:00Z"
      },
      {
        "file_id": "file_a1b2c3d4e5f6",
        "original_filename": "xray_scan.jpg",
        "content_type": "image/jpeg",
        "size_bytes": 1245678,
        "context_key": "patient_reports",
        "uploaded_by": "usr_xyz789",
        "uploaded_by_name": null,
        "download_count": 12,
        "last_downloaded_at": "2026-01-15T08:00:00Z",
        "created_at": "2026-01-03T09:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 847,
      "total_pages": 43,
      "has_next": true,
      "has_previous": false
    }
  },
  "timestamp": "2026-01-04T10:00:00Z"
}

List files uploaded to your tenant with optional filtering by context and uploader.

Query Parameters

context · string

Filter by file context key (e.g., patient_reports)

uploaded_by · string

Filter by uploader ID (API key ID like key_abc123 or user ID like usr_xyz789)

page · integer · default: "1"

Page number (1-indexed)

page_size · integer · default: "20"

Items per page (1-100)

Response

data · object

Show properties

data · array

Array of file objects

pagination · object

Pagination metadata

File Object

Field	Type	Description
file_id	string	Unique file identifier
original_filename	string	Original uploaded filename
content_type	string	MIME content type
size_bytes	integer	File size in bytes
context_key	string	File context key
uploaded_by	string	API key or user ID that uploaded
uploaded_by_name	string	Name of the API key (null for users)
download_count	integer	Number of downloads
last_downloaded_at	datetime	Last download timestamp
created_at	datetime	Upload timestamp

cURL

# List all files
curl "https://api.fileguard.io/api/v1/files?page=1&page_size=20" \
  -H "Authorization: Bearer fg_your_api_key"

# Filter by context
curl "https://api.fileguard.io/api/v1/files?context=patient_reports" \
  -H "Authorization: Bearer fg_your_api_key"

# Filter by uploader
curl "https://api.fileguard.io/api/v1/files?uploaded_by=key_abc123" \
  -H "Authorization: Bearer fg_your_api_key"

200 OK

{
  "status": "SUCCESS",
  "data": {
    "data": [
      {
        "file_id": "file_z1x2c3v4b5n6",
        "original_filename": "blood_test.pdf",
        "content_type": "application/pdf",
        "size_bytes": 245678,
        "context_key": "patient_reports",
        "uploaded_by": "key_abc123",
        "uploaded_by_name": "Production Upload Key",
        "download_count": 47,
        "last_downloaded_at": "2026-01-16T10:30:00Z",
        "created_at": "2026-01-04T10:00:00Z"
      },
      {
        "file_id": "file_a1b2c3d4e5f6",
        "original_filename": "xray_scan.jpg",
        "content_type": "image/jpeg",
        "size_bytes": 1245678,
        "context_key": "patient_reports",
        "uploaded_by": "usr_xyz789",
        "uploaded_by_name": null,
        "download_count": 12,
        "last_downloaded_at": "2026-01-15T08:00:00Z",
        "created_at": "2026-01-03T09:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 847,
      "total_pages": 43,
      "has_next": true,
      "has_previous": false
    }
  },
  "timestamp": "2026-01-04T10:00:00Z"
}

Required Scope

Requires metadata scope on your API key.

Filtering

Combine multiple filters:

GET /api/v1/files?context=patient_reports&uploaded_by=key_abc123&page=1&page_size=50

This returns files in patient_reports context uploaded by API key key_abc123.