SnapOtter

https://docs.snapotter.com
Admin
SnapOtter is a self-hosted image manipulator with 50+ tools, local AI capabilities, REST API,...
Tokens:59,849
Snippets:675
Trust Score:3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and Run Snapotter

Source: https://docs.snapotter.com/llms-full.txt

Clone the repository, install dependencies using pnpm, and start the development servers for the frontend and backend.

```bash
git clone https://github.com/snapotter-hq/snapotter.git
cd snapotter
pnpm install
pnpm dev
```

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

### Install Dependencies and Start Dev Servers

Source: https://docs.snapotter.com/guide/contributing

Installs project dependencies using pnpm and starts the development servers for the web and API. Ensure Node.js 22+ and pnpm 9+ are installed.

```bash
git clone https://github.com.com/<your-username>/snapotter.git
cd snapotter

pnpm install

pnpm dev
```

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

### Set up Development Environment for Translations

Source: https://docs.snapotter.com/guide/translations

Clone the SnapOtter repository and install dependencies to begin contributing translations. This is the initial setup step for local development.

```bash
git clone https://github.com/<your-username>/snapotter.git
cd snapotter
pnpm install
```

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

### Start Development Servers

Source: https://docs.snapotter.com/guide/developer

Start the local development servers for the frontend and backend.

```bash
pnpm dev
```

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

### Build and Run SnapOtter from Source

Source: https://docs.snapotter.com/guide/getting-started

These commands clone the SnapOtter repository, navigate into the directory, install dependencies using pnpm, and start the development server. Prerequisites include Node.js, pnpm, Python, and Git.

```bash
git clone https://github.com/snapotter-hq/SnapOtter.git
cd SnapOtter
pnpm install
pnpm dev
```

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

### Run SnapOtter Docker Image with GPU Acceleration

Source: https://docs.snapotter.com/guide/docker-tags

Starts the SnapOtter container with GPU support enabled using the NVIDIA Container Toolkit. Assumes NVIDIA drivers and toolkit are installed.

```bash
docker run -d --name SnapOtter --gpus all -p 1349:1349 -v SnapOtter-data:/data snapotter/snapotter:latest
```

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

### Run SnapOtter Docker Image (Quick Start)

Source: https://docs.snapotter.com/guide/docker-tags

Starts the SnapOtter container in detached mode, mapping the default port and creating a persistent volume for data.

```bash
docker run -d --name SnapOtter -p 1349:1349 -v SnapOtter-data:/data snapotter/snapotter:latest
```

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

### Clone and Install Dependencies

Source: https://docs.snapotter.com/guide/developer

Clone the SnapOtter repository and install project dependencies using pnpm.

```bash
git clone https://github.com/snapotter-hq/snapotter.git
cd snapotter
pnpm install
```

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

### Backend Tool Route Example

Source: https://docs.snapotter.com/llms-full.txt

A minimal example of a backend route for a new tool using Fastify and Zod for schema validation. It demonstrates how to define settings and process image buffers.

```typescript
import { z } from "zod";
import type { FastifyInstance } from "fastify";
import { createToolRoute } from "../tool-factory.js";

const settingsSchema = z.object({
  intensity: z.number().min(0).max(100).default(50),
});

export function registerMyTool(app: FastifyInstance) {
  createToolRoute(app, {
    toolId: "my-tool",
    settingsSchema,
    async process(inputBuffer, settings, filename) {
      // Use sharp or other libraries to process the image
      const sharp = (await import("sharp")).default;
      const result = await sharp(inputBuffer)
        // ... your processing logic
        .toBuffer();

      return {
        buffer: result,
        filename: filename.replace(/\.[^.]+$/, ".png"),
        contentType: "image/png",
      };
    },
  });
}
```

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

### Get All Settings

Source: https://docs.snapotter.com/api/rest

Retrieve all runtime configuration settings. This endpoint is accessible to any authenticated user.

```bash
GET /api/v1/settings
```

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

### POST /api/v1/admin/features/:bundleId/install

Source: https://docs.snapotter.com/api/rest

Installs a specified AI feature bundle asynchronously. Returns a job ID for tracking the installation progress.

```APIDOC
## POST /api/v1/admin/features/:bundleId/install

### Description
Install a feature bundle (async, returns `jobId` for progress tracking).

### Method
POST

### Endpoint
/api/v1/admin/features/:bundleId/install

### Parameters
#### Path Parameters
- **bundleId** (string) - Required - The ID of the feature bundle to install.

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the asynchronous job for installation progress tracking.
```

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

