### Clone FreeFrame and Set Up Production Environment

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Clone the FreeFrame repository, create a production environment file from the example, and configure it with your specific credentials and settings. This is the initial setup for a production deployment.

```bash
git clone https://github.com/Techiebutler/freeframe.git
cd freeframe

cp .env.example .env.prod

nano .env.prod

docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build

docker compose --env-file .env.prod -f docker-compose.prod.yml ps
```

--------------------------------

### Clone and Run FreeFrame Development Environment

Source: https://github.com/techiebutler/freeframe/blob/main/CONTRIBUTING.md

Use these commands to clone the repository, set up the environment, and start the development server. Ensure Docker is installed and running.

```bash
git clone https://github.com/YOUR_USERNAME/freeframe.git
cd freeframe
cp .env.example .env
docker compose -f docker-compose.dev.yml up --build
# Open http://localhost:3000
```

--------------------------------

### Start Development Environment

Source: https://github.com/techiebutler/freeframe/blob/main/docs/contributing.md

Clone the repository, set up environment variables, and start the Dockerized development services. This command builds the images and starts all necessary services including PostgreSQL, Redis, MinIO, API, Celery workers, and the Next.js frontend.

```bash
git clone https://github.com/YOUR_USERNAME/freeframe.git
cd freeframe
cp .env.example .env
docker compose -f docker-compose.dev.yml up --build
open http://localhost:3000
```

--------------------------------

### List Share Links for a Project

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use GET to retrieve a list of all share links associated with a specific project. Requires project UUID.

```bash
curl -X GET http://localhost:8000/projects/project-uuid/share-links \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Clone and Run FreeFrame for Development

Source: https://github.com/techiebutler/freeframe/blob/main/README.md

Clone the repository, set up the environment, and start the development server using Docker Compose. Access the application at http://localhost:3000. The first user to sign up becomes the super admin.

```bash
git clone https://github.com/Techiebutler/freeframe.git
cd freeframe
cp .env.example .env
docker compose -f docker-compose.dev.yml up --build
```

--------------------------------

### Deploy FreeFrame in Production

Source: https://github.com/techiebutler/freeframe/blob/main/README.md

Prepare for production deployment by copying the example environment file and editing it with your specific credentials and configurations for S3, email, and domain settings. Use Docker Compose to build and run the production environment in detached mode.

```bash
cp .env.example .env.prod
# Edit .env.prod — set your credentials, S3, email config
# For SSL: also set DOMAIN and ACME_EMAIL (Traefik auto-provisions Let's Encrypt certs)
docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build
```

--------------------------------

### Initiate Multipart Upload

Source: https://context7.com/techiebutler/freeframe/llms.txt

Starts a multipart upload process for large media files. This step requires project ID, asset details, and file information. It returns essential IDs for subsequent steps.

```bash
curl -X POST http://localhost:8000/upload/initiate \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "asset_name": "Hero Video Take 3",
    "original_filename": "hero_video_take3.mp4",
    "mime_type": "video/mp4",
    "file_size_bytes": 1073741824,
    "folder_id": null
  }'
```

--------------------------------

### List Trash (Deleted Items)

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use GET to retrieve a list of deleted items within a project. Supports pagination with skip and limit parameters.

```bash
curl -X GET "http://localhost:8000/projects/project-uuid/trash?skip=0&limit=50" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Get Share Link Activity Log

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use GET to retrieve the activity log for a specific share link, including views and downloads. Supports pagination.

```bash
curl -X GET "http://localhost:8000/share/share-token/activity?page=1&per_page=50" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Get Project Details

Source: https://context7.com/techiebutler/freeframe/llms.txt

Fetches detailed information about a specific project, including statistics like asset count, storage usage, and member count. Requires authentication and a project ID.

```bash
# Get project details with stats
curl -X GET http://localhost:8000/projects/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Browser EventSource Example for Real-Time Events

Source: https://context7.com/techiebutler/freeframe/llms.txt

Demonstrates how to use the EventSource API in a web browser to connect to the real-time events stream. Handles incoming messages and errors.

