Merran documentation API & integrations
Add a recipe from text
POST
/api/recipes/import/text
const url = 'http://localhost:3000/api/recipes/import/text';const options = { method: 'POST', headers: { cookie: 'merran.session_token=<merran.session_token>', 'Content-Type': 'application/json' }, body: '{"text":"Lemon Chicken\n\n4 chicken thighs\n2 lemons, juiced\n1 tsp salt\n\nRub the chicken with lemon and salt. Roast at 200°C for 40 minutes.","sourceUrl":null}'};
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/import/text \ --header 'Content-Type: application/json' \ --cookie merran.session_token=<merran.session_token> \ --data '{ "text": "Lemon Chicken\n\n4 chicken thighs\n2 lemons, juiced\n1 tsp salt\n\nRub the chicken with lemon and salt. Roast at 200°C for 40 minutes.", "sourceUrl": null }'Text with a recipe in it, from an email, a note or a message, read by AI and added as a recipe. Uses the household’s model for importing, and counts towards its AI spend. With an API key, it needs the recipes: write permission.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”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." } ]}No text, or too much.
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." } }}No recipe found in it.
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." } }}This month’s AI limit is reached, or the AI is busy.
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." } }}The AI provider failed.
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.