Merran documentation API & integrations
Add a recipe
POST
/api/recipes
const url = 'http://localhost:3000/api/recipes';const options = { method: 'POST', headers: { cookie: 'merran.session_token=<merran.session_token>', 'Content-Type': 'application/json' }, body: '{"name":"Lemon Chicken","description":"Crisp chicken thighs roasted with lemon, garlic and thyme.","servings":4,"prepMinutes":10,"cookMinutes":40,"sourceUrl":"https://example.com/lemon-chicken","tags":["chicken","dinner"],"ingredients":["2 lb chicken thighs","1 tbsp olive oil","2 lemons, juiced","4 cloves garlic, smashed"],"steps":["Heat the oven to 425°F.","Toss the chicken with the oil, lemon juice, garlic, salt and pepper.","Roast skin side up for 40 minutes, until crisp."]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:3000/api/recipes \ --header 'Content-Type: application/json' \ --cookie merran.session_token=<merran.session_token> \ --data '{ "name": "Lemon Chicken", "description": "Crisp chicken thighs roasted with lemon, garlic and thyme.", "servings": 4, "prepMinutes": 10, "cookMinutes": 40, "sourceUrl": "https://example.com/lemon-chicken", "tags": [ "chicken", "dinner" ], "ingredients": [ "2 lb chicken thighs", "1 tbsp olive oil", "2 lemons, juiced", "4 cloves garlic, smashed" ], "steps": [ "Heat the oven to 425°F.", "Toss the chicken with the oil, lemon juice, garlic, salt and pepper.", "Roast skin side up for 40 minutes, until crisp." ] }'Ingredients and steps are lines, one each, as typed in the editor; a line starting with “#” starts a section. Each ingredient line is read into its amount, unit, food and note. With an API key, it needs the recipes: write permission.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Media typeapplication/json
object
name
required
string
description
string | null
servings
number | null
yieldText
What it makes, when that isn’t servings: “2 loaves”.
string | null
prepMinutes
integer | null
cookMinutes
integer | null
totalMinutes
integer | null
notes
string | null
rating
integer | null
tags
Array<string>
ingredients
Array<string>
Example
[ "# Dough", "2 cups flour", "1 tsp salt"]steps
Array<string>
Example
{ "name": "Lemon Chicken", "description": "Crisp chicken thighs roasted with lemon, garlic and thyme.", "servings": 4, "prepMinutes": 10, "cookMinutes": 40, "sourceUrl": "https://example.com/lemon-chicken", "tags": [ "chicken", "dinner" ], "ingredients": [ "2 lb chicken thighs", "1 tbsp olive oil", "2 lemons, juiced", "4 cloves garlic, smashed" ], "steps": [ "Heat the oven to 425°F.", "Toss the chicken with the oil, lemon juice, garlic, salt and pepper.", "Roast skin side up for 40 minutes, until crisp." ]}Responses
Section titled “Responses”Added.
Media typeapplication/json
object
id
required
string
slug
required
string
name
required
string
description
required
string | null
servings
required
number | null
totalMinutes
required
As given, or prep and cook added up.
number | null
rating
required
number | null
tags
required
Array<string>
diets
required
Diet labels worked out from the ingredients, with the household’s corrections.
Array<string>
photo
required
Where its photo is, in each size, or null. The links change with the photo, so they can be kept.
object
full
required
For the recipe page.
string
card
required
Cropped, for recipe cards.
string
lastMadeAt
required
string | null format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
origin
required
string
photoByAi
required
Its photo was made by AI, in the household’s style. Making another replaces it; a real one always does.
boolean
sourceUrl
required
string | null
yieldText
required
string | null
prepMinutes
required
number | null
cookMinutes
required
number | null
notes
required
string | null
dietOverrides
required
Where the household corrected the labels the ingredients suggest.
object
vegetarian
boolean
vegan
boolean
gluten-free
boolean
dairy-free
boolean
egg-free
boolean
nut-free
boolean
needs
required
Foods the household said it can’t do without: a dislike that’s usually left out of recipes rules this one out instead.
Array<string>
nutrition
required
Per serving, when it’s known.
object
source
required
From the recipe’s site, worked out from USDA’s data, or estimated by AI.
string
calories
Kcal.
number
protein
Grams.
number
carbs
Grams.
number
fat
Grams.
number
fiber
Grams.
number
sugar
Grams.
number
sodium
Milligrams.
number
missing
Ingredient lines that couldn’t be counted.
Array<string>
servings
The servings it’s for; it rescales when they change.
number
ingredients
required
Array<object>
object
id
required
string
section
required
string | null
text
required
The line as written.
string
quantity
required
number | null
quantityMax
required
number | null
unit
required
string | null
food
required
string | null
note
required
string | null
mark
required
What it is to the dish, as tidy up marked it: needed, swappable or optional. A dislike is left out of lines that aren’t needed. None until marked.
string | null
steps
required
Array<object>
object
id
required
string
section
required
string | null
text
required
string
Example
{ "id": "0199e8b0-5a10-7a01-8b00-000000000006", "slug": "lemon-chicken", "name": "Lemon Chicken", "description": "Crisp chicken thighs roasted with lemon, garlic and thyme.", "servings": 4, "totalMinutes": 50, "rating": 5, "tags": [ "chicken", "dinner" ], "diets": [ "gluten-free", "dairy-free", "egg-free", "nut-free" ], "photo": { "full": "/api/recipes/0199e8b0-5a10-7a01-8b00-000000000006/photo?size=full&v=4b1c2d3e", "card": "/api/recipes/0199e8b0-5a10-7a01-8b00-000000000006/photo?size=card&v=4b1c2d3e" }, "lastMadeAt": "2026-10-09T01:15:00.000Z", "createdAt": "2026-10-01T17:30:00.000Z", "updatedAt": "2026-10-15T18:30:00.000Z", "origin": "link", "photoByAi": false, "sourceUrl": "https://example.com/lemon-chicken", "yieldText": null, "prepMinutes": 10, "cookMinutes": 40, "notes": "Bone-in thighs work too: give them 10 minutes more.", "dietOverrides": {}, "needs": [], "nutrition": { "source": "calculated", "calories": 412, "protein": 31.5, "carbs": 6.2, "fat": 28.1, "fiber": 1.4, "sugar": 1.2, "sodium": 640, "missing": [], "servings": 4 }, "ingredients": [ { "id": "0199e8b0-5a10-7a01-8b00-000000000011", "section": null, "text": "2 lb chicken thighs", "quantity": 2, "quantityMax": null, "unit": "pound", "food": "chicken thighs", "note": null, "mark": "needed" }, { "id": "0199e8b0-5a10-7a01-8b00-000000000012", "section": null, "text": "1 tbsp olive oil", "quantity": 1, "quantityMax": null, "unit": "tablespoon", "food": "olive oil", "note": null, "mark": "optional" }, { "id": "0199e8b0-5a10-7a01-8b00-000000000013", "section": null, "text": "2 lemons, juiced", "quantity": 2, "quantityMax": null, "unit": null, "food": "lemons", "note": "juiced", "mark": "needed" }, { "id": "0199e8b0-5a10-7a01-8b00-000000000014", "section": null, "text": "4 cloves garlic, smashed", "quantity": 4, "quantityMax": null, "unit": "clove", "food": "garlic", "note": "smashed", "mark": "swappable" } ], "steps": [ { "id": "0199e8b0-5a10-7a01-8b00-000000000015", "section": null, "text": "Heat the oven to 425°F." }, { "id": "0199e8b0-5a10-7a01-8b00-000000000016", "section": null, "text": "Toss the chicken with the oil, lemon juice, garlic, salt and pepper." }, { "id": "0199e8b0-5a10-7a01-8b00-000000000017", "section": null, "text": "Roast skin side up for 40 minutes, until crisp." } ]}Something isn’t right, field by field.
Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
fields
object
key
additional properties
string
Example
{ "error": { "code": "not_found", "message": "There's nothing here.", "fields": { "name": "Give it a name." } }}Not signed in.
Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
fields
object
key
additional properties
string
Example
{ "error": { "code": "not_found", "message": "There's nothing here.", "fields": { "name": "Give it a name." } }}Not allowed.
Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
fields
object
key
additional properties
string
Example
{ "error": { "code": "not_found", "message": "There's nothing here.", "fields": { "name": "Give it a name." } }}© 2026 Kyle Johnson. Documentation: CC BY 4.0. Merran: AGPL-3.0-or-later.