How to use PrintStash's API for automation

PrintStash exposes the same REST API used by its web interface. On a default Docker install you reach it through the frontend’s origin at http://localhost:3000/api/v1, because the api service only exposes port 8000 on the internal Compose network and the frontend’s nginx proxies /api/v1 to it. The interactive Swagger docs at /docs are not proxied, so seeing them means publishing the API port yourself from a docker-compose.override.yml; the API reference has that snippet.

Use an API key for scripts. The key is a login credential, not a permanent Bearer token. Exchange it for a short-lived access token before calling protected endpoints.

Get an API key

Open Settings -> Access, create a named API key, and copy it when it appears. PrintStash shows the full key once. A name such as nas scan or backup job makes later cleanup easier.

Exchange the username and API key at the login endpoint:

curl -s -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"automation","api_key":"<api-key>"}'

Copy the returned access_token and send it as a Bearer token:

TOKEN="<access-token>"
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/v1/models

The token carries the permissions of the account that owns the key. Use a separate non-admin account when the automation does not need admin access. Revoke old keys from the same Settings page.

Upload a source model

Source meshes use the ingest endpoint. Processing is asynchronous, so the response contains a job ID rather than a finished model:

curl -X POST http://localhost:3000/api/v1/ingest/model \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@bracket.stl" \
  -F "model_name=Voron panel bracket" \
  -F "tags=voron,abs"

Poll GET /api/v1/ingest/jobs/{job_id} if the script needs to wait for hashing, parsing, thumbnail generation, and deduplication to finish.

Upload OrcaSlicer G-code

The OrcaSlicer endpoint accepts G-code plus optional model and collection context:

curl -X POST http://localhost:3000/api/v1/ingest/orca \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@bracket.gcode" \
  -F "model_name=Voron panel bracket" \
  -F "collection=Functional/Brackets"

PrintStash already ships an OrcaSlicer post-processing hook for this job. Use the API directly when you need different naming, tagging, or scheduling logic.

Trigger a shared-volume scan

Shared folders are exposed as libraries in the API. Start a scan with the library ID:

curl -X POST http://localhost:3000/api/v1/libraries/12/scan \
  -H "Authorization: Bearer $TOKEN"

The response also returns a job ID. PrintStash can schedule scans itself, so an external trigger is most useful after a separate download or sync job finishes.

Query before building a report

GET /api/v1/models supports search, filtering, and paging. The exact query parameters can change as library filters improve, so use the Swagger page on your running version as the contract rather than copying an old URL from a blog post.

That endpoint is enough for a personal dashboard or inventory report. Related endpoints expose collections, tags, printer status, filament profiles, backups, and health information.

Keep the first script small

Start with one repeatable task: upload the output of another tool, scan a NAS folder after a sync, or export model metadata. Confirm the script handles an expired token and a non-2xx response before putting it in cron.

Do not embed an account password in a hook. Store the API key as a secret, request a fresh access token when the job runs, and keep the automation account’s permissions as narrow as the task allows.

The S3 backup automation guide applies this login flow to a superuser-only endpoint. For automatic slicer uploads, the G-code revision guide explains where the uploaded file fits in the model history.