Stash-Box

https://github.com/stashapp/stash-box
Admin
Stash-Box is an open-source video indexing and metadata API server for adult content, providing a...
Tokens:64,479
Snippets:365
Trust Score:8.4
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### GraphQL server bootstrap with directives and recover

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/01-server.md

Bootstraps the GraphQL server inside the Start function. It creates the executable schema from generated code, sets custom directives, and installs a recover function that converts internal errors to 'Internal system error. Error <%v>' and logs stack traces.

```go
gqlConfig := models.Config{
    Resolvers: NewResolver(fac),
    Directives: models.DirectiveRoot{
        IsUserOwner: IsUserOwnerDirective,
        HasRole:     HasRoleDirective,
    },
}
gqlSrv := gqlHandler.New(models.NewExecutableSchema(gqlConfig))
gqlSrv.SetRecoverFunc(recoverFunc)
```

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

### Start function signature

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/01-server.md

Defines the entry point for starting the HTTP server. It takes a service factory and embedded UI filesystem, then builds the router, middleware, and listeners.

```go
func Start(fac service.Factory, ui embed.FS)
```

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

### Install dependencies with pnpm

Source: https://github.com/stashapp/stash-box/blob/master/frontend/README.md

Run this command in the frontend directory to install all required dependencies using pnpm.

```shell
pnpm i
```

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

### Start local development server

Source: https://github.com/stashapp/stash-box/blob/master/frontend/README.md

Run the local development server with hot reload. The server starts on http://localhost:3001 by default.

```shell
pnpm start
```

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

### Example: validating required settings on startup (as cmd/stash-box/init.go does)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/02-config.md

Validates required autocert settings on startup, printing missing settings and exiting if any are absent, as done in cmd/stash-box/init.go.

```go
missing := config.GetMissingAutocertSettings()
if len(missing) > 0 {
    fmt.Printf("Autocert is enabled, but the following required settings are missing: %s\n", strings.Join(missing, ", "))
    os.Exit(1)
}
```

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

### Example: reading config in application code

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/02-config.md

Shows how to read configuration values in application code, including port, production mode, and S3 settings.

```go
import "github.com/stashapp/stash-box/internal/config"

port := config.GetPort()
if config.GetIsProduction() {
    // session cookies become Secure; /playground is disabled
}
s3 := config.GetS3Config()
endpoint := s3.Endpoint
```

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

### Example stash-box configuration file (YAML)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/configuration.md

Example configuration file for stash-box. Shows all available settings including server host/port, database connection, voting thresholds, email SMTP settings, image storage and resizing, PostgreSQL connection pool, OpenTelemetry tracing, and moderation audit retention.

```yaml
host: 0.0.0.0
port: 9998
database: postgres@localhost/stash-box?sslmode=disable
is_production: true

require_invite: true
require_activation: true
activation_expiry: 7200
email_cooldown: 300
default_user_roles: ["READ", "VOTE", "EDIT"]
vote_promotion_threshold: 10
vote_application_threshold: 3
voting_period: 345600
min_destructive_voting_period: 172800
vote_cron_interval: "5m"
edit_update_limit: 1

email_host: smtp.example.com
email_port: 587
email_user: noreply@example.com
email_password: secret
email_from: noreply@example.com
email_tls_mode: opportunistic
host_url: https://stashdb.example.com

image_location: /var/lib/stash-box/images
image_backend: file
image_resizing:
  enabled: true
  cache_path: /var/lib/stash-box/image-cache
  min_size: 600

postgres:
  max_open_conns: 25
  max_idle_conns: 10
  conn_max_lifetime: 30

otel:
  endpoint: otel.example.com:4317
  trace_ratio: 0.1

title: My StashDB
mod_audit_retention_days: 30
```

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

### GET /graphql

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Serves the GraphQL API over GET, supporting queries via query parameters.

```APIDOC
## GET /graphql

### Description
Serves the GraphQL API over GET, supporting queries via query parameters.

### Method
GET

### Endpoint
/graphql

### Parameters
#### Query Parameters
- **query** (string) - Required - The GraphQL query string.
- **variables** (object) - Optional - JSON-encoded variables for the query.

### Response
#### Success Response (200)
Returns GraphQL JSON with `data` and optional `errors` array.

#### Error Response (401)
Returned for authentication failures.

#### Error Response (500)
Returned for internal failures.
```

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

### GET /assets/*

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Serves static assets from the embedded frontend build.

```APIDOC
## GET /assets/*

### Description
Serves static assets from the embedded frontend build.

### Method
GET

### Endpoint
/assets/*

### Response
#### Success Response (200)
Returns the requested static asset with cache headers.
```

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

### GET /{prefix}/*

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Serves additional on-disk SPA builds for each configured frontend prefix.

```APIDOC
## GET /{prefix}/*

### Description
Serves additional on-disk SPA builds for each configured frontend prefix.

### Method
GET

### Endpoint
/{prefix}/*

### Parameters
#### Path Parameters
- **prefix** (string) - Required - The frontend prefix (must be non-empty, not `/`, and unique).

### Response
#### Success Response (200)
Returns the SPA index.html or static asset for the given prefix.
```

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

### GET /heap (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns heap profile data.

