Merran documentation API & integrations

The Review queue

GET

/api/proposals

const url = 'http://localhost:3000/api/proposals?limit=50&offset=0';
const options = {
  method: 'GET',
  headers: {cookie: 'merran.session_token=<merran.session_token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:3000/api/proposals?limit=50&offset=0' \
  --cookie merran.session_token=<merran.session_token>

What AI suggests, waiting to be applied or dismissed, newest first, a page at a time. With an API key, it needs the recipes: read permission.

Authorizations

session
apiKey

Parameters

Query Parameters

limit

integer

default: 50 >= 1 <= 100

offset

integer | null

recipe

Only this recipe’s, by its id or address.

string

Only this recipe’s, by its id or address.

Responses

200

What’s waiting.

application/json

object

proposals

required

Array<object>

object

required

string

kind

required

string

Allowed values: tidy note edit recipe meals list tastes import swap

status

required

string

Allowed values: pending applied dismissed

recipe

required

object

required

string

slug

required

string

name

required

string

summary

required

What it changes, in a sentence.

string

sections

required

The sections it changes, each applied or skipped on its own.

Array<string>

Allowed values: ingredients steps tags description details marks foods notes

note

required

The cooking note it came from, for one made from a note.

string | null

payload

required

What an assistant’s suggestion adds, by kind: recipe (a recipe, as the editor writes one), meals (meals for the plan), items (lines for the list), tastes to remember (avoid, diets, weeknightMinutes), a recipe page to import (url, name, site, photo, minutes, why), or a stand-in for an ingredient (ingredientId, insteadOf, lines, note, steps), which applying saves to the recipe. Null for changes to a recipe’s sections.

object | null

chat

required

The assistant’s chat it came from, for one from the assistant.

string | null

before

required

A recipe’s sections, only the ones a suggestion changes. Ingredients and steps are editor lines.

object

ingredients

Array<string>

steps

Array<string>

tags

Array<string>

description

string | null

details

object

servings

required

number | null

prepMinutes

required

number | null

cookMinutes

required

number | null

totalMinutes

required

number | null

marks

Array<object>

object

line

required

string

mark

required

string | null

Allowed values: needed swappable optional

foods

Array<object>

object

line

required

string

food

required

The food Merran knows that the line is, as a food key; null when no one has said.

string | null

notes

string | null

after

required

A recipe’s sections, only the ones a suggestion changes. Ingredients and steps are editor lines.

object

ingredients

Array<string>

steps

Array<string>

tags

Array<string>

description

string | null

details

object

servings

required

number | null

prepMinutes

required

number | null

cookMinutes

required

number | null

totalMinutes

required

number | null

marks

Array<object>

object

line

required

string

mark

required

string | null

Allowed values: needed swappable optional

foods

Array<object>

object

line

required

string

food

required

The food Merran knows that the line is, as a food key; null when no one has said.

string | null

notes

string | null

createdAt

required

string format: date-time

resolvedAt

required

string | null format: date-time

total

required

How many are waiting in all.

number

Example

{
  "proposals": [
    {
      "id": "0199e8b0-5a10-7a01-8b00-000000000029",
      "kind": "tidy",
      "status": "pending",
      "resolvedAt": null,
      "recipe": {
        "id": "0199e8b0-5a10-7a01-8b00-000000000006",
        "slug": "lemon-chicken",
        "name": "Lemon Chicken"
      },
      "summary": "Split a long step and marked the chicken as needed.",
      "sections": [
        "steps",
        "marks"
      ],
      "note": null,
      "payload": null,
      "chat": null,
      "before": {
        "steps": [
          "Rub the chicken with lemon and garlic, then roast it at 200°C for 40 minutes until golden. Enjoy!"
        ],
        "marks": [
          {
            "line": "2 lb chicken thighs",
            "mark": null
          },
          {
            "line": "2 lemons, juiced",
            "mark": null
          }
        ]
      },
      "after": {
        "steps": [
          "Rub the chicken with lemon and garlic.",
          "Roast at 200°C for 40 minutes, until golden."
        ],
        "marks": [
          {
            "line": "2 lb chicken thighs",
            "mark": "needed"
          },
          {
            "line": "2 lemons, juiced",
            "mark": "needed"
          }
        ]
      },
      "createdAt": "2026-10-01T17:30:00.000Z"
    }
  ],
  "total": 1
}

401

Not signed in.

application/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

Not allowed.

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