### Get All Settings

Source: https://docs.snapotter.com/api/rest

Retrieve all runtime configuration settings. Accessible by any authenticated user.

```APIDOC
## GET /api/v1/settings

### Description
Retrieves all runtime key-value configuration settings. This endpoint is readable by any authenticated user.

### Method
GET

### Endpoint
/api/v1/settings

### Response
#### Success Response (200)
- **settings** (object) - An object containing all key-value settings.

#### Response Example
```json
{
  "disabledTools": ["legacy_tool"],
  "enableExperimentalTools": "true",
  "loginAttemptLimit": 5
}
```
```

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

### Start SnapOtter Container

Source: https://docs.snapotter.com/guide/deployment

Execute this command after creating the docker-compose.yml file to start the SnapOtter service in detached mode.

```bash
docker compose up -d
```

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

### GET /api/v1/features

Source: https://docs.snapotter.com/api/rest

Lists all available AI feature bundles and their current installation status within the Docker environment.

```APIDOC
## GET /api/v1/features

### Description
List all feature bundles and their install status.

### Method
GET

### Endpoint
/api/v1/features

### Response
#### Success Response (200)
- **features** (array) - List of feature bundles with their status
```

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

### Check GPU Detection in Logs

Source: https://docs.snapotter.com/guide/deployment

After starting the GPU-enabled container, check the logs to confirm that CUDA acceleration has been detected. This is crucial for verifying the GPU setup.

```bash
docker logs SnapOtter 2>&1 | head -20
# Look for: [INFO] GPU detected — AI tools will use CUDA acceleration
```

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

### Start GPU SnapOtter Container

Source: https://docs.snapotter.com/guide/deployment

Use this command to deploy the GPU-enabled SnapOtter service. This command assumes the configuration is saved in 'docker-compose-gpu.yml'.

```bash
docker compose -f docker-compose-gpu.yml up -d
```

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

### Run Cloudflare Tunnel

Source: https://docs.snapotter.com/guide/deployment

Start a Cloudflare Tunnel to expose your local SnapOtter instance to the internet. Note the upload limit for free plans.

```bash
cloudflared tunnel --url http://localhost:1349
```

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

### Run SnapOtter with Docker and GPU Acceleration

Source: https://docs.snapotter.com/guide/getting-started

This command is similar to the basic Docker run command but includes the `--gpus all` flag for enabling NVIDIA GPU acceleration for specific AI features. Ensure the NVIDIA Container Toolkit is installed.

```bash
docker run -d --name SnapOtter -p 1349:1349 --gpus all -v SnapOtter-data:/data snapotter/snapotter:latest
```

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

### Use Session Token for API Request

Source: https://docs.snapotter.com/llms-full.txt

This example shows how to use the obtained session token in the Authorization header to make an authenticated API call.

```bash
# Use token
curl http://localhost:1349/api/v1/tools/resize \
  -H "Authorization: Bearer <session-token>"
```

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

### Docker Compose Configuration for SnapOtter

Source: https://docs.snapotter.com/guide/configuration

This snippet shows a typical Docker Compose setup for SnapOtter. It demonstrates how to map ports, volumes, and set essential environment variables for authentication, upload size, and concurrent jobs.

```yaml
services:
  SnapOtter:
    image: snapotter/snapotter:latest
    ports:
      - "1349:1349"
    volumes:
      - SnapOtter-data:/data
      - SnapOtter-workspace:/tmp/workspace
    environment:
      - AUTH_ENABLED=true
      - DEFAULT_USERNAME=admin
      - DEFAULT_PASSWORD=changeme
      - MAX_UPLOAD_SIZE_MB=200
      - CONCURRENT_JOBS=4
      - FILE_MAX_AGE_HOURS=12
    restart: unless-stopped
```

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

### SnapOtter Docker Compose Configuration with GPU

Source: https://docs.snapotter.com/llms-full.txt

This is a sample docker-compose.yml configuration for SnapOtter, enabling GPU support through resource reservations. Ensure the NVIDIA Container Toolkit is installed.

