API Getting Started

Notory ships with a full REST API. The stable surface lives at /api/v1 and is versioned — a breaking change would be shipped as a new version path, so integrations built against /api/v1 keep working.

The complete, searchable reference for all endpoints is available at the API Reference.

Base URL

https://<deine-instanz>/api/v1

On the live demo, that’s https://demo.notory.io/api/v1. The machine-readable OpenAPI spec is served at /api/openapi.json — you can feed it into an OpenAPI generator to produce a typed client in any language (no separate SDK is needed).

Authentication

There are two options:

• Browser sessions use HttpOnly cookies plus a CSRF token (X-CSRF-Token). This is the path the web interface uses.
• Programmatic clients send an API token as a bearer header:

curl -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/assets

API tokens start with the prefix inv_. You create and manage them in the web interface under Settings → API Tokens (see API Tokens). The token is shown in plain text only once, at creation — after that, only its hash is stored.

Token scopes

A token can carry scopes:

Scope	Effect
read	Read-only access (GET, HEAD, OPTIONS).
write	Write access (POST, PUT, DELETE) — includes read access.
(empty)	Full access within the scope of the token owner’s role (backward compatibility).

The token always inherits the role and tenant of its owner — so a token can never do more than the user themself is allowed to do (RBAC and tenant isolation still apply).

SSO / SCIM

Identity providers can provision users via SCIM 2.0 at /scim/v2. SSO/OIDC is configured per tenant (see SSO / OIDC).

Rate limits

Sensitive endpoints (especially login/auth) are rate-limited per client IP (default: 60 requests/minute). If the limit is exceeded, the API responds with HTTP 429 (Too Many Requests); the Retry-After header states the wait time. Build backoff into your integrations.

Error codes

Status	Meaning
200 / 201	Success (201 on creation).
400	Invalid request (e.g. missing tenant in the token).
401	Not authenticated — token missing, invalid, or expired.
403	Authenticated, but not authorized (role/scope/feature gating).
404	Resource not found (or outside your own tenant).
422	Validation error — the response names the field and reason.
429	Rate limit reached (see above).

Error responses follow the FastAPI schema { "detail": "..." }, or for validation errors, a structured list under detail.

Pagination

List endpoints paginate via the query parameters page (starting at 1) and page_size (1–100, default 25), and return an object with items, total, page, page_size, and total_pages.

Next steps

• API Reference (Scalar) — every endpoint, ready to try.
• How do I create an asset? — GUI and API paths side by side.
• Managing API tokens — creating and revoking tokens.