Developer API

Search over a million recipes, manage bookmarks, and build shopping lists programmatically — via a REST API or by connecting an AI assistant over MCP. One token drives both.

Getting started

Create a free account (or sign in).
Open Account → API Tokens and create a token. Tick the permissions your integration needs: read, create, update, delete.
Send the token as a bearer header on every request.

curl https://www.recipesaint.com/api/v1/recipes/search?q=lasagna \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

The API is available on every plan, including Free. Endpoints return standard HTTP status codes; validation errors come back as 422 JSON. A route can also return 403 if your token lacks the required permission, 429 if you exceed your plan's rate limit, or 503 if the feature is currently unavailable.

Rate limits

Limits apply per account (across all your tokens). Responses carry X-RateLimit-Limit and X-RateLimit-Remaining headers; a 429 includes Retry-After.

Plan	Requests / minute	Requests / day	Search depth
Free	15	500	25 pages × 20 results
Pro	120	20,000	100 pages × 50 results

REST API v1

Recipes

Endpoint	Permission	Description
GET /api/v1/recipes/search?q=&page=&per_page=	read	Hybrid search across the recipe index. Returns ids for the endpoints below.
GET /api/v1/recipes/{id}	read	Recipe detail: title, source URL, ingredients with amounts, categories.

Saved recipes (bookmarks)

Endpoint	Permission	Description
GET /api/v1/saved-recipes?search=&page=&limit=	read	Your bookmarks, including AI-extracted precise ingredients. `search` is full-text over title, description, ingredients and categories, ranked by relevance; `limit` is the page size.
POST /api/v1/saved-recipes	create	Body: `{"recipe_id": "<search result id>"}`. Triggers background ingredient extraction.
DELETE /api/v1/saved-recipes/{guid}	delete	Remove a bookmark.

My Recipes (authored)

Endpoint	Permission	Description
GET /api/v1/my-recipes?search=&page=&per_page=	read	Recipes you wrote (or an assistant wrote for you). `search` is full-text over title, description, ingredients, instructions, tags and notes, ranked by relevance. Response carries `meta.total` and `meta.has_more`.
GET /api/v1/my-recipes/{id}	read	One authored recipe in full: ingredients, instructions, times, notes.

Shopping lists

Endpoint	Permission	Description
GET /api/v1/shopping-lists	read	All your lists with item counts.
GET /api/v1/shopping-lists/{id}	read	One list with items and checked state.
POST /api/v1/shopping-lists	create	Body: `{"name": "...", "items": ["2 cups flour", ...]}` (items optional).
POST /api/v1/shopping-lists/{id}/items	create	Append an item. Body: `{"name": "..."}`.
PATCH /api/v1/shopping-lists/{id}	update	Rename / edit details.
PATCH /api/v1/shopping-lists/{id}/items/{index}	update	Rename an item (zero-based index).
PATCH /api/v1/shopping-lists/{id}/items/{index}/toggle	update	Check / uncheck an item.
DELETE /api/v1/shopping-lists/{id}	delete	Delete a list (default list is protected).
DELETE /api/v1/shopping-lists/{id}/items/{index}	delete	Remove an item.

Menus

Endpoint	Permission	Description
GET /api/v1/menus	read	Your menus.
GET /api/v1/menus/{id}	read	One menu with its recipes.
POST /api/v1/menus	create	Body: `{"name": "...", "description": "...", "serves": 4}`.
POST /api/v1/menus/{id}/recipes	create	Attach a saved recipe. Body: `{"saved_recipe_guid": "..."}`.
PATCH /api/v1/menus/{id}	update	Edit menu details.
DELETE /api/v1/menus/{id}	delete	Delete a menu.
DELETE /api/v1/menus/{id}/recipes/{guid}	delete	Detach a recipe from a menu.

MCP server (AI assistants)

Recipe Saint speaks the Model Context Protocol, so AI assistants like Claude can search recipes, bookmark them, and build your shopping lists in conversation. It uses the same API token as the REST API — the tools your assistant sees match the permissions you ticked when creating the token.

Connect any MCP client (Streamable HTTP transport) to:

https://www.recipesaint.com/api/mcp
Authorization: Bearer YOUR_TOKEN

Example — Claude Code:

claude mcp add recipesaint https://www.recipesaint.com/api/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_TOKEN"

Available tools: search_recipes, get_recipe, save_recipe, list_saved_recipes, search_my_library, unsave_recipe, list_shopping_lists, get_shopping_list, create_shopping_list, add_items_to_shopping_list, toggle_shopping_list_item, list_menus, create_menu, add_recipe_to_menu, list_my_recipes, get_my_recipe, create_recipe, update_recipe, list_collections, create_collection, add_recipe_to_collection, start_menu_from_collection. Search your own library in plain words: "find my recipe with chipotle and cream cheese".

Try: "Find me a weeknight pad thai recipe, save it, and put the ingredients on my shopping list."