```APIDOC
## GET /heap (profiler)

### Description
Returns heap profile data.

### Method
GET

### Endpoint
/heap (profiler)

### Response
#### Success Response (200)
Returns heap profile data.
```

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

### GET /allocs (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns memory allocation profile data.

```APIDOC
## GET /allocs (profiler)

### Description
Returns memory allocation profile data.

### Method
GET

### Endpoint
/allocs (profiler)

### Response
#### Success Response (200)
Returns allocation profile data.
```

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

### GET /cmdline (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns the command line arguments of the running process.

```APIDOC
## GET /cmdline (profiler)

### Description
Returns the command line arguments of the running process.

### Method
GET

### Endpoint
/cmdline (profiler)

### Response
#### Success Response (200)
Returns the command line arguments.
```

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

### Manual factory use without HTTP stack

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/09-database-queries.md

Shows how to create a service factory directly with a database pool and email manager, bypassing the HTTP stack. Useful for background tasks or tests. The example queries a scene by ID and logs any error.

```go
pool := database.Initialize(config.GetDatabasePath())
fac := service.NewFactory(pool, email.NewManager())
ctx := context.Background()

scene, err := fac.Scene().FindByID(ctx, sceneID)
if err != nil {
	logger.Error(err)
}
```

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

### GET /goroutine (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns goroutine profile data.

```APIDOC
## GET /goroutine (profiler)

### Description
Returns goroutine profile data.

### Method
GET

### Endpoint
/goroutine (profiler)

### Response
#### Success Response (200)
Returns goroutine profile data.
```

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

### GET /threadcreate (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns thread creation profile data.

```APIDOC
## GET /threadcreate (profiler)

### Description
Returns thread creation profile data.

### Method
GET

### Endpoint
/threadcreate (profiler)

### Response
#### Success Response (200)
Returns thread creation profile data.
```

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

### GET /*

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Serves the single-page application (SPA) index.html with templated title and security headers.

```APIDOC
## GET /*

### Description
Serves the single-page application (SPA) index.html with templated title and security headers.

### Method
GET

### Endpoint
/*

### Response
#### Success Response (200)
Returns the SPA index.html with security headers.
```

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

### GET /trace (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns an execution trace of the running process.

```APIDOC
## GET /trace (profiler)

### Description
Returns an execution trace of the running process.

### Method
GET

### Endpoint
/trace (profiler)

### Response
#### Success Response (200)
Returns the execution trace data.
```

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

### GET /playground

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Serves the GraphQL playground UI for development, pointing to the `/graphql` endpoint.

```APIDOC
## GET /playground

### Description
Serves the GraphQL playground UI for development, pointing to the `/graphql` endpoint.

### Method
GET

### Endpoint
/playground

### Response
#### Success Response (200)
Returns the GraphQL playground HTML page.
```

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

### Transaction-wrapped write with WithTxn

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/09-database-queries.md

Demonstrates a transaction-wrapped write using the service factory's WithTxn method. The callback receives a *queries.Queries object; returning an error rolls back the transaction. The example finds a user and updates their API key.

```go
err := fac.User().WithTxn(func(tx *queries.Queries) error {
	user, err := tx.FindUser(ctx, userID)
	if err != nil {
		return err  // rolls back
	}
	return tx.UpdateUserAPIKey(ctx, queries.UpdateUserAPIKeyParams{ID: userID, ApiKey: key})
})
```

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

### GET /favicon.ico

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Serves the favicon from the embedded frontend build.

```APIDOC
## GET /favicon.ico

### Description
Serves the favicon from the embedded frontend build.

### Method
GET

### Endpoint
/favicon.ico

### Response
#### Success Response (200)
Returns the favicon file with cache headers.
```

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

### GET /mutex (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns mutex profile data.

```APIDOC
## GET /mutex (profiler)

### Description
Returns mutex profile data.

### Method
GET

### Endpoint
/mutex (profiler)

### Response
#### Success Response (200)
Returns mutex profile data.
```

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

### GET /manifest.json

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Serves the web app manifest from the embedded frontend build.

```APIDOC
## GET /manifest.json

### Description
Serves the web app manifest from the embedded frontend build.

### Method
GET

### Endpoint
/manifest.json

### Response
#### Success Response (200)
Returns the manifest file with cache headers.
```

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

### GET /profile (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns a CPU profile of the running process.

```APIDOC
## GET /profile (profiler)

### Description
Returns a CPU profile of the running process.

### Method
GET

### Endpoint
/profile (profiler)

### Response
#### Success Response (200)
Returns the CPU profile data.
```

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

### Multipart upload example

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Upload an image using a multipart/form-data request to the /graphql endpoint. The operation field includes a mutation with an Upload scalar, and a file part contains the image bytes (max 10 MiB).

```text
POST /graphql with multipart/form-data, operation field like mutation($file: Upload!) { imageCreate(input: { file: $file }) { id url } } and a file part with the image bytes (≤ 10 MiB).
```

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

### GET / (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Serves the profiler index page when the profiler port is enabled.

```APIDOC
## GET / (profiler)

### Description
Serves the profiler index page when the profiler port is enabled.

### Method
GET

### Endpoint
/ (profiler)

### Response
#### Success Response (200)
Returns the profiler index page.
```

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

