Skip to content
merran
GitHubInstall

Merran documentation API & integrations

Swap an ingredient in a recipe for good

POST
/api/recipes/{recipe}/swap
curl --request POST \
  --url http://localhost:3000/api/recipes/lemon-chicken/swap \
  --header 'Content-Type: application/json' \
  --cookie merran.session_token=<merran.session_token> \
  --data '{ "ingredientId": "0199e8b0-5a10-7a01-8b00-000000000012", "lines": [ "1 tbsp butter" ], "steps": [] }'

Puts lines in an ingredient’s place, and rewrites the steps given, as one change that keeps a version of how it was. The answer has that version’s id, to restore to undo it. 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
ingredientId
required
string
lines
required
Array<string>
>= 1 items <= 5 items
steps
Array<object>
<= 20 items
object
stepId
required
string
text
required

The step, rewritten.

string
<= 5000 characters

Example 

{
  "ingredientId": "0199e8b0-5a10-7a01-8b00-000000000012",
  "lines": [
    "1 tbsp butter"
  ],
  "steps": []
}

Responses

Section titled “Responses”

200

Section titled “200”

Swapped.

Media typeapplication/json
object
recipe
required
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
undoVersionId
required

The version of the recipe as it was, to restore to undo the swap.

string | null

Example 

{
  "recipe": {
    "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."
      }
    ]
  },
  "undoVersionId": "0199e8b0-5a10-7a01-8b00-00000000000d"
}

400

Section titled “400”

No lines, or too many.

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

409

Section titled “409”

The recipe changed since: the ingredient or a step is gone.

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.