```javascript
const eventSource = new EventSource(
  `http://localhost:8000/events/${projectId}?token=${accessToken}`
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data.payload);
  // Handle: asset_uploaded, comment_added, approval_changed, etc.
};

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
  eventSource.close();
};
```

--------------------------------

### Follow All Service Logs

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Use this command to stream logs from all services in the Docker Compose setup. Useful for real-time monitoring during development or debugging.

```bash
docker compose --env-file .env.prod -f docker-compose.prod.yml logs -f
```

--------------------------------

### Get Users by IDs (Batch)

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieves multiple users by providing a comma-separated list of their IDs. Requires authentication.

```bash
curl -X GET http://localhost:8000/users?ids=uuid1,uuid2,uuid3 \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Get Single Asset with Latest Version

Source: https://context7.com/techiebutler/freeframe/llms.txt

Fetches details of a specific asset, including its latest version and associated files. The response provides metadata and a thumbnail URL.

```bash
curl -X GET http://localhost:8000/assets/asset-uuid \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Get Folder Tree Structure

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieve the hierarchical structure of folders within a project. Requires authentication.

```bash
curl -X GET http://localhost:8000/projects/project-uuid/folder-tree \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Get Folder Share Contents

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use GET on a public endpoint to retrieve assets within a shared folder. Supports pagination.

```bash
curl -X GET "http://localhost:8000/share/share-token/assets?folder_id=subfolder-uuid&page=1&per_page=50"
```

--------------------------------

### Check Service Logs

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Retrieves logs for a specific Docker service. Useful for troubleshooting services that are not starting.

```bash
# Check logs for a specific service
docker compose --env-file .env.prod -f docker-compose.prod.yml logs api
docker compose --env-file .env.prod -f docker-compose.prod.yml logs worker
docker compose --env-file .env.prod -f docker-compose.prod.yml logs web
docker compose --env-file .env.prod -f docker-compose.prod.yml logs traefik
```

--------------------------------

### List Notifications

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use GET to retrieve a list of user notifications, optionally filtering for unread items. Defaults to the most recent 50.

```bash
curl -X GET "http://localhost:8000/me/notifications?unread_only=true" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Get Current User Information

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieve details about the currently authenticated user. Requires a valid access token.

```bash
# Get current user info
curl -X GET http://localhost:8000/auth/me \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Create a New Project

Source: https://context7.com/techiebutler/freeframe/llms.txt

Initiates the creation of a new project. Requires authentication and provides project details like name, description, and type.

```bash
# Create a new project
curl -X POST http://localhost:8000/projects \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Commercial Shoot Q1",
    "description": "Spring marketing campaign video assets",
    "project_type": "commercial"
  }'
```

--------------------------------

### Get Stream URL via Share Link

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use GET on a public endpoint to obtain the stream URL for an asset via a share link. Set `download=false` for streaming.

```bash
curl -X GET "http://localhost:8000/share/share-token/stream/asset-uuid?download=false"
```

--------------------------------

### Create Share Link for Project

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use POST to create a share link for an entire project. Specify title and permission level.

```bash
curl -X POST http://localhost:8000/projects/project-uuid/share \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Full Project Access", "permission": "comment"}'
```

--------------------------------

### Create a Folder

Source: https://context7.com/techiebutler/freeframe/llms.txt

Create a new folder within a project. Specify the parent folder ID or null for a root folder. Requires authentication.

```bash
curl -X POST http://localhost:8000/projects/project-uuid/folders \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Raw Footage", "parent_id": null}'
```

--------------------------------

### Configure Automated Daily Backups

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Sets up a cron job to perform daily database backups and automatically delete backups older than 30 days. Remember to replace `/path/to/freeframe` and `/path/to/backups` with your actual paths.

```bash
# Edit crontab
crontab -e

# Add this line (runs daily at 2 AM, keeps 30 days)
0 2 * * * cd /path/to/freeframe && docker compose --env-file .env.prod -f docker-compose.prod.yml exec -T postgres pg_dump -U freeframe freeframe | gzip > /path/to/backups/freeframe_$(date +\%Y\%m\%d).sql.gz && find /path/to/backups -name "freeframe_*.sql.gz" -mtime +30 -delete
```