### GET /symbol (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns symbol information for the running process.

```APIDOC
## GET /symbol (profiler)

### Description
Returns symbol information for the running process.

### Method
GET

### Endpoint
/symbol (profiler)

### Response
#### Success Response (200)
Returns symbol information.
```

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

### GET /block (profiler)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Returns blocking profile data.

```APIDOC
## GET /block (profiler)

### Description
Returns blocking profile data.

### Method
GET

### Endpoint
/block (profiler)

### Response
#### Success Response (200)
Returns blocking profile data.
```

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

### GET /images/site/{uuid}

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Retrieves a site's favicon by its UUID.

```APIDOC
## GET /images/site/{uuid}

### Description
Retrieves a site's favicon by its UUID.

### Method
GET

### Endpoint
/images/site/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the site.

### Response
#### Success Response (200)
Returns the favicon bytes with appropriate content type and cache headers.

#### Error Response (404)
Returned when the site or icon is not found.
```

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

### Generate self-signed certificate with OpenSSL

Source: https://github.com/stashapp/stash-box/blob/master/README.md

Use this OpenSSL command to create a self-signed certificate and key pair. Modify the command for your setup. The resulting files must be named 'stash-box.crt' and 'stash-box.key' and placed in the same directory as stash-box to enable HTTPS.

```bash
openssl req -x509 -newkey rsa:4096 -sha256 -days 7300 -nodes -keyout stash-box.key -out stash-box.crt -extensions san -config <(echo "[req]"; echo distinguished_name=req; echo "[san]"; echo subjectAltName=DNS:stash-box.server,IP:127.0.0.1) -subj /CN=stash-box.server
```

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

### GET /images/{uuid}

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Retrieves an image by its UUID, optionally resized to a specified size.

```APIDOC
## GET /images/{uuid}

### Description
Retrieves an image by its UUID, optionally resized to a specified size.

### Method
GET

### Endpoint
/images/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the image.

#### Query Parameters
- **size** (string) - Optional - The desired size: `300`, `600`, `1280`, or `full`.

### Response
#### Success Response (200)
Returns the image bytes with appropriate content type and cache headers.

#### Error Response (400)
Returned for invalid UUID or disallowed size.

#### Error Response (404)
Returned when the image is not found.

#### Error Response (500)
Returned for read or resize failures.
```

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

### Journal a background job with OpenTelemetry tracing

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/10-support.md

Use this pattern to add OpenTelemetry tracing to background jobs, such as the cron job that cleans expired drafts. It starts a span with the tracer, defers its end, executes the job, and records any error on the span while logging it.

```go
ctx, span := otel.Tracer("github.com/stashapp/stash-box/internal/cron").Start(context.Background(), "cron.cleanDrafts")
defer span.End()
err := c.fac.Draft().DeleteExpired(ctx)
tracing.RecordError(span, err)
if err != nil { logger.Errorf("Error cleaning drafts: %s", err) }
```

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

### RequestChangeEmail

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/04-service-user.md

Starts the email change flow by sending a confirmation token to the current email address.

```APIDOC
## RequestChangeEmail

### Description
Initiates the email change process. Sends a CONFIRM_OLD_EMAIL token to the current email address.

### Method
RequestChangeEmail

### Signature
func (s *User) RequestChangeEmail(ctx context.Context) (models.UserChangeEmailStatus, error)

### Parameters
- **ctx** (context.Context) - Required - The request context.

### Return Values
- **models.UserChangeEmailStatus** - The status of the email change request (e.g., CONFIRM_OLD_EMAIL).
- **error** - Error if the request fails.
```

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

### JSON error response for mutation

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Example error response when a mutation fails, such as when an edit contains no changes. The response includes an errors array with a message and a null data field.

```json
{"errors":[{"message":"edit contains no changes"}],"data":{"sceneEdit":null}}
```

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

### Initialize environment configuration

Source: https://github.com/stashapp/stash-box/blob/master/frontend/README.md

Copy the shadow environment file to create a local development configuration file.

```shell
cp .env.development.local.shadow .env.development.local
```

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

### Site service constructor: `NewSite`

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/06-service-entities.md

Constructs a `*Site` service instance, taking the `queries.Queries` and a `queries.WithTxnFunc` transaction wrapper. Required before using site methods.

```go
func NewSite(queries *queries.Queries, withTxn queries.WithTxnFunc) *Site
```

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

### Create system users (root, StashBot, deleted user)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/04-service-user.md

Idempotent method that creates system users when missing: root (ADMIN, random 16-char password, prints 'root user has been created.\nUser: root\nPassword: ...\nAPI Key: ...' to stdout only), StashBot (BOT role, random 32-char password), and [deleted user] (no roles, sentinel for fingerprint reassignment). Constants (user.go:11-21): minPasswordLength=8, maxPasswordLength=64, minUniqueChars=5, rootUserName="root", modUserName="StashBot", deletedUserName="[deleted user]", unsetEmail="root@example.com", deletedUserEmail="deleted@example.com".

```go
func (s *User) CreateSystemUsers(ctx context.Context)   // service.go:713
```

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

### User lifecycle method signatures

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/04-service-user.md

