Complete REST API reference for FastCMS — collections, records, authentication, files, webhooks, and more. All endpoints at /api/v1.

API Reference

All API endpoints are available at http://localhost:8000/api/v1.

Interactive Documentation

For interactive API exploration with live testing, visit:

Swagger UI: http://localhost:8000/docs

The Swagger UI allows you to:

Browse all available endpoints
Test API calls directly from the browser
View request/response schemas
Authenticate and test protected endpoints

Authentication

Include the access token in the Authorization header for protected endpoints:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Collections API

List Collections

GET /api/v1/collections

Get Collection

GET /api/v1/collections/{collection_id}

Create Collection

POST /api/v1/collections
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{
  "name": "posts",
  "type": "base",
  "schema": [
    {"name": "title", "type": "text", "validation": {"required": true}},
    {"name": "content", "type": "editor"},
    {"name": "published", "type": "bool"}
  ]
}

Update Collection

PATCH /api/v1/collections/{collection_id}
Authorization: Bearer ADMIN_TOKEN

Delete Collection

DELETE /api/v1/collections/{collection_id}
Authorization: Bearer ADMIN_TOKEN

Records API

List Records

GET /api/v1/collections/{collection_name}/records

Query Parameters:

Parameter	Description
`page`	Page number (default: 1)
`per_page`	Records per page (default: 30, max: 100)
`sort`	Sort field (prefix with `-` for descending)
`filter`	Filter expression (e.g., `status=published&&featured=true`)
`search`	Full-text search across all text fields

Example:

GET /api/v1/collections/products/records?page=1&per_page=20&sort=-created&filter=active=true

Search Records

Full-text search across all text, editor, email, and URL fields:

GET /api/v1/collections/posts/records?search=fastcms
GET /api/v1/collections/posts/records?search=fastcms&filter=status=published

Get Record

GET /api/v1/collections/{collection_name}/records/{record_id}

Create Record

POST /api/v1/collections/{collection_name}/records
Authorization: Bearer USER_TOKEN
Content-Type: application/json

{
  "data": {
    "title": "Product Name",
    "price": 99.99
  }
}

Update Record

PATCH /api/v1/collections/{collection_name}/records/{record_id}
Authorization: Bearer USER_TOKEN
Content-Type: application/json

{
  "data": {
    "price": 89.99
  }
}

Delete Record

DELETE /api/v1/collections/{collection_name}/records/{record_id}
Authorization: Bearer USER_TOKEN

Bulk Delete

POST /api/v1/collections/{collection_name}/records/bulk-delete
Authorization: Bearer USER_TOKEN
Content-Type: application/json

{"record_ids": ["id1", "id2", "id3"]}

Bulk Update

POST /api/v1/collections/{collection_name}/records/bulk-update
Authorization: Bearer USER_TOKEN
Content-Type: application/json

{
  "record_ids": ["id1", "id2"],
  "data": {"status": "published"}
}

Export to CSV

GET /api/v1/collections/{collection_name}/records/export/csv
Authorization: Bearer USER_TOKEN

Import from CSV

POST /api/v1/collections/{collection_name}/records/import/csv
Authorization: Bearer USER_TOKEN
Content-Type: multipart/form-data

file=@records.csv

Authentication API

Register

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123"
}

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123"
}

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "user": {"id": "...", "email": "user@example.com", "role": "user"}
}

Refresh Token

POST /api/v1/auth/refresh
Content-Type: application/json

{"refresh_token": "eyJ..."}

Get Current User

GET /api/v1/auth/me
Authorization: Bearer USER_TOKEN

Forgot Password

POST /api/v1/auth/forgot-password
Content-Type: application/json

{"email": "user@example.com"}

Reset Password

POST /api/v1/auth/reset-password
Content-Type: application/json

{
  "token": "reset-token-from-email",
  "new_password": "NewSecurePass123"
}

API Keys

Create API Key

POST /api/v1/api-keys
Authorization: Bearer USER_TOKEN
Content-Type: application/json

{
  "name": "Production Server",
  "scopes": ["read", "write"],
  "expires_at": "2026-01-01T00:00:00"
}

List API Keys

GET /api/v1/api-keys
Authorization: Bearer USER_TOKEN

Revoke API Key

DELETE /api/v1/api-keys/{key_id}
Authorization: Bearer USER_TOKEN

Files API

Upload File

POST /api/v1/files
Authorization: Bearer USER_TOKEN
Content-Type: multipart/form-data

file=@image.png&collection=products&record_id=abc123

Get File

GET /api/v1/files/{file_id}

Delete File

DELETE /api/v1/files/{file_id}
Authorization: Bearer USER_TOKEN

Webhooks API

Create Webhook

POST /api/v1/webhooks
Authorization: Bearer USER_TOKEN
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "collection_name": "posts",
  "events": ["create", "update", "delete"],
  "secret": "your-secret"
}

List Webhooks

GET /api/v1/webhooks
Authorization: Bearer USER_TOKEN

Update Webhook

PATCH /api/v1/webhooks/{webhook_id}
Authorization: Bearer USER_TOKEN

Delete Webhook

DELETE /api/v1/webhooks/{webhook_id}
Authorization: Bearer USER_TOKEN

Audit Logs API

List Audit Logs

GET /api/v1/audit
Authorization: Bearer ADMIN_TOKEN

Query Parameters: limit, offset, event_type, severity, user_id, ip_address, from_date, to_date

Get Security Events

GET /api/v1/audit/security?severity=critical
Authorization: Bearer ADMIN_TOKEN

Get Audit Statistics

GET /api/v1/audit/statistics
Authorization: Bearer ADMIN_TOKEN

System API

Health Check

GET /health

Connection Statistics

GET /api/v1/stats

Settings

GET /api/v1/settings
Authorization: Bearer ADMIN_TOKEN

POST /api/v1/settings
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{"key": "app_name", "value": "My App", "category": "app"}

Backups

POST /api/v1/backups
Authorization: Bearer ADMIN_TOKEN

GET /api/v1/backups
Authorization: Bearer ADMIN_TOKEN

POST /api/v1/backups/{filename}/restore
Authorization: Bearer ADMIN_TOKEN

DELETE /api/v1/backups/{filename}
Authorization: Bearer ADMIN_TOKEN

Response Format

Success Response

{
  "items": [...],
  "total": 100,
  "page": 1,
  "per_page": 30
}

Error Response

{
  "detail": "Error message",
  "code": "ERROR_CODE"
}

Common HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`204`	No Content (delete)
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found
`422`	Validation Error
`429`	Rate Limit Exceeded
`500`	Internal Server Error

API Reference

On this page