```yaml
services:
  SnapOtter:
    image: snapotter/snapotter:latest
    container_name: SnapOtter
    ports:
      - "1349:1349"
    volumes:
      - SnapOtter-data:/data
      - SnapOtter-workspace:/tmp/workspace
    environment:
      - AUTH_ENABLED=true
      - DEFAULT_USERNAME=admin
      - DEFAULT_PASSWORD=admin
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1349/api/v1/health"]
      interval: 30s
      timeout: 5s
      start_period: 60s
      retries: 3
    shm_size: "2gb"                # Required for PyTorch CUDA shared memory
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all           # Or set to 1 for a specific GPU
              capabilities: [gpu]
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  SnapOtter-data:
  SnapOtter-workspace:
```

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

### Get Specific Setting

Source: https://docs.snapotter.com/api/rest

Retrieve the value of a specific runtime configuration setting by its key. Accessible to any authenticated user.

```bash
GET /api/v1/settings/:key
```

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

### Docker Compose for CPU Deployment

Source: https://docs.snapotter.com/guide/deployment

Use this configuration to deploy SnapOtter for CPU-only usage. Ensure Docker Compose is installed and then run 'docker compose up -d'. The application will be accessible at http://localhost:1349.

```yaml
# docker-compose.yml — Copy this file and run: docker compose up -d
services:
  SnapOtter:
    image: snapotter/snapotter:latest    # or ghcr.io/snapotter-hq/snapotter:latest
    container_name: SnapOtter
    ports:
      - "1349:1349"                # Web UI + API
    volumes:
      - SnapOtter-data:/data           # Database, AI models, user files (PERSISTENT)
      - SnapOtter-workspace:/tmp/workspace  # Temp processing files (can be tmpfs)
    environment:
      # --- Authentication ---
      - AUTH_ENABLED=true          # Set to false to disable login entirely
      - DEFAULT_USERNAME=admin     # First-run admin username
      - DEFAULT_PASSWORD=admin     # First-run admin password (you'll be forced to change it)

      # --- Limits (0 = unlimited) ---
      # - MAX_UPLOAD_SIZE_MB=0     # Per-file upload limit in MB
      # - MAX_BATCH_SIZE=0         # Max files per batch request
      # - RATE_LIMIT_PER_MIN=0     # API rate limit (0 = disabled, 100 = recommended for public)
      # - MAX_USERS=0              # Max user accounts

      # --- Networking ---
      # - TRUST_PROXY=true         # Trust X-Forwarded-For headers (set false if not behind a proxy)

      # --- Bind mount permissions ---
      # - PUID=1000                # Match your host user's UID (run: id -u)
      # - PGID=1000                # Match your host user's GID (run: id -g)
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1349/api/v1/health"]
      interval: 30s
      timeout: 5s
      start_period: 60s
      retries: 3
    shm_size: "2gb"            # Needed for Python ML shared memory
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  SnapOtter-data:       # Named volume — Docker manages permissions automatically
  SnapOtter-workspace:

```

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

### Login and Get Session Token

Source: https://docs.snapotter.com/llms-full.txt

Authenticate with the API by providing username and password to obtain a session token.

```APIDOC
## POST /api/auth/login

### Description
Logs in a user and returns a session token.

### Method
POST

### Endpoint
/api/auth/login

### Parameters
#### Request Body
- **username** (string) - Required - The username for login.
- **password** (string) - Required - The password for login.

### Request Example
{
  "username": "admin",
  "password": "admin"
}

### Response
#### Success Response (200)
- **token** (string) - The session token for authenticated requests.

#### Response Example
{
  "token": "<session-token>"
}
```

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

### Login and Get Session Token

Source: https://docs.snapotter.com/llms-full.txt

Use this snippet to log in with username and password to obtain a session token. The token is required for subsequent authenticated requests.

```bash
# Login
curl -X POST http://localhost:1349/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'
# Returns: {"token":"<session-token>"}
```

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

### OIDC Callback URI Example

Source: https://docs.snapotter.com/llms-full.txt

The required redirect URI format for configuring your OIDC provider. This URI is used by the provider to send authentication responses back to SnapOtter.

```text
${EXTERNAL_URL}/api/auth/oidc/callback
```

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

### Define a New Image Processing Tool Route

Source: https://docs.snapotter.com/guide/developer

Example of creating a new backend route for an image processing tool using Fastify and Zod for schema validation.