Method signatures for the User service lifecycle: NewUser, Create, Update, Delete, and ActivateNewUser. NewUser handles registration with email and invite key validation, returning the activation key when require_activation is false or emailing it when true. Create is for direct admin creation, hashing the password and generating an API key. Update validates input and invalidates the auth cache on success. Delete blocks system users and reassigns fingerprints to a sentinel. ActivateNewUser validates the activation token and invite key, creates the user, and cleans up tokens.

```go
func (s *User) NewUser(ctx context.Context, emailAddr string, inviteKey *uuid.UUID) (*uuid.UUID, error)  // service.go:212
func (s *User) Create(ctx context.Context, input models.UserCreateInput) (*models.User, error)            // service.go:249
func (s *User) Update(ctx context.Context, input models.UserUpdateInput) (*models.User, error)            // service.go:262
func (s *User) Delete(ctx context.Context, input models.UserDestroyInput) error                           // service.go:301
func (s *User) ActivateNewUser(ctx context.Context, input models.ActivateNewUserInput) (*models.User, error) // service.go:426
```

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

### Build release bundle

Source: https://github.com/stashapp/stash-box/blob/master/frontend/README.md

Build the production-ready static bundle for the frontend.

```shell
pnpm build
```

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

### image resizer InitResizer and Resize functions

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/10-support.md

Initializes the libvips resizer and provides the Resize function used by routes_image.go when shouldResize(...) is true. The result is written through io.Copy or w.Write.

```go
func InitResizer() error          // resize_unix.go / resize_windows.go (platform-specific)
func Resize(data any, size int, image *models.Image, size int) ([]byte, error)  // reader-based resize
```

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

### Register with invite and activate user

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/04-service-user.md

Registers a new user using an invite key and then activates the account. NewUser returns an error for "email already in use", "invite key expired", or "key already used". The returned key is a *uuid.UUID activation key when require_activation is false, which is passed to ActivateNewUser along with the new password.

```go
key, err := fac.User().NewUser(ctx, "bob@example.com", inviteKey /* *uuid.UUID */)
if err != nil {
    // "email already in use" | "invite key expired" | "key already used" ...
    return nil, err
}
// key is *uuid.UUID — the activation key when require_activation is false
user, err := fac.User().ActivateNewUser(ctx, models.ActivateNewUserInput{
    Name:          "bob",
    ActivationKey: *key,
    Password:      "B3tter!Pass9",
})
```

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

### Paths (internal/config/paths.go)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/02-config.md

Lists the default path and configuration file functions in internal/config/paths.go, with their default return values.

```go
func GetConfigDirectory() string          // "."
func GetDefaultDatabaseFilePath() string  // "postgres@localhost/stash-box?sslmode=disable"
func GetConfigName() string               // "stash-box-config"
func GetDefaultConfigFilePath() string    // "./stash-box-config.yml"
func GetSSLKey() string                   // "./stash-box.key"
func GetSSLCert() string                  // "./stash-box.crt"
```

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

### New function and WithTxnFunc type (db.go)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/09-database-queries.md

Shows the entry point New that creates a Queries instance from a database connection, and the WithTxnFunc type representing a function that wraps a transaction.

```go
func New(conn database/sql.Db) *Queries     // internal/queries/db.go
type WithTxnFunc func(fn func(*Queries) error) error
```

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

### Autocert functions for Let's Encrypt

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/10-support.md

Autocert functions for Let's Encrypt. Init returns a tls.Config or nil when autocert is not enabled, HTTPHandler provides the ACME HTTP-01 challenge handler on port 80, and CheckAndRenew is the cron entry. Init uses autocert.DirCache, HostWhitelist, AcceptTOS, and email, and obtains the certificate asynchronously on startup.

```go
func Init() *tls.Config                        // autocert.go:21 — nil when autocert not enabled
func HTTPHandler(fallback http.Handler) http.Handler  // :48 — ACME HTTP-01 challenge handler on :80
func CheckAndRenew()                           // :57 — cron entry
```

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

### Configuration structs for S3, Postgres, OTel, image resize, autocert, and frontend

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/02-config.md

Defines the configuration structs for S3, Postgres, OpenTelemetry, image resizing, autocert, and frontend settings. Each field uses mapstructure tags to map YAML keys to Go fields. The FrontendConfig comments indicate the path is the directory holding the build and the prefix is the URL mount point.

```go
type S3Config struct {
	Endpoint      string            `mapstructure:"endpoint"`
	Bucket        string            `mapstructure:"bucket"`
	AccessKey     string            `mapstructure:"access_key"`
	Secret        string            `mapstructure:"secret"`
	MaxDimension  int               `mapstructure:"max_dimension"`
	UploadHeaders map[string]string `mapstructure:"upload_headers"`
}

type PostgresConfig struct {
	MaxOpenConns    int `mapstructure:"max_open_conns"`
	MaxIdleConns    int `mapstructure:"max_idle_conns"`
	ConnMaxLifetime int `mapstructure:"conn_max_lifetime"`
}

type OTelConfig struct {
	Endpoint   string  `mapstructure:"endpoint"`
	TraceRatio float64 `mapstructure:"trace_ratio"`
}

type ImageResizeConfig struct {
	Enabled   bool   `mapstructure:"enabled"`
	CachePath string `mapstructure:"cache_path"`
	MinSize   int    `mapstructure:"min_size"`
}

type AutocertConfig struct {
	Enabled  bool   `mapstructure:"enabled"`
	Domain   string `mapstructure:"domain"`
	Email    string `mapstructure:"email"`
	CacheDir string `mapstructure:"cache_dir"`
}

type FrontendConfig struct {
	Path   string `mapstructure:"path"`   // directory holding the build (index.html + assets/)
	Prefix string `mapstructure:"prefix"` // URL mount point, e.g. "/v2"
}
```

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