--------------------------------

### Create Multi-Item Share Link

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use POST to create a share link for a selection of assets and folders within a project. Requires project UUID, lists of asset/folder IDs, title, and permission.

```bash
curl -X POST http://localhost:8000/projects/project-uuid/share/multi \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_ids": ["asset-1", "asset-2"],
    "folder_ids": ["folder-1"],
    "title": "Selected Items for Review",
    "permission": "comment"
  }'
```

--------------------------------

### Build the Web Application

Source: https://github.com/techiebutler/freeframe/blob/main/CONTRIBUTING.md

Build the web application using pnpm. This command is used to ensure the frontend is correctly built before submitting a pull request.

```bash
pnpm --filter web build
```

--------------------------------

### Validate Share Link

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use GET on a public endpoint to validate a share link token and check password if required. Logs link opens.

```bash
curl -X GET "http://localhost:8000/share/share-token?password=SecurePass123&log_open=true"
```

--------------------------------

### Health Check Endpoint

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

The API exposes a GET /health endpoint that returns a JSON object with a status field. This is useful for external monitoring services.

```json
{ "status": "ok" }
```

--------------------------------

### Create Share Link for Folder

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use POST to create a share link for a folder. Specify title and permission level (e.g., 'view', 'comment').

```bash
curl -X POST http://localhost:8000/folders/folder-uuid/share \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Dailies - Week 3",
    "permission": "view",
    "allow_download": true
  }'
```

--------------------------------

### Subscribe to Project Events (SSE)

Source: https://context7.com/techiebutler/freeframe/llms.txt

Establishes a Server-Sent Events connection to receive real-time updates for project activities. Use an EventSource client in the browser.

```bash
curl -N -H "Accept: text/event-stream" \
  "http://localhost:8000/events/project-uuid?token=<access_token>"
```

--------------------------------

### Bulk Move Assets and Folders

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use POST to move multiple assets and folders to a target folder simultaneously. Requires project UUID and lists of asset/folder IDs.

```bash
curl -X POST http://localhost:8000/projects/project-uuid/bulk-move \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_ids": ["asset-1", "asset-2"],
    "folder_ids": ["folder-1"],
    "target_folder_id": "destination-folder-uuid"
  }'
```

--------------------------------

### API Workers Scaling Guideline

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

The API_WORKERS environment variable controls the number of gunicorn worker processes. A recommended starting point is (2 x CPU cores) + 1.

```text
API_WORKERS = (2 x CPU cores) + 1
```

--------------------------------

### Invite New User

Source: https://context7.com/techiebutler/freeframe/llms.txt

Invites a new user to the system by providing their email and name. This action is restricted to administrators.

```bash
curl -X POST http://localhost:8000/users/invite \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"email": "newuser@example.com", "name": "New User"}'
```

--------------------------------

### Login with Email and Password

Source: https://context7.com/techiebutler/freeframe/llms.txt

Authenticate users using their email and password. This is a traditional login method.

```bash
# Login with email and password
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePassword123!"}'
```

--------------------------------

### Get Streaming URL for Asset

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieves the streaming URL for an asset. For videos, this provides an HLS manifest URL. For images and audio, it provides a presigned URL for direct download.

```bash
curl -X GET "http://localhost:8000/assets/asset-uuid/stream?download=false" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### List All Projects

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieves a list of all projects accessible to the authenticated user, including public projects and those the user is a member of. Requires authentication.

```bash
# List all projects (includes public projects and user's memberships)
curl -X GET http://localhost:8000/projects \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Get Presigned URL for Upload Part

Source: https://context7.com/techiebutler/freeframe/llms.txt

Obtains a presigned URL to upload a specific part of a multipart upload. This is used for uploading chunks of the large media file directly to S3.

```bash
curl -X POST http://localhost:8000/upload/presign-part \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_key": "raw/project-id/asset-id/version-id/original.mp4",
    "upload_id": "multipart-upload-id",
    "part_number": 1
  }'
```

--------------------------------

