Information
- License: AGPL-3.0-only
- OpenAPI version:
3.1.0
Overview
Savorum API 1
Section titled “Savorum API 1”The /api/v1 namespace is the compatibility boundary for browser, native, and external clients. Optional response fields and new operations may be added. Removing or renaming fields, changing meaning, tightening accepted inputs, or changing behavior through defaults requires a new API major. Clients must ignore unknown response fields.
Credentials and local mode
An instance started without --auth-enabled runs in local mode: it authenticates nobody and acts as one persisted local user, so keep it on loopback or behind an access-controlled network or proxy.
With authentication enabled, a browser session or a personal API token is required. Send a token as Authorization: Bearer <token>, and name a library with X-Savorum-Library: <library-id> when the token reaches more than one. A token’s authority is the intersection of its scopes, its optional library restriction, and the current membership of the account that owns it.
A request using any method other than GET, HEAD, or OPTIONS passes an origin check first. A cookie-authenticated one additionally requires the session-bound X-CSRF-Token header. Bearer requests set no cookie and need no CSRF header.
The bearerToken and browserSession security schemes name these credentials. Operations that answer without credentials declare that explicitly.
Extension boundary
External integrations use the authenticated HTTP API, versioned events, signed webhooks, SREF, and iCalendar. Internal import, export, authentication, and extraction adapters are compiled, typed components over canonical models and services. They receive no database handle. Adapter metadata is registered by the capability implementation, not a frontend list. There is no Go native plugin, shared-library loader, server-script runtime, plugin SQL migration, or plugin package manager. Any future richer extension protocol must be out of process with explicit capabilities and API authorization.
Conventions
Operation IDs are verb-resource. Responses that carry a revision use a strong ETag, and a conditional write echoes it in If-Match. Meals and saved meals differ: their ETag validates the representation as returned, and If-Match takes their revision field as a strong ETag. Problem responses use application/problem+json with stable machine-readable codes, field locations, and revision context. Missing write preconditions return 428, stale revisions return 412. Shopping field-edit conflicts retain their documented 409 outcome and explicit resolution flow.
Authentication
Section titled “Authentication”bearerToken
Section titled “bearerToken”A personal API token. An instance in local mode accepts requests without it.
Security scheme type: http
browserSession
Section titled “browserSession”A browser session; hosted instances use __Host-savorum_session, declared by their running OpenAPI document. Writes also send the session’s X-CSRF-Token header. An instance in local mode accepts requests without it.
Security scheme type: apiKey
Cookie parameter name: savorum_session