Skip to content
Rigel docs
Open Rigel

Find recipes

recipes.recipe.search

GET/api/v1/households/{household_id}/queries/recipes.recipe.search

  • Query
  • Rigel runs it

Recipes whose title, summary, notes or ingredient names contain every word of text (ignoring case), or all recipes without text. Ordered by title.

Parameters#

Find recipes: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

textquerystringoptional

Words to look for, at most 200 characters.

at most 200 characters
limitqueryintegeroptional

How many to return, 1–200. Defaults to 50.

1 to 200Default 50
cursorquerystringoptional

The next_cursor of the previous page, with the same text.

at most 500 characters

Response#

200 The answer.

Find recipes: response fields
FieldDescription
itemsarray of objectsrequired
items[].idstringrequired

A recipe ID, such as rcp_01JC0000000000000000000000.

items[].titlestringrequired

The title.

items[].summarystring or nullrequired

One or two sentences about it, or null.

items[].servingsintegerrequired

How many servings it makes.

items[].prep_minutesinteger or nullrequired

Prep minutes, or null.

items[].cook_minutesinteger or nullrequired

Cook minutes, or null.

items[].total_minutesinteger or nullrequired

Prep plus cook minutes, or null.

items[].times_cookedintegerrequired

How many times it has been cooked.

items[].last_cooked_onstring (date) or nullrequired

The last day it was cooked, or null if never.

items[].icon_file_idstring or nullrequired

The small icon, or null.

items[].import_stateone of: none, importing, imported, failedrequired

none (made here), importing (a URL import is running), imported, or failed.

next_cursorstring or nullrequired

Send as cursor for the next page; null on the last page.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Find recipes: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404not_foundThe household doesn't exist, or you aren't a member of it.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Search recipes for pancakes

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search?text=pancakes' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search?text=pancakes", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search?text=pancakes HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSDTGB9192E167Y7RN8D

{
  "items": [
    {
      "id": "rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ",
      "title": "Saturday pancakes",
      "summary": "Fluffy, and easy for Nia to measure.",
      "servings": 4,
      "prep_minutes": 10,
      "cook_minutes": 15,
      "total_minutes": 25,
      "times_cooked": 0,
      "last_cooked_on": null,
      "icon_file_id": null,
      "import_state": "none"
    }
  ],
  "next_cursor": null
}

List every recipe

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSDWQE6KE3J960KR3CKE

{
  "items": [
    {
      "id": "rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ",
      "title": "Saturday pancakes",
      "summary": "Fluffy, and easy for Nia to measure.",
      "servings": 4,
      "prep_minutes": 10,
      "cook_minutes": 15,
      "total_minutes": 25,
      "times_cooked": 0,
      "last_cooked_on": null,
      "icon_file_id": null,
      "import_state": "none"
    },
    {
      "id": "rcp_01M6V9CSD8VZYF11AC568Y7QPZ",
      "title": "Tomato and white bean orzo",
      "summary": "One pot, 30 minutes. Good the next day too.",
      "servings": 4,
      "prep_minutes": 10,
      "cook_minutes": 20,
      "total_minutes": 30,
      "times_cooked": 0,
      "last_cooked_on": null,
      "icon_file_id": null,
      "import_state": "none"
    }
  ],
  "next_cursor": null
}

List recipes one at a time

limit and cursor page through the results; next_cursor is null on the last page.

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search?limit=1' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search?limit=1", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search?limit=1 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSDXNJJZF79MVERRQMCV

{
  "items": [
    {
      "id": "rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ",
      "title": "Saturday pancakes",
      "summary": "Fluffy, and easy for Nia to measure.",
      "servings": 4,
      "prep_minutes": 10,
      "cook_minutes": 15,
      "total_minutes": 25,
      "times_cooked": 0,
      "last_cooked_on": null,
      "icon_file_id": null,
      "import_state": "none"
    }
  ],
  "next_cursor": "saturday%20pancakes.rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ"
}

List the next recipe

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search?limit=1&cursor=saturday%2520pancakes.rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search?limit=1&cursor=saturday%2520pancakes.rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.search?limit=1&cursor=saturday%2520pancakes.rcp_01M6V9CSDDZVYFRVFNA4X5BSMZ HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSDY4FVR5BD7NTNRRJGB

{
  "items": [
    {
      "id": "rcp_01M6V9CSD8VZYF11AC568Y7QPZ",
      "title": "Tomato and white bean orzo",
      "summary": "One pot, 30 minutes. Good the next day too.",
      "servings": 4,
      "prep_minutes": 10,
      "cook_minutes": 20,
      "total_minutes": 30,
      "times_cooked": 0,
      "last_cooked_on": null,
      "icon_file_id": null,
      "import_state": "none"
    }
  ],
  "next_cursor": null
}

For Rigel#

Rigel's tool for this query is recipes_recipe_search. Rigel runs this on its own, then says what it did. The agent guide has the rest.

Rigel is in early access, and sign-up is by invitation. Open Rigel