### Configure External PostgreSQL Database

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Set the DATABASE_URL environment variable to connect to an external PostgreSQL instance. Ensure migrations are run manually on first deploy.

```dotenv
DATABASE_URL=postgresql://user:password@your-db-host:5432/freeframe
```

```bash
docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm api sh -c "cd /workspace/apps/api && alembic upgrade head"
```

--------------------------------

### Direct Share Asset with User

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use POST to share an asset directly with a user via email, sending a notification. Specify the user's email and desired permission.

```bash
curl -X POST http://localhost:8000/assets/asset-uuid/share/user \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "collaborator@example.com",
    "permission": "comment"
  }'
```

--------------------------------

### List Assets in Project

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieves a list of assets within a specified project. Supports filtering by folder ID. Query parameters can be used to include failed assets or specify a folder.

```bash
curl -X GET "http://localhost:8000/projects/project-uuid/assets?folder_id=root" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Create Share Link for Asset

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use POST to create a password-protected, expiring share link for an asset. Customize title, description, password, expiry, permissions, and appearance.

```bash
curl -X POST http://localhost:8000/assets/asset-uuid/share \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Client Review - Hero Video",
    "description": "Please review and provide feedback",
    "password": "SecurePass123",
    "expires_at": "2024-02-01T23:59:59Z",
    "permission": "comment",
    "allow_download": false,
    "show_versions": true,
    "show_watermark": true,
    "appearance": {"accent_color": "#3B82F6"}
  }'
```

--------------------------------

### List All Users in System

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieves a list of all users currently in the system. This endpoint is intended for super administrators.

```bash
curl -X GET http://localhost:8000/admin/users \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Perform One-Time Database Backup

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Creates a compressed SQL dump of the Freeframe database. This is useful for manual backups.

```bash
# One-time backup
docker compose --env-file .env.prod -f docker-compose.prod.yml exec postgres \
  pg_dump -U freeframe freeframe | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
```

--------------------------------

### Restore Database from Backup

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Restores the Freeframe database from a compressed SQL dump file. Ensure the backup file is accessible.

```bash
# Restore from backup
gunzip -c backup_20260403_120000.sql.gz | \
  docker compose --env-file .env.prod -f docker-compose.prod.yml exec -T postgres \
  psql -U freeframe freeframe
```

--------------------------------

### Run Database Migrations Manually

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Executes database migrations manually. This is useful if migrations fail to run automatically on API startup.

```bash
# Run migrations manually
docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm api sh -c "cd /workspace/apps/api && alembic upgrade head"
```

--------------------------------

### Configure External Redis/Valkey Instance

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Set the REDIS_URL environment variable to connect to an external Redis or Valkey instance.

```dotenv
REDIS_URL=redis://:password@your-redis-host:6379/0
```

--------------------------------

### Enable SSL/TLS with Let's Encrypt using Traefik

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Configure FreeFrame for SSL/TLS by setting the DOMAIN, ACME_EMAIL, and FRONTEND_URL variables in your .env.prod file. Traefik will automatically handle certificate provisioning and renewal.

```bash
DOMAIN=your-domain.com
ACME_EMAIL=admin@your-domain.com
FRONTEND_URL=https://your-domain.com

docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build
```

--------------------------------

### Set User Password

Source: https://context7.com/techiebutler/freeframe/llms.txt

This endpoint allows users to set their password after initial magic code verification. Requires a valid access token.

```bash
# Set password after magic code verification
curl -X POST http://localhost:8000/auth/set-password \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"password": "SecurePassword123!"}'
```

--------------------------------

### List Folders with Parent Filter

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieve a list of folders within a project, optionally filtering by a parent folder ID. Requires authentication.

```bash
curl -X GET "http://localhost:8000/projects/project-uuid/folders?parent_id=root" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Run Frontend Tests

Source: https://github.com/techiebutler/freeframe/blob/main/docs/contributing.md

Execute frontend tests using npm within the Docker environment. Tests can be run for all tests or in watch mode for continuous testing during development.

```bash
docker compose -f docker-compose.dev.yml exec web npm test
```

```bash
docker compose -f docker-compose.dev.yml exec web npm run test:watch
```

--------------------------------

### Send Magic Code for Authentication

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use this endpoint to initiate the passwordless login flow by sending a magic code to the user's email. Ensure the email is valid.

```bash
# Send magic code to email for login/registration
curl -X POST http://localhost:8000/auth/send-magic-code \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

