API Reference

Complete reference for the FileGuard API

Base URL

https://api.fileguard.io/api/v1

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer fg_your_api_key

See Authentication for details on creating and managing API keys.

Request Format

• Content-Type: application/json for most endpoints
• File uploads: multipart/form-data
• Timestamps: ISO 8601 format (UTC)

Response Format

All responses follow a consistent structure:

Success Response

{
  "status": "SUCCESS",
  "message": "Operation successful",
  "data": { ... },
  "timestamp": "2026-01-04T10:00:00Z"
}

Error Response

{
  "status": "ERROR",
  "message": "Error description",
  "errors": ["Detailed error message 1", "Detailed error message 2"],
  "timestamp": "2026-01-04T10:00:00Z"
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Resource already exists
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Pagination

List endpoints support pagination:

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
page_size	integer	20	Items per page (max 100)

Paginated Response

{
  "status": "SUCCESS",
  "data": {
    "data": [...],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 150,
      "total_pages": 8,
      "has_next": true,
      "has_previous": false
    }
  }
}

Rate Limiting

Rate limits vary by endpoint and tenant configuration. When exceeded:

HTTP 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

API Endpoints

Files

Method	Endpoint	Description
POST	/files/upload	Upload a file
GET	/files/{file_id}	Get download URL
GET	/files/{file_id}/metadata	Get file metadata
GET	/files	List files
DELETE	/files/{file_id}	Delete a file

File Contexts

Method	Endpoint	Description
POST	/contexts	Create context
GET	/contexts	List contexts
GET	/contexts/{context_key}	Get context details
PATCH	/contexts/{context_key}	Update context

API Keys

Method	Endpoint	Description
POST	/api-keys	Create API key
GET	/api-keys	List API keys
GET	/api-keys/simple	List API keys (minimal)
GET	/api-keys/{api_key_id}	Get API key details
PATCH	/api-keys/{api_key_id}	Update API key
POST	/api-keys/{api_key_id}/enable	Enable API key
POST	/api-keys/{api_key_id}/disable	Disable API key
DELETE	/api-keys/{api_key_id}	Revoke API key

Statistics

Method	Endpoint	Description
GET	/stats	Dashboard statistics
GET	/stats/charts/api-calls	API calls chart data
GET	/stats/charts/storage	Storage chart data
GET	/stats/charts/uploads	Uploads chart data
GET	/stats/logs	API call logs
GET	/stats/logs/export	Export logs

Audit Logs

Method	Endpoint	Description
GET	/audit-logs	List audit logs
GET	/audit-logs/entity/{type}/{id}	Get entity audit history