Getting Started

Snaapi is a Backend-as-a-Service that generates REST APIs from your data models. Define a resource, and Snaapi creates CRUD endpoints, access control, real-time streaming, webhooks, and an OpenAPI spec — all automatically.

In this guide you will:

1. Install and run Snaapi
2. Create your admin account
3. Define your first resource
4. Make your first API call

Install Snaapi

Snaapi Cloud

Coming soon. A fully managed Snaapi instance with nothing to install or maintain.

Docker (recommended)

Pull the official image from GitHub Container Registry:

docker pull ghcr.io/snaapi/snaapi:latest

The image supports linux/amd64 and linux/arm64 and is tagged with semver versions (1, 1.0, 1.0.0, latest).

Pre-compiled binary

Download a binary from the GitHub Releases page:

chmod +x snaapi-linux-amd64
./snaapi-linux-amd64

Quickstart with Docker Compose

The fastest way to get running. This brings up Snaapi and PostgreSQL together with a single command.

Save the following as docker-compose.yml:

services:
  snaapi:
    image: ghcr.io/snaapi/snaapi:latest
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: "postgres://snaapi:snaapi@db:5432/snaapi"
      BETTER_AUTH_SECRET: "replace-with-a-random-secret"
      BETTER_AUTH_URL: "http://localhost:8000"
      SNAAPI_SESSION_SECRET: "replace-with-a-random-secret"
      SNAAPI_AUTO_MIGRATE: "true"
      SNAAPI_INSTALL_TOKEN: "pick-a-secret-token"
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      POSTGRES_USER: snaapi
      POSTGRES_PASSWORD: snaapi
      POSTGRES_DB: snaapi
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Tip: Generate secrets with openssl rand -base64 32 and replace the placeholder values above.

Start the stack:

docker compose up -d

Open http://localhost:8000 in your browser, then skip ahead to Create your admin account.

Manual setup

If you prefer to manage PostgreSQL separately or run Snaapi as a binary, follow these steps instead.

Set up PostgreSQL

Snaapi stores all data in PostgreSQL (v15+ recommended). If you don't already have an instance, start one with Docker:

docker run -d \
  --name snaapi-postgres \
  -e POSTGRES_USER=snaapi \
  -e POSTGRES_PASSWORD=snaapi \
  -e POSTGRES_DB=snaapi \
  -p 5432:5432 \
  postgres:15

Configure environment

Create a .env file with the required settings:

# Connection string for your PostgreSQL database
DATABASE_URL="postgres://snaapi:snaapi@localhost:5432/snaapi"

# Secrets used for signing tokens and encrypting sessions
BETTER_AUTH_SECRET="replace-with-a-random-secret"
BETTER_AUTH_URL="http://localhost:8000"
SNAAPI_SESSION_SECRET="replace-with-a-random-secret"

# Run database migrations automatically on startup
SNAAPI_AUTO_MIGRATE=true

# Token required during initial setup (see next section)
SNAAPI_INSTALL_TOKEN="pick-a-secret-token"

Tip: Generate secrets with openssl rand -base64 32.

See Configuration for the full list of environment variables.

Run Snaapi

With Docker

docker run -d \
  --name snaapi \
  --env-file .env \
  -p 8000:8000 \
  ghcr.io/snaapi/snaapi:latest

Note: If PostgreSQL is running on the host (not in Docker), replace localhost in your DATABASE_URL with host.docker.internal (macOS/Windows) or use --network host (Linux) so the container can reach it.

With a binary

./snaapi-linux-amd64

Snaapi listens on port 8000 by default. Open http://localhost:8000 in your browser to continue.

Create your admin account

On first launch, Snaapi redirects you to the setup page at /install. The setup has two steps:

1. Enter your install token — this is the value you set in SNAAPI_INSTALL_TOKEN. If you didn't set one, Snaapi generates a random token and prints it to the startup logs.
2. Create your admin account — enter a name, email, and password. This becomes the first user with the admin role.

After setup completes, log in and you'll land in the Admin Console — a visual dashboard for managing resources, roles, permissions, and more.

Create your first resource

Resources are the core building block in Snaapi. Each resource becomes a database table and a set of REST API endpoints.

The easiest way to create a resource is through the Admin Console:

1. Click Add Resource on the dashboard
2. Give it a name (e.g. posts) and add fields:
   • title — type string, required
   • body — type string
3. Save the resource

Snaapi immediately creates the database table and generates API endpoints at /api/resources/posts.

Prefer the CLI? You can also create resources via the admin API:

curl -X POST http://localhost:8000/console/api/resources \
  -H "Content-Type: application/json" \
  -b "your-session-cookie" \
  -d '{
    "name": "posts",
    "fields": [
      { "name": "title", "type": "string", "required": true },
      { "name": "body", "type": "string" }
    ]
  }'

Make your first API call

With a resource created, you can start reading and writing data immediately:

# Create a record
curl -X POST http://localhost:8000/api/resources/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{ "title": "Hello World", "body": "My first Snaapi post" }'

# List all records
curl http://localhost:8000/api/resources/posts \
  -H "Authorization: Bearer <your-token>"

# Get a single record by ID
curl http://localhost:8000/api/resources/posts/<record-id> \
  -H "Authorization: Bearer <your-token>"

Every resource automatically supports filtering, sorting, pagination, and field selection — see Filtering & Pagination for the full query syntax.

Next steps

Now that you have Snaapi running with your first resource, explore what else you can do:

• Resources — system fields, soft delete, and resource settings
• Fields — all 10 field types, validation rules, and generation transforms
• Access Control — roles, permissions, and the three-layer security model
• API Endpoints — full REST API reference with response formats and error codes
• Admin Console — visual resource builder, AI chat, content generator, and analytics
• Import & Export — import from YAML, GraphQL SDL, or Excel/CSV