```typescript
import {
  z,
} from "zod";
import type { FastifyInstance } from "fastify";
import { createToolRoute } from "../tool-factory.js";

const settingsSchema = z.object({
  intensity: z.number().min(0).max(100).default(50),
});

export function registerMyTool(app: FastifyInstance) {
  createToolRoute(app, {
    toolId: "my-tool",
    settingsSchema,
    async process(inputBuffer, settings, filename) {
      // Use sharp or other libraries to process the image
      const sharp = (await import("sharp")).default;
      const result = await sharp(inputBuffer)
        // ... your processing logic
        .toBuffer();

      return {
        buffer: result,
        filename: filename.replace(/\.[^.]+$/, ".png"),
        contentType: "image/png",
      };
    },
  });
}
```

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

### Docker Compose for GPU Deployment

Source: https://docs.snapotter.com/guide/deployment

This configuration enables GPU acceleration for AI tools. It requires an NVIDIA GPU and the nvidia-container-toolkit to be installed. Deploy using 'docker compose -f docker-compose-gpu.yml up -d'.

```yaml
# docker-compose-gpu.yml — Requires: NVIDIA GPU + nvidia-container-toolkit
# Install toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
services:
  SnapOtter:
    image: snapotter/snapotter:latest
    container_name: SnapOtter
    ports:
      - "1349:1349"
    volumes:
      - SnapOtter-data:/data
      - SnapOtter-workspace:/tmp/workspace
    environment:
      - AUTH_ENABLED=true
      - DEFAULT_USERNAME=admin
      - DEFAULT_PASSWORD=admin
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1349/api/v1/health"]
      interval: 30s
      timeout: 5s
      start_period: 60s
      retries: 3
    shm_size: "2gb"                # Required for PyTorch CUDA shared memory
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all           # Or set to 1 for a specific GPU
              capabilities: [gpu]
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  SnapOtter-data:
  SnapOtter-workspace:

```

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

### GET /api/v1/admin/features/disk-usage

Source: https://docs.snapotter.com/api/rest

Retrieves the total disk space consumed by all installed AI models.

```APIDOC
## GET /api/v1/admin/features/disk-usage

### Description
Get total disk usage of AI models.

### Method
GET

### Endpoint
/api/v1/admin/features/disk-usage

### Response
#### Success Response (200)
- **diskUsageBytes** (integer) - Total disk usage in bytes.
```

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

### Check GPU Status via Health Endpoint

Source: https://docs.snapotter.com/guide/docker-tags

Example of a GET request to the admin health endpoint after the first AI request to check GPU status.

```http
GET /api/v1/admin/health
{"ai": {"gpu": true}}
```

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

### Create and Use API Key

Source: https://docs.snapotter.com/api/rest

This snippet demonstrates how to create a new API key and subsequently use it for authentication. Remember to store the key securely as it is only shown once.

```bash
# Create a key (returns key once - store it)
curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-script"}'
# Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}

# Use the key
curl http://localhost:1349/api/v1/tools/resize \
  -H "Authorization: Bearer si_<your-key>"
```

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

### Recommended Deployment Resources (CPU)

Source: https://docs.snapotter.com/guide/deployment

Specifies recommended CPU and memory resources for AI tools running on CPU.

```yaml
deploy:
  resources:
    limits:
      cpus: '4'
      memory: 4G
```

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

### inpaint

Source: https://docs.snapotter.com/llms-full.txt

Removes objects from an image using an inpainting model, guided by a mask.

```APIDOC
## inpaint

### Description
Removes objects from an image using an inpainting model and a mask.

### Method
POST

### Endpoint
/erase-object

### Parameters
#### Request Body
- **maskData** (string) - Required - Base64-encoded PNG mask (white areas indicate regions to erase).
- **maskThreshold** (number) - Optional - Threshold for mask binarization (0-255).
```

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

### GET /api/v1/meme-templates/full/:filename

Source: https://docs.snapotter.com/api/rest

Serves the full-size image of a specified meme template.

```APIDOC
## GET /api/v1/meme-templates/full/:filename

### Description
Serve full-size template image.

### Method
GET

### Endpoint
/api/v1/meme-templates/full/:filename

### Parameters
#### Path Parameters
- **filename** (string) - Required - The filename of the meme template.
```

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

### Build All Workspaces

Source: https://docs.snapotter.com/guide/developer

Build all workspaces within the monorepo.

```bash
pnpm build
```

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

### Use API Key for Authentication

Source: https://docs.snapotter.com/llms-full.txt