### Usage pattern: create factory and use tag service

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/03-service-factory.md

Shows the code-level usage pattern from the package comment (factory.go:1-18). It creates a pgxpool, constructs a service factory, retrieves the tag service, and calls FindByID.

```go
pool, err := pgxpool.New(context.Background(), databaseURL)
factory := service.NewFactory(pool)
tagService := factory.Tag()
tag, err := tagService.FindByID(ctx, tagID)
```

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

### User struct and constructor

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/04-service-user.md

Defines the User service struct and its constructor. NewUser takes the queries object, a transaction function, and an email manager. WithTxn wraps a function with a transaction.

```go
type User struct {
	queries  *queries.Queries
	withTxn  queries.WithTxnFunc
	emailMgr *email.Manager
}

func NewUser(queries *queries.Queries, withTxn queries.WithTxnFunc, emailMgr *email.Manager) *User   // service.go:27
func (s *User) WithTxn(fn func(*queries.Queries) error) error                                        // service.go:43
```

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

### Configure autocert for Let's Encrypt

Source: https://github.com/stashapp/stash-box/blob/master/README.md

Enable automatic certificate generation from Let's Encrypt by setting the 'autocert' config option. Requires access to port 80 for the challenge; after generation, port 80 redirects to SSL. Certificates renew automatically when less than 30 days remain.

```yaml
autocert:
    enabled: true
    cache_dir: /autocert
    domain: example.org
    email: email@example.org
```

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

### Tag service constructor: `NewTag`

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/06-service-entities.md

Constructs a `*Tag` service instance, taking the `queries.Queries` and a `queries.WithTxnFunc` transaction wrapper. Required before using tag methods.

```go
func NewTag(queries *queries.Queries, withTxn queries.WithTxnFunc) *Tag
```

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

### Scene service constructor

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/06-service-entities.md

Constructor for the Scene service. It takes the query layer and a transaction function, returning a new Scene service instance.

```go
func NewScene(queries *queries.Queries, withTxn queries.WithTxnFunc) *Scene
```

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

### Create user with UserCreate

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/04-service-user.md

Creates a user with the specified name, password, roles, and email. The password must satisfy the policy: length 8-64, at least 5 unique characters, not in the top-10,000 banned passwords, and not equal to username or email. On failure, returns an error such as ErrPasswordTooShort, ErrInvalidEmail, or "email already in use".

```go
u, err := fac.User().Create(ctx, models.UserCreateInput{
    Name:     "alice",
    Password: "correct horse battery staple",
    Roles:    []models.RoleEnum{models.RoleEnumRead, models.RoleEnumVote, models.RoleEnumEdit},
    Email:    "alice@example.com",
})
if err != nil {
    // e.g. ErrPasswordTooShort, ErrInvalidEmail, "email already in use"
    return nil, err
}
```

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

### Administrative lifecycle service methods (Go)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/05-service-edit.md

Go function signatures for administrative lifecycle operations on edits, including cancel, apply, close, amend, and promotion of user vote rights.

```go
func (s *Edit) Cancel(ctx context.Context, input models.CancelEditInput) (*models.Edit, error)               // service.go:1072
func (s *Edit) Apply(ctx context.Context, input models.ApproveEditInput) (*models.Edit, error)               // service.go:1097
func (s *Edit) ApplyEdit(ctx context.Context, editID uuid.UUID, immediate bool) (*models.Edit, error)        // service.go:1142
func (s *Edit) CloseEdit(ctx context.Context, editID uuid.UUID, status models.VoteStatusEnum) (*models.Edit, error) // service.go:1228
func (s *Edit) AmendEdit(ctx context.Context, input models.AmendEditInput) (*models.Edit, error)             // service.go:182
func (s *Edit) CloseCompleted(ctx context.Context) ([]*models.Edit, error)                                   // service.go:1409
func (s *Edit) PromoteUserVoteRights(ctx context.Context, userID uuid.UUID, threshold int) error             // service.go:1454
```

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

### InitializeDefaults and Initialize function signatures

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/02-config.md

Declarations for the two initialization functions. InitializeDefaults generates keys and writes config; Initialize unmarshals YAML into the config struct.

```go
func InitializeDefaults() error   // config.go:400
func Initialize() error           // config.go:428
```

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

### query service-level helpers

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/10-support.md

Service-level query helpers for building SQL criteria. ApplyMultiIDCriterion builds EXISTS/NOT EXISTS semi-joins or an INNER JOIN with HAVING COUNT(*) = n for INCLUDES_ALL, collapsing single values to INCLUDES; unsupported modifiers return an error. ApplyIDCriterion also supports IS NULL/IS NOT NULL. Pagination computes limit and offset from page and perPage.

