mirror of https://github.com/ashim-hq/ashim synced 2026-04-21 21:48:03 +00:00

Siddharth Kumar Sah fe80287cb4 docs: replace localhost links with generic path references in API docs

Clickable localhost:1349 links are misleading on the GitHub Pages site
since users may not have Stirling Image running locally. Use plain path
references instead so it is clear these live on their own instance.

2026-04-06 11:33:50 +08:00

3.5 KiB

Raw Blame History

REST API

The API server runs on port 1349 by default and serves all endpoints under /api.

::: tip Full API Reference Your Stirling Image instance includes a complete interactive API reference at /api/docs (e.g. http://your-host:1349/api/docs) with all 67 endpoints, request/response schemas, and examples. :::

::: info LLM-friendly docs Need to feed these docs to an AI assistant? Use /llms.txt for an index or /llms-full.txt for the complete documentation in a single file. On a running instance, these are also available at /llms.txt and /llms-full.txt. :::

This page covers the basics of using the API. For per-endpoint details (every parameter, schema, and response), see the interactive docs at /api/docs.

Authentication

Two methods:

Session token -- POST /api/auth/login with { "username", "password" }. Returns a token. Pass as Authorization: Bearer <token>.
API key -- Generate via Settings UI or POST /api/v1/api-keys. Prefixed with si_. Pass as Authorization: Bearer si_....

Public endpoints (no auth required): health check, login, API docs, downloads, job progress.

Using a tool

Every tool follows the same pattern:

POST /api/v1/tools/:toolId
Content-Type: multipart/form-data

Send a multipart request with:

file -- the image
settings -- JSON string with tool-specific options

{
  "jobId": "abc123",
  "downloadUrl": "/api/v1/download/abc123/output.png",
  "originalSize": 245000,
  "processedSize": 180000
}

Tool IDs

Category	Tools
Essentials	`resize`, `crop`, `rotate`, `convert`, `compress`
Optimization	`strip-metadata`, `bulk-rename`, `image-to-pdf`, `favicon`
Adjustments	`brightness-contrast`, `saturation`, `color-channels`, `color-effects`, `replace-color`
AI	`remove-background`, `upscale`, `erase-object`, `ocr`, `blur-faces`, `smart-crop`
Watermark	`watermark-text`, `watermark-image`, `text-overlay`, `compose`
Utilities	`info`, `compare`, `find-duplicates`, `color-palette`, `qr-generate`, `barcode-read`
Layout	`collage`, `split`, `border`
Format	`svg-to-raster`, `vectorize`, `gif-tools`

Each tool's specific settings are documented in the interactive API reference at /api/docs on your running instance.

Batch processing

POST /api/v1/tools/:toolId/batch

Send multiple files with the same settings. Returns a ZIP. Use the X-Job-Id header to track progress.

Pipelines

Chain tools into reusable workflows.

POST /api/v1/pipeline/execute   -- Run a pipeline (multipart: file + steps JSON)
POST /api/v1/pipeline/save      -- Save a named pipeline
GET  /api/v1/pipeline/list      -- List saved pipelines
DELETE /api/v1/pipeline/:id     -- Delete a pipeline

Example steps:

[
  { "toolId": "resize", "settings": { "width": 200, "height": 200, "fit": "cover" } },
  { "toolId": "compress", "settings": { "quality": 80 } },
  { "toolId": "convert", "settings": { "format": "webp" } }
]

Progress tracking (SSE)

For long-running jobs (AI tools, batch processing):

GET /api/v1/jobs/:jobId/progress

Returns a Server-Sent Events stream with { status, progress, completedFiles, failedFiles }.

Error responses

{ "statusCode": 400, "error": "Bad Request", "message": "Invalid image format" }

Status codes: 400 invalid input, 401 not authenticated, 403 not authorized, 413 file too large, 429 rate limited, 500 server error.

3.5 KiB Raw Blame History