Demonstrates how to use a generated API key in the Authorization header for authentication. API keys are prefixed with 'si_'.

```bash
# Use the key
curl http://localhost:1349/api/v1/tools/resize \
  -H "Authorization: Bearer si_<your-key>"
```

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

### Get File Thumbnail

Source: https://docs.snapotter.com/api/rest

Retrieve a 300px JPEG thumbnail for a specific file.

```APIDOC
## GET /api/v1/files/:id/thumbnail

### Description
Generates and returns a 300px JPEG thumbnail for a specified file.

### Method
GET

### Endpoint
/api/v1/files/:id/thumbnail

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the file for which to generate a thumbnail.

### Response
#### Success Response (200)
- A 300px JPEG image.

#### Response Example
(Binary data - JPEG image)
```

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

### Use Tool

Source: https://docs.snapotter.com/llms-full.txt

Applies a specific tool to a single input file with optional settings.

```APIDOC
## POST /api/v1/tools/<toolId>

### Description
Applies a specified tool to a single input file. The tool is identified by `<toolId>`.

### Method
POST

### Endpoint
/api/v1/tools/<toolId>

### Parameters
#### Path Parameters
- **toolId** (string) - Required - The identifier of the tool to use (e.g., `resize`, `crop`).

#### Request Body
- **file** (file) - Required - The input image file to process.
- **settings** (string) - Optional - A JSON string containing tool-specific settings.

### Request Example
```bash
curl -X POST http://localhost:1349/api/v1/tools/resize \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'settings={"width":800,"height":600}'
```

### Response
#### Success Response (200)
The processed file directly. The content type will depend on the tool and output format.
```

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

### GET /api/v1/meme-templates/thumbs/:filename

Source: https://docs.snapotter.com/api/rest

Serves the thumbnail version of a specified meme template image.

```APIDOC
## GET /api/v1/meme-templates/thumbs/:filename

### Description
Serve template thumbnail.

### Method
GET

### Endpoint
/api/v1/meme-templates/thumbs/:filename

### Parameters
#### Path Parameters
- **filename** (string) - Required - The filename of the meme template thumbnail.
```

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

### Get File Metadata

Source: https://docs.snapotter.com/api/rest

Retrieve metadata and version history for a specific file in the library.

```APIDOC
## GET /api/v1/files/:id

### Description
Retrieves detailed metadata and the version history for a specific file identified by its ID.

### Method
GET

### Endpoint
/api/v1/files/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the file.

### Response
#### Success Response (200)
- **file** (object) - The file's metadata and version information.

#### Response Example
```json
{
  "id": "file-id-1",
  "name": "image.jpg",
  "versions": [
    {
      "versionId": "v1",
      "createdAt": "2023-10-27T10:00:00Z"
    },
    {
      "versionId": "v2",
      "createdAt": "2023-10-27T11:00:00Z"
    }
  ]
}
```
```

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

### Minimum Deployment Resources

Source: https://docs.snapotter.com/guide/deployment

Specifies the minimum CPU and memory resources for basic SnapOtter deployment.

```yaml
deploy:
  resources:
    limits:
      cpus: '1'
      memory: 1G
```

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

### List Pipeline Tools

Source: https://docs.snapotter.com/api/rest

Get a list of all tool IDs that can be used in pipeline steps.

```APIDOC
## GET /api/v1/pipeline/tools

### Description
Retrieves a list of all valid tool IDs that can be specified in pipeline steps.

### Method
GET

### Endpoint
/api/v1/pipeline/tools

### Response
#### Success Response (200)
- **tools** (array) - A list of available tool IDs.

#### Response Example
```json
[
  "resize",
  "crop",
  "watermark"
]
```
```

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

### Project Structure Overview

Source: https://docs.snapotter.com/guide/architecture

Illustrates the monorepo layout, including applications and shared packages.

```tree
snapotter/
├── apps/
│   ├── api/          # Fastify backend
│   ├── web/          # React + Vite frontend
│   └── docs/         # This VitePress site
├── packages/
│   ├── image-engine/ # Sharp-based image operations
│   ├── ai/           # Python AI model bridge
│   └── shared/       # Types, constants, i18n
└── docker/           # Dockerfile and Compose config
```

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

### Full Deployment Resources (GPU)

Source: https://docs.snapotter.com/guide/deployment

