API reference
Collections
The groupings recipes are filed into, and what goes in and out of them.
Paths below are relative to
https://recipejam.com/api/v1
/collections
List collections
Your collections, most recently changed first.
Parameters
| Field | Type | Notes |
|---|---|---|
perPage
|
integer · query | 1 to 100. Defaults to 25. |
page
|
integer · query | Which page, from 1. |
since
|
string · query | An ISO 8601 timestamp. Returns only what has changed since then, deleted records included, so a synced device can catch up without refetching everything. Url-encode it — a raw `+` in a query string arrives as a space. |
deleted
|
string · query | `only` lists the wastebasket — what was deleted and can still be restored, each with a `deletedAt`. `include` lists both. Left out, you get the ordinary listing. |
Response
200
with a page of Collection objects in the pagination envelope.
- Carries `recipeCount` but not the recipes themselves.
/collections/{collection}
Get a collection
One collection, with every recipe in it.
Parameters
| Field | Type | Notes |
|---|---|---|
collection
|
string · path | The collection id. |
Response
200
with a single Collection object under a `data` key.
- The nested recipes are the listing shape: no steps, no images beyond the cover.
/collections
Create a collection
Start a new one. Recipes are added afterwards.
Request body
| Field | Type | Notes |
|---|---|---|
name
required
|
string max 255 | What it is called. |
description
|
string, or null max 2000 | What belongs in it. |
isPublic
|
boolean | Defaults to false. |
tags
|
array of string each max 50 | Short labels. |
Example request body
{
"name": "Weeknights",
"description": "Anything on the table inside forty minutes."
}Response
201
with a single Collection object under a `data` key.
/collections/{collection}
PUT
Update a collection
Rename it, publish it, or change its tags.
Parameters
| Field | Type | Notes |
|---|---|---|
collection
|
string · path | The collection to change. |
Request body
| Field | Type | Notes |
|---|---|---|
name
|
string max 255 | A new name. |
description
|
string max 2000 | A new description. Known limitation: sending null leaves the existing one in place rather than clearing it. |
isPublic
|
boolean | Publish or unpublish. |
tags
|
array of string | Replaces the whole tag list. |
Example request body
{
"isPublic": true
}Response
200
with a single Collection object under a `data` key.
- PUT is accepted and behaves identically to PATCH.
/collections/{collection}
Delete a collection
Removes the grouping. Only works when the collection is empty; the recipes are never touched.
Parameters
| Field | Type | Notes |
|---|---|---|
collection
|
string · path | The collection to delete. |
Response
204
with an empty body.
- A collection with recipes in it comes back 422 saying how many. Take them out first — deliberately, because deleting a full collection also empties the books built from it and there is no undo.
/collections/{collection}/restore
Restore a collection
Takes one back out of the bin.
Parameters
| Field | Type | Notes |
|---|---|---|
collection
|
string · path | The deleted collection. Find it with `since`, which reports it with a `deletedAt`. |
Response
200
with a single Collection object under a `data` key.
- It comes back empty, which is how it went in — only an empty collection can be deleted.
- Past the retention window this answers 404.
/collections/{collection}/reader
Read a collection
The whole collection as pages: its cover, a contents page, then every recipe in full.
Parameters
| Field | Type | Notes |
|---|---|---|
collection
|
string · path | The collection to read. |
Response
200
with a single reader object under a `data` key.
- Each recipe inside is bounded rather than running end to end: `exitTo` on every page, `backTo` on a recipe cover and `nextTo` on its last page all point at the contents. Reading a collection means choosing a recipe and reading that recipe.
- The cover carries one combined shopping list for the whole collection, with the same ingredient asked for by three recipes appearing once. Amounts are grouped by unit and never converted, because converting needs a density nobody supplied.
- An empty collection returns no pages.
/collections/{collection}/recipes
List a collection's recipes
What is in it, in the order it is filed. Not paginated.
Parameters
| Field | Type | Notes |
|---|---|---|
collection
|
string · path | The collection id. |
Response
200
with the Recipe objects under a `data` key. No pagination on this one.
/collections/{collection}/shopping-list
Shopping list for a collection
Every recipe's ingredients merged into one list, with the same thing asked for twice added up.
Parameters
| Field | Type | Notes |
|---|---|---|
collection
|
string · path | The collection to shop for. |
Response
200
| Field | Type | Notes |
|---|---|---|
data.ingredients
|
array of object | Each has `name`, `amount` and `from` — the recipes that asked for it. |
data.equipment
|
array of object | The same, for equipment. |
- Amounts are bucketed by unit and never converted: 4 tbsp and 150g of flour come back as "4 tbsp + 150g", because converting needs a density nobody supplied.
- An amount that is a word — "Grating of nutmeg" — is filed as the unit with no quantity. Read both.
/collections/{collection}/recipes
Add a recipe to a collection
Files an existing recipe into it. Adding one that is already there changes nothing.
Parameters
| Field | Type | Notes |
|---|---|---|
collection
|
string · path | The collection to file into. |
Request body
| Field | Type | Notes |
|---|---|---|
recipeId
required
|
string | The recipe to add. It must be one you can see — adding a recipe you cannot reach would show it to everyone the collection is shared with. |
Example request body
{
"recipeId": "w9jow0324z"
}Response
201
with {"message": "Recipe added."}.
/collections/{collection}/recipes/{recipe}
Remove a recipe from a collection
Takes it out of the grouping. The recipe itself is untouched.
Parameters
| Field | Type | Notes |
|---|---|---|
collection
|
string · path | The collection. |
recipe
|
string · path | The recipe to remove. |
Response
204
with an empty body.
Try these
The endpoints on this page, sent from your browser with your own token. Nothing is proxied through us.
Kept in this browser only, so it survives a reload. It is never sent to RecipeJam except as the header on the request you ask for.
The same request, as curl
The collection object
| Field | Type | Notes |
|---|---|---|
id
|
string | Opaque identifier. |
name
|
string | What the collection is called. |
description
|
string, or null | What belongs in it. |
isPublic
|
boolean | Whether it answers on its public share link. |
tags
|
array of string | Short labels. |
recipeCount
|
integer | How many recipes are filed into it. |
recipes
|
array of recipe | Only on a single collection, never in a listing. |
coverImage
|
image, or absent | Only when the collection has one. |
createdAt
|
string | ISO 8601. |
updatedAt
|
string | ISO 8601. |