```go
func ApplyMultiIDCriterion(query *sq.SelectBuilder, tableName, joinTable, fkColumn, joinField string, criterion *models.MultiIDCriterionInput) error
func ApplyIDCriterion(query sq.SelectBuilder, field string, criterion *models.IDCriterionInput) sq.SelectBuilder
func ApplyIntCriterion(query sq.SelectBuilder, field string, criterion *models.IntCriterionInput) sq.SelectBuilder
func ApplyStringCriterion(query sq.SelectBuilder, field string, criterion *models.StringCriterionInput) sq.SelectBuilder
func ApplyDateCriterion(query sq.SelectBuilder, field string, criterion *models.DateCriterionInput) sq.SelectBuilder
func Pagination(page, perPage int) (limit int, offset int)    // helpers.go
```

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

### User read methods

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/04-service-user.md

Read methods for the User service. FindByID and FindByName return nil instead of pgx.ErrNoRows via errutil.IgnoreNotFound. FindWithRoles returns (nil, nil, nil) when the user does not exist. CountVotesByType builds UserVoteCount from ACCEPT/REJECT/ABSTAIN/IMMEDIATE_ACCEPT/IMMEDIATE_REJECT rows; CountEditsByStatus separately tallies bot vs non-bot rows.

```go
func (s *User) FindByID(ctx context.Context, id uuid.UUID) (*models.User, error)                          // service.go:49
func (s *User) FindWithRoles(ctx context.Context, id uuid.UUID) (*models.User, []models.RoleEnum, error)  // service.go:60
func (s *User) LoadIds(ctx context.Context, ids []uuid.UUID) ([]*models.User, []error)                    // service.go:78
func (s *User) FindByName(ctx context.Context, name string) (*models.User, error)                         // service.go:86
func (s *User) Count(ctx context.Context) (int, error)                                                    // service.go:94
func (s *User) CountVotesByType(ctx context.Context, userID uuid.UUID) (*models.UserVoteCount, error)     // service.go:99
func (s *User) CountEditsByStatus(ctx context.Context, userID uuid.UUID) (*models.UserEditCount, error)   // service.go:126
func (s *User) GetNotificationSubscriptions(ctx context.Context, userID uuid.UUID) ([]models.NotificationEnum, error) // service.go:176
func (s *User) GetRoles(ctx context.Context, userID uuid.UUID) ([]models.RoleEnum, error)                 // service.go:190
func (s *User) LoadRoles(ctx context.Context, userIDs []uuid.UUID) ([][]string, []error)                  // service.go:200
```

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

### Database package constants and function declarations

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/09-database-queries.md

Defines the PostgreSQL driver name and current schema version (75), embeds migration files, and declares the main functions of the database package: Initialize, runMigrations, and extractSQLCQueryName.

```go
const (
	postgresDriver = "postgres"
	schemaVersion  = 75
)

//go:embed migrations/postgres/*.sql
var migrationsFS embed.FS

func Initialize(databasePath string) *pgxpool.Pool            // database.go:46
func runMigrations(databasePath string) error                 // database.go:95
func extractSQLCQueryName(query string) string                // database.go:27
```

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

### loadutil generic load helpers

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/10-support.md

Generic helper functions for loading and grouping data by keys. One returns a slice of converted values in the order of the input keys, with nil for missing keys and last-wins for duplicates. Many returns a slice of slices for grouped results. These primitives are used to implement service Load* methods.

```go
func One[K comparable, V any, R any](keys []K, fetch func([]K) ([]V, error), key func(V) K, convert func(V) R) ([]R, []error)
func Many[K comparable, V any, R any](keys []K, fetch func([]K) ([]V, error), key func(V) K, convert func(V) R) ([][]R, []error)
func repeatError(err error, size int) []error
func matchByKey[K comparable, V any, R any](keys []K, values []V, key func(V) K, convert func(V) R) []R
func groupByKey[K comparable, V any, R any](keys []K, values []V, key func(V) K, convert func(V) R) [][]R
```

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

### POST /login

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Authenticates a user with username and password, establishing a session cookie.

```APIDOC
## POST /login

### Description
Authenticates a user with a username and password, establishing a session cookie.

### Method
POST

### Endpoint
/login

### Parameters
#### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.

### Request Example
```
username=user&password=pass
```

### Response
#### Success Response (200)
Sets the `stashbox` cookie with the user ID and a 30-day max age.

#### Error Response (401)
Returned when the password is incorrect.

#### Error Response (500)
Returned for internal errors (session store, database).
```

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

### Run code formatter

Source: https://github.com/stashapp/stash-box/blob/master/frontend/README.md

Run the code formatter to automatically format the codebase.

```shell
pnpm format
```

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

### fingerprint service API

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/06-service-entities.md

Defines the Fingerprint service constructor and the ClusterScenes method, which is the core engine behind the 'fingerprintClusters' query. It performs BFS-based clustering over phash fingerprints within a Hamming distance.

```go
func New(q *queries.Queries) *Fingerprint
func (s *Fingerprint) ClusterScenes(ctx context.Context, seedScene uuid.UUID, distance int) (*models.FingerprintClustersResult, error)  // cluster.go:37
```

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

