mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
Siddharth Kumar Sah
8ae1d8cec3
The full API reference now lives at /api/docs (Scalar). This page becomes a getting-started guide covering auth, tool pattern, tool IDs, batch, pipelines, and errors — pointing to the interactive docs for per-endpoint details.
107 lines
3.5 KiB
Markdown
107 lines
3.5 KiB
Markdown
# REST API
|
|
|
|
The API server runs on port 1349 by default and serves all endpoints under `/api`.
|
|
|
|
::: tip Full API Reference
|
|
When your Stirling Image instance is running, visit [`/api/docs`](http://localhost:1349/api/docs) for the complete interactive API reference 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`](/Stirling-Image/llms.txt) for an index or [`/llms-full.txt`](/Stirling-Image/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:
|
|
|
|
1. **Session token** -- `POST /api/auth/login` with `{ "username", "password" }`. Returns a `token`. Pass as `Authorization: Bearer <token>`.
|
|
2. **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
|
|
|
|
```json
|
|
{
|
|
"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](http://localhost:1349/api/docs).
|
|
|
|
## 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:
|
|
|
|
```json
|
|
[
|
|
{ "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
|
|
|
|
```json
|
|
{ "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.
|