Specifies recommended CPU, memory, and GPU resources for AI tools running on GPU.

```yaml
deploy:
  resources:
    limits:
      cpus: '4'
      memory: 8G
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]
```

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

### Bulk Rename Tool

Source: https://docs.snapotter.com/llms-full.txt

Renames multiple files based on a specified pattern and starting index.

```APIDOC
## Tool: Bulk Rename

### Description
Renames multiple files according to a defined pattern, allowing for sequential numbering, date insertion, and use of original filenames.

### Tool ID
`bulk-rename`

### Key Settings
- **pattern** (string) - The renaming pattern. Supports placeholders like `{n}` (sequence number), `{date}`, and `{original}` (original filename).
- **startIndex** (integer) - The starting number for the sequence if `{n}` is used.
- **padding** (integer) - The number of digits for the sequence number (e.g., 3 for `001`, `002`).
```

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

### Build Production Docker Image

Source: https://docs.snapotter.com/guide/developer

Build the full production Docker image locally using the provided Dockerfile. This command tags the image as 'snapotter:latest'.

```bash
docker build -f docker/Dockerfile -t snapotter:latest .
```

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

### GET /api/v1/meme-templates/fonts/:filename

Source: https://docs.snapotter.com/api/rest

Serves a font file used for rendering text on meme templates.

```APIDOC
## GET /api/v1/meme-templates/fonts/:filename

### Description
Serve font file used for meme text rendering.

### Method
GET

### Endpoint
/api/v1/meme-templates/fonts/:filename

### Parameters
#### Path Parameters
- **filename** (string) - Required - The filename of the font file.
```

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

### GET /api/v1/meme-templates

Source: https://docs.snapotter.com/api/rest

Lists all available meme templates, including information about their text box positions.

```APIDOC
## GET /api/v1/meme-templates

### Description
List all available meme templates with text box positions.

### Method
GET

### Endpoint
/api/v1/meme-templates

### Response
#### Success Response (200)
- **templates** (array) - List of meme templates with their details.
```

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

### Get Specific Setting

Source: https://docs.snapotter.com/api/rest

Retrieve a specific runtime setting by its key. Accessible by any authenticated user.

```APIDOC
## GET /api/v1/settings/:key

### Description
Retrieves a specific runtime setting by its key. This endpoint is readable by any authenticated user.

### Method
GET

### Endpoint
/api/v1/settings/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the setting to retrieve.

### Response
#### Success Response (200)
- **value** (any) - The value of the requested setting.

#### Response Example
```json
{
  "value": "[\"legacy_tool\"]"
}
```
```

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

### Verify Translations

Source: https://docs.snapotter.com/guide/translations

Run these commands to check for missing or mistyped keys, ensure correct formatting, and manually verify strings.

```bash
pnpm typecheck    # catches missing or mistyped keys
pnpm lint         # formatting check
pnpm dev          # manually verify strings appear correctly
```

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

### AI Feature Bundles

Source: https://docs.snapotter.com/llms-full.txt

Manage AI feature bundles, including installation, uninstallation, and disk usage monitoring.

```APIDOC
## GET /api/v1/features

### Description
List all feature bundles and their install status.

### Method
GET

### Endpoint
/api/v1/features

### Parameters
None

### Response
#### Success Response (200)
- **bundles** (array) - List of feature bundles and their status.

#### Response Example
```json
{
  "bundles": [
    {
      "id": "string",
      "name": "string",
      "installed": "boolean"
    }
  ]
}
```
```

```APIDOC
## POST /api/v1/admin/features/:bundleId/install

### Description
Install a feature bundle asynchronously. Returns a jobId for progress tracking.

### Method
POST

### Endpoint
/api/v1/admin/features/:bundleId/install

### Parameters
#### Path Parameters
- **bundleId** (string) - Required - The ID of the feature bundle to install.

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the asynchronous job.

#### Response Example
```json
{
  "jobId": "string"
}
```
```

```APIDOC
## POST /api/v1/admin/features/:bundleId/uninstall

### Description
Uninstall a feature bundle and clean up associated model files.

### Method
POST

### Endpoint
/api/v1/admin/features/:bundleId/uninstall

### Parameters
#### Path Parameters
- **bundleId** (string) - Required - The ID of the feature bundle to uninstall.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Feature bundle uninstalled successfully."
}
```
```

```APIDOC
## GET /api/v1/admin/features/disk-usage

