Merran documentation API & integrations

Followed recipe sites

GET

/api/sites

const url = 'http://localhost:3000/api/sites';
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/sites \
  --cookie merran.session_token=<merran.session_token>

The recipe sites the household follows, oldest followed first, each with its newest recipes; and suggested sites it doesn’t follow yet. Merran reads each site’s feed every few hours. With an API key, it needs the recipes: read permission.

Authorizations

session
apiKey

Responses

200

Its sites.

application/json

object

sites

required

Array<object>

object

required

string

name

required

string

url

required

string

feedUrl

required

string

recipes

required

Its newest recipes, newest first: posts Merran opened and can import.

Array<object>

object

required

string

url

required

The recipe’s page, to import at POST /recipes/import.

string

name

required

string

site

required

string

description

required

The recipe’s own short description, when the site gives one.

string | null

minutes

required

number | null

courses

required

What its site says it is, in Merran’s words; empty when it doesn’t say.

Array<string>

Allowed values: main side soup salad dessert baking breakfast snack drink sauce

photo

required

A small copy of its photo, through Merran.

string | null

publishedAt

required

string | null format: date-time

inLibrary

required

The household’s recipe from it, if it has one.

object

slug

required

string

name

required

string

suits

required

False when it has a food the household avoids, or is off its diets.

boolean

waiting

required

New posts not opened yet: Merran opens them a few seconds apart.

number

reading

required

Not read for the first time yet.

boolean

readAt

required

string | null format: date-time

error

required

Why its feed couldn’t be read last time.

string | null

followedAt

required

string format: date-time

suggestions

required

Sites that work well with Merran, not followed yet.

Array<object>

object

name

required

string

url

required

Follow it with this.

string

description

required

string

Example

{
  "sites": [
    {
      "id": "0199e8b0-5a10-7a01-8b00-000000000030",
      "name": "RecipeTin Eats",
      "url": "https://www.recipetineats.com/",
      "feedUrl": "https://www.recipetineats.com/feed/",
      "recipes": [
        {
          "id": "0199e8b0-5a10-7a01-8b00-000000000031",
          "url": "https://www.recipetineats.com/honey-garlic-chicken/",
          "name": "Honey Garlic Chicken",
          "site": "RecipeTin Eats",
          "description": "Juicy chicken in a sticky honey garlic sauce, in 12 minutes.",
          "minutes": 12,
          "courses": [
            "main"
          ],
          "photo": "/api/sites/recipes/0199e8b0-5a10-7a01-8b00-000000000031/photo",
          "publishedAt": "2026-10-01T17:30:00.000Z",
          "inLibrary": null,
          "suits": true
        },
        {
          "id": "0199e8b0-5a10-7a01-8b00-000000000032",
          "url": "https://www.recipetineats.com/lemon-chicken/",
          "name": "Lemon Chicken",
          "site": "RecipeTin Eats",
          "description": null,
          "minutes": 35,
          "courses": [
            "main"
          ],
          "photo": "/api/sites/recipes/0199e8b0-5a10-7a01-8b00-000000000031/photo",
          "publishedAt": "2026-10-01T17:30:00.000Z",
          "inLibrary": {
            "slug": "lemon-chicken",
            "name": "Lemon Chicken"
          },
          "suits": true
        }
      ],
      "waiting": 3,
      "reading": false,
      "readAt": "2026-10-15T18:30:00.000Z",
      "error": null,
      "followedAt": "2026-10-01T17:30:00.000Z"
    }
  ],
  "suggestions": [
    {
      "name": "Love and Lemons",
      "url": "https://www.loveandlemons.com/",
      "description": "Bright, seasonal vegetarian cooking."
    }
  ]
}

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