Get started

The Savorum API is the same HTTP API the web app uses. This page gets a script or service talking to it. The overview covers credentials and conventions, and each operation has its own page.

Get a token

Sign in to the instance and open Your account → API tokens. Name the integration, choose its scopes, libraries, and expiry, then choose Create token. Copy the secret now and keep it in your integration’s secret store: Savorum can’t show it again.

Send the token in the Authorization header. Savorum never accepts a token in a query string.

A token acts as you, limited to its scopes and libraries. Create a personal API token in the manual covers scopes, lifetimes, and rotation.

Choose a library

Name the library with X-Savorum-Library on every library request. Without it, Savorum uses the first library the token can reach, which changes when your memberships change.

export SAVORUM_URL=https://recipes.example.com
export SAVORUM_TOKEN=...
export SAVORUM_LIBRARY=...

Make your first requests

Check what the instance offers, then search for recipes:

curl --fail -H "Authorization: Bearer $SAVORUM_TOKEN" \
  "$SAVORUM_URL/api/v1/capabilities"

curl --fail -H "Authorization: Bearer $SAVORUM_TOKEN" \
  -H "X-Savorum-Library: $SAVORUM_LIBRARY" \
  "$SAVORUM_URL/api/v1/recipes?q=bread"

The q parameter takes the same search the web app uses. See search for a recipe.

To change a resource, send the revision you read in If-Match. A stale revision returns 412, and a missing one returns 428. Read the resource again, then decide what to do.

Check capabilities

Discover capabilities tells you what this instance supports before you rely on it.

• auth_features lists the sign-in features, even without a token. The native ones are covered in native app sign-in.
• features lists optional features, such as meal_planning, shopping, webhooks, events.sse, bulk.jobs, import.jobs, and api.idempotency. Hide the parts of your client that need a missing feature.
• limits lists the sizes the server enforces, such as the synchronous bulk limit and request size. Stay under them instead of hard-coding numbers.

A listed feature means the instance has it, not that you may use it. Every request still checks your access to the resource.

Cache the document for the session and read it again after you reconnect. New fields and identifiers can appear at any time, so ignore ones you don’t know.

Pick recipes, books, and saved meals

For a picker, use the suggestion endpoints instead of loading full lists: GET /api/v1/recipes/suggestions, /api/v1/books/suggestions, and /api/v1/saved-meals/suggestions. Each takes q, limit, and offset, and returns short summaries.

There is no total count. Keep adding the limit to the offset while has_more is true. Edits between requests can move a result to another page.

To show items someone already picked, post their IDs to POST /api/v1/recipes/lookup or POST /api/v1/books/lookup:

{ "ids": ["weeknight-dal", "sourdough-loaf"] }

Found items come back once each, in the order you asked. IDs that are missing, or that you can’t see, come back in unresolved_ids. A recipe in the trash still comes back, with deleted_at set, so you can show it as unavailable.

The largest request sizes are limits.suggestion_items and limits.lookup_items in capabilities.