--------------------------------

### Reject an Asset Version

Source: https://context7.com/techiebutler/freeframe/llms.txt

Submit a rejection for a specific asset version, including a note explaining the reason. Requires authentication.

```bash
curl -X POST http://localhost:8000/assets/asset-uuid/reject \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version_id": "version-uuid",
    "note": "Audio levels need adjustment at 2:30"
  }'
```

--------------------------------

### Configure External S3 Storage

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Configure S3_STORAGE, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, and optionally S3_REGION and S3_ENDPOINT for S3-compatible storage.

```dotenv
S3_STORAGE=s3
S3_BUCKET=your-bucket-name
S3_ACCESS_KEY=YOUR_ACCESS_KEY
S3_SECRET_KEY=YOUR_SECRET_KEY
S3_REGION=us-east-1
```

--------------------------------

### List All Approvals for an Asset

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieve a list of all approval records for a given asset. Requires authentication.

```bash
curl -X GET http://localhost:8000/assets/asset-uuid/approvals \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Open Firewall Ports

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Opens ports 80 and 443 on the server's firewall using `ufw`. This is necessary for external access to the web services.

```bash
sudo ufw allow 80,443/tcp
```

--------------------------------

### Check Memory Usage

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Use `free -m` to check memory usage. A warning sign is when swap is in use.

```bash
free -m
```

--------------------------------

### List Project Members

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieves a list of all members associated with a specific project, including their roles. Requires authentication and a project ID.

```bash
# List project members
curl -X GET http://localhost:8000/projects/550e8400-e29b-41d4-a716-446655440000/members \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### List All Versions of an Asset

Source: https://context7.com/techiebutler/freeframe/llms.txt

Retrieves a list of all historical versions associated with a specific asset. This is useful for tracking changes or accessing older versions.

```bash
curl -X GET http://localhost:8000/assets/asset-uuid/versions \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Create Feature Branch

Source: https://github.com/techiebutler/freeframe/blob/main/docs/contributing.md

Branching strategy for new features. Create a new branch from the 'main' branch with a descriptive name.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Upload Project Poster Image

Source: https://context7.com/techiebutler/freeframe/llms.txt

Uploads a poster image for a project. Supports JPEG, PNG, WebP, and GIF formats, with a maximum file size of 10MB. Requires authentication and a project ID.

```bash
# Upload project poster image (JPEG, PNG, WebP, GIF up to 10MB)
curl -X POST http://localhost:8000/projects/550e8400-e29b-41d4-a716-446655440000/poster \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@poster.jpg"
```

--------------------------------

### Approve an Asset Version

Source: https://context7.com/techiebutler/freeframe/llms.txt

Submit an approval for a specific asset version, optionally including a note. Requires authentication.

```bash
curl -X POST http://localhost:8000/assets/asset-uuid/approve \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version_id": "version-uuid",
    "note": "Approved for final delivery"
  }'
```

--------------------------------

### Create a Comment with Timecode and Annotation

Source: https://context7.com/techiebutler/freeframe/llms.txt

Post a new comment on an asset, including timecode ranges, mentions, and detailed annotations. Authentication is required.

```bash
curl -X POST http://localhost:8000/assets/asset-uuid/comments \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "The color grading looks great here! @john@example.com what do you think?",
    "version_id": "version-uuid",
    "timecode_start": 45.5,
    "timecode_end": 48.0,
    "visibility": "public",
    "mention_user_ids": ["john-user-uuid"],
    "annotation": {
      "drawing_data": {"type": "arrow", "points": [[100,200], [300,400]]},
      "frame_number": 1365
    }
  }'
