API Reference

Two simple steps: search for links, then fetch the pages you want to read. Base URL: https://www.laurel.dev/api/v1

Getting started

Sign in to the dashboard and an API key (lrl_...) is created for you.
Search for pages, then fetch the ones you want to read:

# 1. search for relevant links
curl -X POST https://www.laurel.dev/api/v1/search \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"q": "what is the capital of Australia"}'

# 2. fetch a page's content
curl -X POST https://www.laurel.dev/api/v1/fetch \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://en.wikipedia.org/wiki/Canberra"}'

Authentication

Every request needs your API key in the Authorization header. Rotate it anytime from the dashboard.

Authorization: Bearer lrl_your_key_here

1. Search

POST/search

Finds relevant pages and returns a list of results, no page content. Read the snippets to decide which URLs are worth fetching.

Parameter	Type		Description
q	string	required	The search query in plain language. Max 400 characters.
limit	integer 1-10	default: 3	How many results to return.
freshness	string	optional	Only return results from a time window: day, week, month, or year. Use for current events.

Response

{
  "query": "what is the capital of Australia",
  "results": [
    {
      "title": "Canberra - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Canberra",
      "snippet": "Canberra is the capital city of Australia...",
      "favicon": "https://www.google.com/s2/favicons?domain=en.wikipedia.org&sz=64"
    }
  ],
  "tookMs": 720,
  "requestId": "j97denn8pz3zygngxn517mp3vh8a5mag"
}

2. Fetch

POST/fetch

Fetches the readable content of one or more URLs (from your search results) as clean Markdown. Pass a single URL or an array of up to 3. Fetch only what you need; a fetch costs a third of a search toward your limit.

Parameter	Type		Description
url	string \| string[]	required	A single URL, or an array of up to 3 URLs to fetch at once.
format	string	default: full	full returns the whole article (~8k chars). compact returns just the lead section (~1500 chars).
output	string	default: markdown	markdown (clean text) or html (cleaned article HTML).

Response

{
  "pages": [
    {
      "url": "https://en.wikipedia.org/wiki/Canberra",
      "title": "Canberra",
      "content": "# Canberra\n\nCanberra is the capital city of Australia...",
      "truncated": false
    }
  ],
  "requestId": "j97denn8pz3zygngxn517mp3vh8a5mag"
}

Some hosts (Reddit, X, and other walled gardens) block automated fetching. Those return { "blocked": true, "error": ... }. Use the snippet from your search result instead.

Limits & errors

Free plan: 50 searches + 150 fetches per month. Searches and fetches are counted separately, so reading pages never eats into your searches. Personal is unlimited (fair-use cap of up to 1,050 URLs / 3 hours).

400	Bad request: a required parameter is missing or out of range.
401	Missing, invalid, or revoked API key.
429	Rate limit reached: up to 1,050 URLs every 3 hours (105 searches), counted from your first search. The response includes resetAt (when access returns).
502	A search engine or page was temporarily unreachable. Retry.

MCP server

laurel.dev ships a hosted Model Context Protocol server exposing two tools: web_search and fetch_page. Point any MCP client at it and your agent runs the search-then-fetch loop natively.

POSThttps://www.laurel.dev/api/v1/mcp

Claude Code

claude mcp add --transport http laurel https://www.laurel.dev/api/v1/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

Cursor / JSON config

{
  "mcpServers": {
    "laurel": {
      "url": "https://www.laurel.dev/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Prompt for agents

Not using MCP? Copy this into your agent's system prompt, replace <YOUR_API_KEY> with a key from the dashboard, and it has everything it needs to search and read the web.

You have access to laurel.dev, a web search tool with two steps: search for links, then fetch the pages you want to read. Use it whenever you need current or factual information from the web.

STEP 1. Search for relevant pages:
POST https://www.laurel.dev/api/v1/search
Header: Authorization: Bearer <YOUR_API_KEY>
Header: Content-Type: application/json
Body: {"q": "<your search query>"}
Returns: {"results": [{"title", "url", "snippet"}]}

STEP 2. Fetch the content of the pages worth reading:
POST https://www.laurel.dev/api/v1/fetch
Header: Authorization: Bearer <YOUR_API_KEY>
Header: Content-Type: application/json
Body: {"url": "<url from search results>"}
Returns: {"pages": [{"url", "title", "content"}]}  (content is clean Markdown)

Search parameters:
- q (required): the search query, e.g. "best rust web framework 2026"
- limit (optional, 1-10, default 3): number of results
- freshness (optional): day | week | month | year (only recent results)

Fetch parameters:
- url (required): one URL, or an array of up to 3 URLs
- format (optional): full (default, ~8k chars) or compact (~1500 chars)
- output (optional): markdown (default) or html

How to use them together: call search first, read the snippets, then call fetch only on the URLs you actually need. Fetch one or a few at a time to keep your context small. Always cite the source URLs you relied on.

Example:
curl -X POST https://www.laurel.dev/api/v1/search -H "Authorization: Bearer <YOUR_API_KEY>" -H "Content-Type: application/json" -d '{"q": "what is the capital of Australia"}'
curl -X POST https://www.laurel.dev/api/v1/fetch -H "Authorization: Bearer <YOUR_API_KEY>" -H "Content-Type: application/json" -d '{"url": "https://en.wikipedia.org/wiki/Canberra"}'