### Description
Get the total disk usage of all installed AI models.

### Method
GET

### Endpoint
/api/v1/admin/features/disk-usage

### Parameters
None

### Response
#### Success Response (200)
- **diskUsageMB** (number) - Total disk usage in megabytes.

#### Response Example
```json
{
  "diskUsageMB": 1234.56
}
```
```

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

### Run Tests

Source: https://docs.snapotter.com/guide/developer

Execute all unit, integration, and end-to-end tests, or specific subsets.

```bash
pnpm test
```

```bash
pnpm test:unit
```

```bash
pnpm test:integration
```

```bash
pnpm test:e2e
```

```bash
pnpm test:coverage
```

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

### Build Docker Image with BuildKit Cache

Source: https://docs.snapotter.com/guide/developer

Build the Docker image locally using BuildKit for faster rebuilds by enabling cache mounts. This command also tags the image as 'snapotter:latest'.

```bash
DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile -t snapotter:latest .
```

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

### Create API Key

Source: https://docs.snapotter.com/llms-full.txt

Create a new API key by sending a POST request with a session token and a name for the key. The key is returned only once, so store it securely.

```bash
# Create a key (returns key once - store it)
curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-script"}'
# Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}
```

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

### Get Analytics Configuration

Source: https://docs.snapotter.com/llms-full.txt

Retrieve the analytics configuration, including PostHog key and Sentry DSN. Returns empty values if analytics are disabled.

```http
GET /api/v1/config/analytics
```

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

### Upgrade SnapOtter using Docker

Source: https://docs.snapotter.com/changelog

Pull the latest SnapOtter image for version 1.17.1.

```bash
docker pull snapotter/snapotter:1.17.1
```

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

### Get File Thumbnail

Source: https://docs.snapotter.com/api/rest

Retrieve a 300px JPEG thumbnail for a specific file. This is useful for quick previews without downloading the entire file.

```bash
GET /api/v1/files/:id/thumbnail
```

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

### Execute a Pipeline on Multiple Files (Batch)

Source: https://docs.snapotter.com/llms-full.txt

Applies a pipeline to multiple input files, returning a ZIP archive of the processed results. Replace <token> with your authorization token.

```bash
# Batch (multiple files → ZIP)
curl -X POST http://localhost:1349/api/v1/pipeline/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'pipeline={"steps":[{"toolId":"resize","settings":{"width":800}}]}'
```

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

### Get Audit Log

Source: https://docs.snapotter.com/llms-full.txt

Retrieve a paginated audit log with optional filtering by action, date range, page, and limit. This endpoint is accessible only to administrators.

```http
GET /api/v1/audit-log
```

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

### Docker Compose Configuration with GPU Acceleration

Source: https://docs.snapotter.com/guide/docker-tags

Configures SnapOtter service in Docker Compose to utilize NVIDIA GPU resources. Requires the 'deploy' section with device reservations.

```yaml
services:
  SnapOtter:
    image: snapotter/snapotter:latest
    ports:
      - "1349:1349"
    volumes:
      - SnapOtter-data:/data
      - SnapOtter-workspace:/tmp/workspace
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    restart: unless-stopped

volumes:
  SnapOtter-data:
  SnapOtter-workspace:
```

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

### Tool Usage

Source: https://docs.snapotter.com/api/rest

Explains the general pattern for using tools via the API, including single file and batch processing.

```APIDOC
## Using Tools

Every tool follows the same pattern:

```bash
# Single file
curl -X POST http://localhost:1349/api/v1/tools/<toolId> \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'settings={"width":800,"height":600}'

# Batch (returns ZIP)
curl -X POST http://localhost:1349/api/v1/tools/<toolId>/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'settings={...}'
```

