Skip to main content

Lists and syncing

The list endpoints share one set of query parameters. This page covers paging through a list, choosing how much detail to return, and reading only the records that changed since your last request.

The list endpoints are:

  • GET /recipes
  • GET /recipe-books
  • GET /recipe-books/{id}/recipes
  • GET /labels

Paging with limit and offset​

  • limit. How many records to return. The default is 50 and the maximum is 200.
  • offset. How many records to skip before the first one returned. The default is 0.

Lists are ordered by ID, newest first.

To read a whole list, request pages until you have read meta.total records:

curl -H "Authorization: Bearer <API_KEY>" \
  "https://dev.nutritionistpro.com/v3/customer/recipes?limit=200&offset=0"

curl -H "Authorization: Bearer <API_KEY>" \
  "https://dev.nutritionistpro.com/v3/customer/recipes?limit=200&offset=200"

Invalid values are refused​

A value outside the allowed range returns 400. The API never adjusts a value for you, so a request for limit=5000 fails instead of returning 200 records that look like the whole list.

  • limit must be a whole number between 1 and 200.
  • offset must be a whole number of 0 or more.

The meta block​

Every list response has a meta block beside data:

{
  "status": true,
  "code": 200,
  "data": [],
  "meta": { "total": 37, "limit": 50, "offset": 0 }
}
  • total. The number of records that match the request, across all pages.
  • limit and offset. The values used for this response, including defaults.

Responses for a single record, such as GET /recipes/{id}, have no meta block.

Summary and full views​

The recipe lists accept a view parameter:

  • view=summary. The default. Each recipe has its ID, name, code, number of servings, and dates.
  • view=full. Each recipe has the same shape as GET /recipes/{id}, with nutrients and ingredient lines.

Use the summary view to find what changed, and the full view when you need the detail of every recipe on the page. Full responses are much larger, so a smaller limit keeps them quick.

Any other value for view returns 400.

view applies to GET /recipes and GET /recipe-books/{id}/recipes. The recipe book and label lists have one view.

Reading only what changed​

Every list accepts two date parameters that filter on updated_at:

  • updated_since. Returns records changed at or after this moment.
  • updated_until. Returns records changed before this moment.

Either parameter can be used alone, or both together.

Date formats​

Both parameters accept a date or a date and time:

  • A date, as YYYY-MM-DD. For example 2026-05-01.
  • A date and time in ISO 8601 format. For example 2026-05-01T14:30:00Z or 2026-05-01T09:30:00-05:00.

A date and time with no offset is read as UTC. All times in responses are UTC.

In a URL, write the + of a positive offset as %2B, or send the time in UTC with a Z.

How the range is applied​

  • updated_since includes the moment given. updated_since=2026-05-01 starts at the first instant of May 1, UTC.
  • updated_until with a date covers that whole day. updated_until=2026-05-31 includes changes made at any time on May 31, UTC.
  • updated_until with a date and time excludes that exact moment.

So this request returns every recipe changed in May 2026:

curl -H "Authorization: Bearer <API_KEY>" \
  "https://dev.nutritionistpro.com/v3/customer/recipes?updated_since=2026-05-01&updated_until=2026-05-31"

updated_since must be earlier than updated_until, and both must be valid dates. Otherwise the request returns 400.

A sync routine​

  1. On the first run, page through the whole list and store each record with its id.
  2. Record the time the run started.
  3. On each later run, request the list with updated_since set to the start time of the previous run, and page through the results.
  4. Replace your stored copy of each record returned.
  5. For recipe books, call GET /recipe-books/{id}/recipes and remove every recipe listed in deleted_recipe_ids.

Using the start time of the previous run means a record changed while that run was in progress is picked up by the next one.

What counts as a change to a recipe​

A recipe's updated_at is the time of its most recent save, whether that save changed the recipe's details or its ingredient lines. The date filters use the same time.

Deleted records​

A deleted record is no longer returned by any list, and its ID returns 404. For recipes in a recipe book, deleted_recipe_ids reports the deletions. For other records, compare the IDs you hold against a full read of the list from time to time.