### Factory struct and NewFactory constructor

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/03-service-factory.md

Defines the Factory struct and its constructor. The factory is the central access point for every entity service, constructing a fresh service instance bound to a new queries.Queries handle over the shared connection pool. NewFactory takes the PostgreSQL connection pool (from database.Initialize) and an email.Manager (from email.NewManager), which may be a stub for tests.

```go
type Factory struct {
	db       *pgxpool.Pool
	withTxn  queries.WithTxnFunc
	emailMgr *email.Manager
}

func NewFactory(pool *pgxpool.Pool, emailMgr *email.Manager) *Factory   // factory.go:48
```

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

### dataloader context key and loader functions

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/09-database-queries.md

Defines the context key type and the loader-related functions in the dataloader package. Middleware attaches a fresh Loaders instance to the request context, For retrieves it, and GetLoaders builds it while resolving the current user for per-user loaders.

```go
type contextKey int
const (
	loadersKey contextKey = iota
)

func Middleware(fac service.Factory) func(next http.Handler) http.Handler   // loaders.go:57
func For(ctx context.Context) *Loaders                                       // :68
func GetLoadersKey() contextKey                                             // :72
func GetLoaders(ctx context.Context, fac service.Factory) *Loaders           // :75
```

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

### Run linter

Source: https://github.com/stashapp/stash-box/blob/master/frontend/README.md

Run the linter to check for code style and potential errors.

```shell
pnpm lint
```

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

### FromUser function signature

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/07-auth.md

Constructs an AuthUser from a models.User, returning nil for nil input.

```go
func FromUser(u *models.User) *AuthUser   // cache.go:71 — nil input → nil
```

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

### Version functions printVersion and GetVersion

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/01-server.md

Declares the version functions. GetVersion returns version, githash, and buildstamp from linker-injected symbols. printVersion prints the version string, appending the githash unless the build type is OFFICIAL. Used by the version GraphQL query.

```go
func printVersion()
func GetVersion() (string, string, string)
```

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

### Password and email flow methods

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/04-service-user.md

Password and email flow methods. ResetPassword sleeps 500-1500 ms (randomized) before and after the lookup to avoid leaking email presence, then sends a RESET_PASSWORD token email. ChangePassword branches on ResetKey (password reset path) or current password path (requires authentication and ExistingPassword; returns ErrCurrentPasswordIncorrect on mismatch). Email-change flow is three-step: RequestChangeEmail -> CONFIRM_OLD_EMAIL, ValidateChangeEmail -> CONFIRM_NEW_EMAIL, ConfirmChangeEmail -> SUCCESS; any error returns UserChangeEmailStatusError.

```go
func (s *User) ResetPassword(ctx context.Context, input models.ResetPasswordInput) error                 // service.go:379
func (s *User) ChangePassword(ctx context.Context, input models.UserChangePasswordInput) error           // service.go:403
func (s *User) RequestChangeEmail(ctx context.Context) (models.UserChangeEmailStatus, error)             // service.go:634
func (s *User) ValidateChangeEmail(ctx context.Context, tokenID uuid.UUID, emailAddr string) (models.UserChangeEmailStatus, error) // service.go:654
func (s *User) ConfirmChangeEmail(ctx context.Context, tokenID uuid.UUID) (models.UserChangeEmailStatus, error) // service.go:687
```

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

### GET|POST /logout

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Clears the user session and redirects to the root path.

```APIDOC
## GET|POST /logout

### Description
Clears the user session and redirects to the root path.

### Method
GET, POST

### Endpoint
/logout

### Response
#### Success Response (302)
Redirects to `/` after clearing the session cookie.
```

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

### storage Backend interface and Image() factory

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/10-support.md

Defines the storage Backend interface and the Image() factory that selects between FileBackend and S3Backend based on config. shardedKey builds a two-level sharded path from the first four characters of the ID.

```go
type Backend interface {
	WriteFile(file []byte, image *models.Image) error
	DestroyFile(image *models.Image) error
	ReadFile(image models.Image) (io.ReadCloser, int64, error)
}
```

```go
func Image() Backend            // image_backend.go — selects FileBackend ("file") or S3Backend ("s3") from config
func shardedKey(id string) string  // id[0:2] + "/" + id[2:4] + "/" + id
```

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

### createWithTxnFunc signature

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/03-service-factory.md

Signature of the transaction wrapper factory. It returns a function that begins a transaction, runs the provided function with a transaction-bound queries object, rolls back on error or panic (re-panicking after rollback), and commits on success.

```go
func createWithTxnFunc(pool *pgxpool.Pool) queries.WithTxnFunc
```

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

### usertoken service API

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/06-service-entities.md

Defines the UserToken service constructor and methods for creating, destroying, and querying user tokens, including invite key operations. The DestroyExpired method removes expired tokens.

```go
func NewUserToken(queries *queries.Queries, withTxn queries.WithTxnFunc) *UserToken
func (s *UserToken) Create(ctx, newToken models.UserToken) (*models.UserToken, error)
func (s *UserToken) Destroy(ctx, id uuid.UUID) error
func (s *UserToken) DestroyExpired(ctx) error
func (s *UserToken) Find(ctx, id uuid.UUID) (*models.UserToken, error)
func (s *UserToken) FindByInviteKey(ctx, key uuid.UUID) ([]*models.UserToken, error)
func (s *UserToken) FindActiveInviteKeysForUser(ctx, userID uuid.UUID) ([]models.InviteKey, error)
```

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

