Merran documentation API & integrations

A starter collection

GET

/api/collections/{collection}

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

Its recipes that suit the household, and what Find more found for it last. With an API key, it needs the recipes: read permission.

Authorizations

session
apiKey

Parameters

Path Parameters

collection

required

string

Example

weeknight

Responses

200

The collection.

application/json

object

required

string

title

required

string

description

required

string

theme

required

What Find more looks for.

string

count

required

number

toImport

required

How many aren’t in the library yet.

number

photos

required

Up to four, for its card.

Array<string>

recipes

required

Up to 24 that suit the household, those not in its library first: the sites’ newest that fit, its hand-picked classics, then the rest.

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

found

required

Any of:

object
null

object

required

string

theme

required

string

collection

required

The starter collection it found more for (POST /collections/{collection}/find), or null.

string | null

status

required

Still searching, done, or failed (error says why).

string

Allowed values: searching done failed

error

required

string | null

recipes

required

Up to eight, each a page Merran opened and can import, no more than two from a site unless there aren’t others.

Array<object>

object

url

required

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

string

name

required

string

site

required

string

minutes

required

number | null

photo

required

string | null

why

required

Why it’s a good pick.

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

Example

{
  "id": "weeknight",
  "title": "Weeknight wins",
  "description": "Dinners on the table in 40 minutes or less.",
  "theme": "Weeknight dinners on the table in 40 minutes or less",
  "count": 2,
  "toImport": 1,
  "photos": [
    "/api/sites/recipes/0199e8b0-5a10-7a01-8b00-000000000031/photo"
  ],
  "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
    }
  ],
  "found": null
}

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

404

No such collection.

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