Linkup Search

Linkup is a web search API for agents: it turns a natural-language instruction into retrieval actions (web search, scraping, LinkedIn, and more) and returns accurate, cited, real-time results.

A Linkup query is an instruction to a retrieval system, not a question to answer. Optimize for what to find and where, then do the synthesis yourself.

How to call it

MaraClaw automatically supplies LINKUP_API_BASE (the engine proxy base, including /api/linkup) and the agent-scoped LINKUP_PROXY_TOKEN. Use only this proxy for Linkup requests.

POST to $LINKUP_API_BASE/v1/search with a natural-language query and a depth. The same endpoint supports structured JSON output, domain filters (includeDomains/excludeDomains), and date filters (fromDate/toDate).

curl -sS -X POST "$LINKUP_API_BASE/v1/search" \
  -H "Authorization: Bearer $LINKUP_PROXY_TOKEN" -H "Content-Type: application/json" \
  -d '{"q":"...","depth":"standard","outputType":"searchResults"}'

Reason from the data request (before writing q)

Answer three questions in order - each narrows the next and lands you on a depth:

1. What inputs do I already have? A URL → scrape it directly (don't search to find it). A name/topic only → search. Both → combine (scrape the URL + search for the rest).
2. Where does the data live? A single fact usually in snippets (CEO, price, date) → fast. A few facts across snippets → standard. On full pages (tables, specs, long-form) → you must scrape. Unsure → deep.
3. Do I need to chain steps? All work is parallel → standard. Must find a URL then scrape it, or scrape multiple/discovered pages → deep. When uncertain, deep.

Then pick the output type - searchResults (you'll inspect/synthesize sources), sourcedAnswer (a human needs a direct cited answer), structured (software needs fields; always include a structuredOutputSchema) - and set hard filters (includeDomains, excludeDomains, fromDate, toDate) only when the source family or timeframe is actually implied. Never invent domains.

Key rule: standard cannot discover a URL and then scrape it in the same call - use deep ("first find the official page, then scrape it") or split into two calls.

Write the query as a retrieval plan

Make the plan visible: target entity/URL, the retrieval action (find/scrape/count/compare), the source scope, the exact fields to return, ordering (deep only), and "return source URLs / say none found." Name distinct facets rather than rewording the same search. Quote and disambiguate ambiguous names ("Clause AI" legal-tech startup).

Worked examples

Input: company name only · need: CEO (one fact) · not sequential
→ depth=fast · q: "Who is the CEO of {company}?"

Input: company name only · need: latest funding amount (lives in snippets) · not sequential
→ depth=standard · q: "Find {company}'s latest funding round amount and date"

Input: company name only · need: pricing (lives on a full page) · sequential (find page, then scrape)
→ depth=deep · q: "Find the pricing page for {company}. Scrape it. Extract plan names, prices, and features."

Input: a known URL · need: pricing from that page · not sequential
→ depth=standard (or the linkup-fetch skill) · q: "Scrape {url}. Extract plan names, prices, and included features."

Input: company name · need: ICP inferred from homepage + blog + case studies · sequential
→ depth=deep · q: "Find and scrape {company}'s homepage, use-case pages, and 2-3 recent blog posts. Extract industries, company sizes, job titles, and pain points."

Building with Linkup (integration code)

Everything above applies equally to the queries your code sends. When the
task is writing an integration rather than running a search now: use the
same authenticated proxy request shown above and bake the request-shape
rules into how your product constructs queries. See the per-endpoint agent briefs
at docs.linkup.so
for function-calling tool definitions; route their requests through the
MaraClaw engine proxy as well. Live-test queries through that proxy before
shipping them.

Read the full knowledge before non-trivial queries

This skill is the summary. For exact depth behavior, query templates, source-constraint rules, LinkedIn wording, local-place rules, and known bad patterns, read the bundled files in this skill's references/ directory:

• references/LINKUP_AGENT_QUERY_MENTAL_MODEL.md - how to reason from a data request to the right request shape.
• references/LINKUP_PROMPT_OPTIMIZER_KNOWLEDGE.md - the detailed rulebook: depth rules, templates, filters, LinkedIn, bad patterns.
• references/LINKUP_API_REFERENCE.md - endpoints, output types, auth, examples.

For scraping a known URL, use the linkup-fetch skill.