### Query Existing Scenes for De-duplication

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/06-service-entities.md

Queries for existing scenes using the service factory's Scene().FindExistingScenes method with title, studio ID, and fingerprints. Also demonstrates finding pending scene creation edits via fac.Edit().FindPendingSceneCreation.

```go
scenes, err := fac.Scene().FindExistingScenes(ctx, models.QueryExistingSceneInput{
    Title:        "Found Footage",
    StudioID:     studioID,
    Fingerprints: []models.FingerprintInput{ {Hash: ph, Algorithm: models.FingerprintAlgorithmPhash, Duration: 100} },
})
edits, err := fac.Edit().FindPendingSceneCreation(ctx, ...)
```

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

### Cron struct and Init function

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/10-support.md

Defines the Cron struct and its Init function, which takes a service.Factory. The cron scheduler runs periodic jobs guarded by a weighted semaphore for processEdits.

```go
type Cron struct {
	fac service.Factory
}
func Init(fac service.Factory)   // cron.go:133
```

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

### Three-way assignment functions (assign.go)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/08-models.md

Provides three-way assignment helpers: when in is set use it; else when old was set clear the field; else leave as-is.

```go
func String(out *string, in *string)
func StringPtr(out **string, in *string, old *string)
func IntPtr(out **int, in *int, old *int)
func NullUUID(out *uuid.NullUUID, in *uuid.UUID, old *uuid.UUID)
func EnumPtr[T StringEnum](out **T, in *string, old *string)
```

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

### Context keys definition

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/07-auth.md

Defines the key type and two constants (ContextUser, ContextRoles) used in the request context. Both are set by api.authenticateHandler and read by directives/resolvers.

```go
type key int
const (
	ContextUser key = iota
	ContextRoles
)
```

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

### Voting and comment service methods (Go)

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/05-service-edit.md

Go function signatures for voting and commenting on edits. CreateVote is only allowed on pending edits and requires the VOTE role; CreateComment requires the EDIT role; UpdateComment and HideComment are moderator-only and record audit records.

```go
func (s *Edit) CreateVote(ctx context.Context, input models.EditVoteInput) (*models.Edit, error)          // service.go:985
func (s *Edit) CreateComment(ctx context.Context, input models.EditCommentInput) (*models.Edit, *models.EditComment, error) // service.go:1044
func (s *Edit) UpdateComment(ctx context.Context, input models.UpdateEditCommentInput) (*models.EditComment, error) // service.go:297
func (s *Edit) HideComment(ctx context.Context, input models.HideEditCommentInput) (*models.EditComment, error)     // service.go:342
```

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

### Image routes handler signatures and allowedSizes

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/01-server.md

Function signatures and the allowedSizes variable for the image routes handler in internal/api/routes_image.go. The image handler serves uploaded images with size query parameter validation, caching, and resizing; siteImage serves site icons with caching.

```go
func (rs imageRoutes) Routes() chi.Router                        // routes_image.go:36
func (rs imageRoutes) image(w http.ResponseWriter, r *http.Request)     // routes_image.go:45
func (rs imageRoutes) siteImage(w http.ResponseWriter, r *http.Request) // routes_image.go:154
func getImageSize(r *http.Request) (int, error)                  // routes_image.go:201
func shouldResize(image *models.Image, requestedSize int) bool   // routes_image.go:223
var allowedSizes = []int{300, 600, 1280}                         // routes_image.go:199
```

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

### image cache manager GetCacheManager and methods

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/api-reference/10-support.md

Provides the resized-image disk cache manager. GetCacheManager returns a singleton (sync.Once) that is nil when the resize cache is disabled. Cache files are named <id>_<size> under image_resizing.cache_path.

```go
func GetCacheManager() *cacheManager                 // singleton (sync.Once); nil when resize cache disabled
func (c *cacheManager) Read(id uuid.UUID, size int) (io.ReadCloser, error)
func (c *cacheManager) Write(id uuid.UUID, size int, data []byte) error
func (c *cacheManager) Delete(id uuid.UUID) error    // glob <id>_* cleanup
```

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

### POST /graphql

Source: https://github.com/stashapp/stash-box/blob/master/_autodocs/endpoints.md

Serves the GraphQL API over POST, accepting GraphQL queries and mutations in the request body.

```APIDOC
## POST /graphql

### Description
Serves the GraphQL API over POST, accepting GraphQL queries and mutations in the request body.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL query or mutation string.
- **variables** (object) - Optional - JSON-encoded variables for the query.

### Request Example
```json
{
  "query": "query { me { id } }",
  "variables": {}
}
```

### Response
#### Success Response (200)
Returns GraphQL JSON with `data` and optional `errors` array.

#### Error Response (401)
Returned for authentication failures.

#### Error Response (500)
Returned for internal failures.
```

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

### Run validation before PR

Source: https://github.com/stashapp/stash-box/blob/master/frontend/README.md

Run all validation checks, typically required before submitting a pull request.

```shell
pnpm validate
```
Tokens:
Raw