Public API

The public API lets your scripts, integrations, and backend services talk to your archive directly — upload images and videos, check their processing state, and search the library with the same engine the app uses. All endpoints live under /api/v1 and speak JSON.

Base URL and format

https://your-host/api/v1

Requests and responses are JSON (uploads use multipart/form-data). Every request is authenticated with an API key sent as a Bearer token — see Authentication. Session cookies are never accepted on API routes.

Quick start

1. Create an API key. In the app, open Settings → API keys, create a key with the upload and search scopes, and copy the secret — it starts with na_ and is shown only once.

2. Upload a file.

curl -X POST https://your-host/api/v1/files \
  -H "Authorization: Bearer na_your_key" \
  -F "file=@sunset.jpg"

The response is 202 Accepted — processing happens in the background:

{ "id": "0198c9a0-…", "version_id": "0198c9a0-…", "status": "processing" }

3. Poll until it's ready.

curl https://your-host/api/v1/files/0198c9a0-… \
  -H "Authorization: Bearer na_your_key"

Once status is ready, the file has dimensions, a thumbnail URL, and is findable in search.

4. Search for it.

curl -X POST https://your-host/api/v1/search \
  -H "Authorization: Bearer na_your_key" \
  -H "Content-Type: application/json" \
  -d '{"q": "sunset at the beach"}'

What's in this section

  • Authentication — API keys, scopes, and rate limits.
  • Uploading files — direct uploads up to 100 MB and status polling.
  • Searching — queries, the full filter surface, and pagination.
  • Large file uploads — resumable tus uploads for files over 100 MB.
  • Errors — the uniform error format and every error code.

Not in v1

  • OAuth or per-user third-party tokens — keys are created by account members.
  • Original file downloads — responses include thumbnail URLs only.
  • Facet listings and find-similar endpoints.
PreviousReview roundsNextAuthentication