Skip to content
merran
GitHubInstall

Merran documentation API & integrations

Change a recipe

PUT
/api/recipes/{recipe}
curl --request PUT \
  --url http://localhost:3000/api/recipes/lemon-chicken \
  --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." ] }'

Replaces the whole recipe, as the editor saves it. The recipe as it was is kept as a version, so the change can be undone; its slug stays the same. With an API key, it needs the recipes: write permission.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
recipe
required

The recipe’s id, or its slug.

string

Example 

lemon-chicken

The recipe’s id, or its slug.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
>= 1 characters <= 200 characters
description
string | null
<= 2000 characters
servings
number | null
> 0 <= 1000
yieldText

What it makes, when that isn’t servings: “2 loaves”.

string | null
<= 100 characters
prepMinutes
integer | null
<= 100000
cookMinutes
integer | null
<= 100000
totalMinutes
integer | null
<= 100000
notes
string | null
<= 5000 characters
sourceUrl
Any of:
string format: uri
rating
integer | null
>= 1 <= 5
tags
Array<string>
default: <= 30 items
ingredients
Array<string>
default: <= 300 items

Example 

[
  "# Dough",
  "2 cups flour",
  "1 tsp salt"
]
steps
Array<string>
default: <= 200 items

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”

200

Section titled “200”

Saved.

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>
Allowed values: vegetarian vegan gluten-free dairy-free egg-free nut-free
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
Allowed values: link video text photo manual assistant mealie paprika merran
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
Allowed values: site calculated estimate
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
Allowed values: needed swappable optional
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."
    }
  ]
}

400

Section titled “400”

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."
    }
  }
}

401

Section titled “401”

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."
    }
  }
}

403

Section titled “403”

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."
    }
  }
}

404

Section titled “404”

No such recipe.

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.