Find new recipes online

POST

/api/discover

curl --request POST \
  --url http://localhost:3000/api/discover \
  --header 'Content-Type: application/json' \
  --cookie merran.session_token=<merran.session_token> \
  --data '{ "theme": "cozy fall soups" }'

• Your Merran

Searches the web for recipes that fit a theme (“cozy fall soups”) and suit the household, in the background, with the household’s model for finding recipes, which must be able to search the web. Merran opens each page and keeps those it can import. Follow it at GET /discover/{discoveryId}; one at a time for a household. With an API key, it needs the recipes: write permission.

Authorizations

• session
• apiKey

Request Body^required

Media typeapplication/json

object

theme

required

string

>= 2 characters <= 200 characters

Example

{
  "theme": "cozy fall soups"
}

Responses

202

Searching.

Media typeapplication/json

object

id

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": "0199e8b0-5a10-7a01-8b00-00000000002d",
  "theme": "cozy fall soups",
  "collection": null,
  "status": "done",
  "error": null,
  "recipes": [
    {
      "url": "https://cooking.example/butternut-squash-soup",
      "name": "Roasted Butternut Squash Soup",
      "site": "cooking.example",
      "minutes": 60,
      "photo": "https://cooking.example/images/squash-soup.jpg",
      "why": "Vegetarian and freezes well, with the squash roasted for depth."
    }
  ],
  "createdAt": "2026-10-01T17:30:00.000Z",
  "updatedAt": "2026-10-01T17:30:00.000Z"
}

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

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

409

A search is going already.

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