* Upload is `multipart/form-data`.
* `settings` is a JSON string with tool-specific options.
* Response is the processed file directly (or a ZIP for batch).
* Progress is tracked via SSE (see [Progress Tracking](#progress-tracking)).
```

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

### GET /api/v1/config/analytics

Source: https://docs.snapotter.com/api/rest

Fetches the analytics configuration, including PostHog key, Sentry DSN, and sample rate. Returns empty values if analytics are disabled.

```APIDOC
## GET /api/v1/config/analytics

### Description
Get analytics configuration (PostHog key, Sentry DSN, sample rate). Returns empty values if `ANALYTICS_ENABLED=false`.

### Method
GET

### Endpoint
/api/v1/config/analytics

### Response
#### Success Response (200)
- **posthogKey** (string) - PostHog API key
- **sentryDsn** (string) - Sentry DSN URL
- **sampleRate** (number) - Analytics sample rate
```

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

### Progress Tracking via Server-Sent Events

Source: https://docs.snapotter.com/llms-full.txt

Demonstrates how to connect to the Server-Sent Events endpoint to receive real-time progress updates for long-running jobs like batch processing or pipelines.

```bash
curl http://localhost:1349/api/v1/progress/<jobId>
```

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

### Optimize for Web Preview

Source: https://docs.snapotter.com/api/rest

Provides a lightweight preview of an image optimized for web use, allowing for live parameter tuning. Returns the optimized image along with size headers.

```APIDOC
## POST /api/v1/tools/optimize-for-web/preview

### Description
Lightweight preview for live parameter tuning. Returns optimized image with size headers.

### Method
POST

### Endpoint
/api/v1/tools/optimize-for-web/preview
```

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

### GET /api/v1/audit-log

Source: https://docs.snapotter.com/api/rest

Retrieves a paginated list of audit log entries. This endpoint is restricted to administrators and supports filtering by action type and date range.

```APIDOC
## GET /api/v1/audit-log

### Description
Admin-only endpoint for reviewing security-relevant actions. Provides a paginated audit log with optional filters.

### Method
GET

### Endpoint
/api/v1/audit-log

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1)
- **limit** (integer) - Optional - Entries per page (default: 50, max: 100)
- **action** (string) - Optional - Filter by action type (e.g. `ROLE_CREATED`, `ROLE_DELETED`)
- **from** (string) - Optional - Filter entries after this ISO 8601 date
- **to** (string) - Optional - Filter entries before this ISO 8601 date

### Response
#### Success Response (200)
- **audit entries** (array) - Description of audit log entries
- **pagination** (object) - Description of pagination details
```

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

### SnapOtter Interactive API Docs and OpenAPI Spec

Source: https://docs.snapotter.com/llms.txt

This snippet provides the URLs to access the interactive API documentation and the OpenAPI specification for a running SnapOtter instance.

```text
Interactive API docs on running instance: /api/docs
OpenAPI spec on running instance: /api/v1/openapi.yaml
```

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

### Create New User

Source: https://docs.snapotter.com/llms-full.txt

Creates a new user account in the system. Requires administrator privileges.

```APIDOC
## POST /api/auth/register

### Description
Creates a new user account. This endpoint is restricted to administrators.

### Method
POST

### Endpoint
/api/auth/register

### Parameters
#### Request Body
- **username** (string) - Required - The username for the new user.
- **password** (string) - Required - The initial password for the new user.
- **role** (string) - Optional - The role for the new user (e.g., 'admin', 'user'). Defaults to 'user'.

### Response
#### Success Response (200)
Indicates the user was successfully created. The response body may contain the new user's ID or details.
```

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

### Get File Metadata and Version Chain

Source: https://docs.snapotter.com/api/rest

Retrieve detailed metadata for a specific file, including its version history. This allows you to inspect the lineage and changes of a file over time.

```bash
GET /api/v1/files/:id
```

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

### Monorepo Commands

Source: https://docs.snapotter.com/llms-full.txt

A list of common commands for managing the Snapotter monorepo, including building, testing, linting, and type checking.

```bash
pnpm dev                # start frontend + backend
pnpm build              # build all workspaces
pnpm typecheck          # TypeScript check across monorepo
pnpm lint               # Biome lint + format check
pnpm lint:fix           # auto-fix lint + format
pnpm test               # unit + integration tests
pnpm test:unit          # unit tests only
pnpm test:integration   # integration tests only
pnpm test:e2e           # Playwright e2e tests
pnpm test:coverage      # tests with coverage report
```

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

### Configure SnapOtter with Self-Signed Certificates

Source: https://docs.snapotter.com/guide/oidc

Mount a custom CA bundle and set NODE_EXTRA_CA_CERTS to use OIDC with a provider that has a self-signed or private CA certificate. Ensure OIDC is enabled and correctly configured with issuer URL, client ID, and secret.

```yaml
services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - ./my-ca.pem:/etc/ssl/certs/custom-ca.pem:ro
    environment:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/custom-ca.pem
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.internal.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"
```
Tokens:
Raw