```

--------------------------------

### Search Users by Name or Email

Source: https://context7.com/techiebutler/freeframe/llms.txt

Searches for users based on a query string that can match names or email addresses. Requires authentication.

```bash
curl -X GET "http://localhost:8000/users/search?q=john" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Follow Specific Service Logs

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Stream logs for a particular service, such as the 'api' service, using this command. Helps in isolating issues to a specific component.

```bash
docker compose --env-file .env.prod -f docker-compose.prod.yml logs -f api
```

--------------------------------

### Configure External SMTP for Email

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Set MAIL_PROVIDER to 'smtp' and configure SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, and SMTP_USE_TLS for external SMTP services.

```dotenv
MAIL_PROVIDER=smtp
MAIL_FROM_ADDRESS=noreply@your-domain.com
MAIL_FROM_NAME=FreeFrame
SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASSWORD=your-smtp-password
SMTP_USE_TLS=true
```

--------------------------------

### Check Database Connections

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Check the number of active database connections against the maximum allowed. Exceeding 80% of the maximum is a warning sign.

```bash
docker compose exec postgres psql -U freeframe -c "SELECT count(*) FROM pg_stat_activity;"
```

--------------------------------

### Upload New Version to Existing Asset

Source: https://context7.com/techiebutler/freeframe/llms.txt

Initiates the upload process for a new version of an existing asset. This requires the asset ID and details about the new file, such as its filename, MIME type, and size.

```bash
curl -X POST http://localhost:8000/assets/asset-uuid/versions \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "original_filename": "hero_video_v2.mp4",
    "mime_type": "video/mp4",
    "file_size_bytes": 524288000
  }'
```

--------------------------------

### Update User Preferences

Source: https://context7.com/techiebutler/freeframe/llms.txt

Allows users to update their preferences, such as theme and notification settings. Requires a valid access token.

```bash
# Update user preferences (theme, etc.)
curl -X PATCH http://localhost:8000/auth/me/preferences \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"theme": "dark", "notifications_enabled": true}'
```

--------------------------------

### Add Member to Project (Owner Only)

Source: https://context7.com/techiebutler/freeframe/llms.txt

Use this endpoint to add a new member to a project. Requires owner privileges. The request body specifies the user ID and their role within the project.

```bash
curl -X POST http://localhost:8000/projects/550e8400-e29b-41d4-a716-446655440000/members \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-uuid-to-add",
    "role": "editor"
  }'
```

--------------------------------

### Admin API

Source: https://context7.com/techiebutler/freeframe/llms.txt

Endpoints for system administration tasks, including user management and role changes.

```APIDOC
## GET /admin/users

### Description
Lists all users in the system. This endpoint is intended for administrators.

### Method
GET

### Endpoint
/admin/users

### Response
#### Success Response (200)
A list of all users in the system.

## PATCH /admin/users/{user-uuid}/role

### Description
Promotes or demotes a user's administrative role. This endpoint is intended for administrators.

### Method
PATCH

### Endpoint
/admin/users/{user-uuid}/role

### Parameters
#### Path Parameters
- **user-uuid** (string) - Required - The unique identifier of the user whose role is to be modified.
#### Request Body
- **is_admin** (boolean) - Required - Set to `true` to promote to admin, `false` to demote.

### Request Example
```json
{
  "is_admin": true
}
```

### Response
#### Success Response (200)
Confirmation of the role change.
```

--------------------------------

### Run Backend Tests

Source: https://github.com/techiebutler/freeframe/blob/main/docs/contributing.md

Execute backend tests using pytest within the Docker environment. Options include running all tests, verbose output, or targeting specific test files.

```bash
docker compose -f docker-compose.dev.yml exec api pytest
```

```bash
docker compose -f docker-compose.dev.yml exec api pytest -v
```

```bash
docker compose -f docker-compose.dev.yml exec api pytest apps/api/tests/test_auth.py
```

--------------------------------

### Check All Service Statuses

Source: https://github.com/techiebutler/freeframe/blob/main/docs/deployment.md

Displays the status of all services managed by Docker Compose. Helps in identifying which services are running or stopped.

```bash
# Check all service statuses
docker compose --env-file .env.prod -f docker-compose.prod.yml ps
```