🚀 Linkup JS/TS SDK

A JS/TS SDK for the Linkup API, allowing easy integration with Linkup's services.

🌟 Features

• ✅ Simple and intuitive API client.
• 🔍 Supports flash, fast, standard, and deep search depths.
• 🧠 Supports asynchronous research tasks and batched task workflows.
• 🔒 Handles authentication and request management.

📦 Installation

Requires Node.js >= 22

Simply install the Linkup JS SDK using npm or any other package manager:

npm i linkup-sdk

📚 Documentation

Find the complete documentation here.

🛠️ Usage

Setting Up Your Environment

1. 🔑 Obtain an API Key:

Sign up on Linkup to get your API key.

2. ⚙️ Set-up the API Key:

Pass the Linkup API key to the Linkup Client when creating it.

import { LinkupClient } from 'linkup-sdk';

const client = new LinkupClient({
  apiKey: '<YOUR API KEY>',
});

📋 Search Endpoint

All search queries can be used with four depth modes:

• flash is lowest latency: ranked sources and snippets in a few hundred milliseconds, built for low-latency use cases
• fast is higher-quality one-shot retrieval in about a second, the recommended default for most agentic applications
• standard is a single pass of agentic search for queries that span several topics or sources
• deep runs several search iterations, optimizing for coverage and multi-hop agentic workflows.

You can also refine search requests with:

• includeDomains and excludeDomains domain filters (includeDomains accepts up to 100 entries)
• fromDate and toDate ISO date filters
• maxResults to cap the number of returned results
• includeInlineCitations for sourcedAnswer output
• includeSources for structured output responses

Structured output schemas must use an object at their root (type: 'object').

📝 Example standard search query

import { LinkupClient } from 'linkup-sdk';

const client = new LinkupClient({
  apiKey: '<YOUR API KEY>',
});

const askLinkup = () => client.search({
  query: 'Can you tell me which women were awared the Physics Nobel Prize',
  depth: 'standard',
  outputType: 'sourcedAnswer',
});

askLinkup()
  .then(console.log)
  .catch(console.error);

⬇️ Fetch Endpoint

You can use the fetch endpoint to retrieve the content of a given URL in clean markdown format, together with the website's favicon URL.

Use renderJs to execute the JavaScript code of the page before returning the content.

Use includeRawContent to get the raw page content together with its contentType when available.

includeRawHtml remains available for backward compatibility, but the Linkup API now prefers includeRawContent.

Use extractImages to get an extracted list of images from the page.

Set mode to pro for significantly higher success rates on hard-to-retrieve pages. It defaults to standard.

Pass an object JSON schema to extract structured data. Optional instructions can guide the extraction and require a schema.

📝 Example

import { LinkupClient } from 'linkup-sdk';

const client = new LinkupClient({
  apiKey: '<YOUR API KEY>',
});

const fetchLinkup = async () => client.fetch({
  url: 'https://docs.linkup.so',
  schema: {
    type: 'object',
    properties: {
      title: { type: 'string' },
    },
  },
  instructions: 'Extract the page title.',
});

fetchLinkup()
  .then(console.log)
  .catch(console.error);

🧠 Research Endpoint

Use research to create an asynchronous research task, then poll it later or list recent runs.

The research endpoint also supports:

• mode: answer, auto, investigate, or research
• reasoningDepth: S, M, L, or XL
• listResearch({ page, pageSize, sortBy, sortDirection }) to page through recent runs

import { LinkupClient } from 'linkup-sdk';

const client = new LinkupClient({
  apiKey: '<YOUR API KEY>',
});

const task = await client.research({
  query: 'Research the current state of the semiconductor market, covering key market dynamics, major industry players and their strategic positioning, recent analyst sentiment, and the main bull and bear cases for the sector. Ground the report in sourced, factual information.',
  outputType: 'sourcedAnswer',
  mode: 'auto',
  reasoningDepth: 'L',
});

const latest = await client.getResearch(task.id);
const recent = await client.listResearch({ page: 1, pageSize: 10, sortDirection: 'desc' });

🗂️ Tasks Endpoint

Use createTasks to submit mixed search, fetch, and research jobs in one batch, then inspect them through listTasks or getTask.

createTasks accepts up to 100 tasks per batch. listTasks supports pagination and filtering via page, pageSize, sortBy, sortDirection, status, and type.

import { LinkupClient } from 'linkup-sdk';

const client = new LinkupClient({
  apiKey: '<YOUR API KEY>',
});

const tasks = await client.createTasks([
  {
    type: 'search',
    input: {
      query: 'Linkup latest product updates',
      depth: 'deep',
      outputType: 'sourcedAnswer',
    },
  },
  {
    type: 'fetch',
    input: {
      url: 'https://docs.linkup.so',
    },
  },
]);

console.log(tasks.map(task => task.id));

const queued = await client.listTasks({
  status: ['pending', 'processing'],
  type: ['search', 'research'],
  sortBy: 'updatedAt',
  sortDirection: 'desc',
  page: 1,
  pageSize: 20,
});

console.log(queued.quota);

💳 X402 Payment Protocol

The SDK supports the X402 payment protocol for direct search, fetch, and research creation calls, allowing you to pay with on-chain transactions instead of an API key. Task methods and research read/list methods require an API key.

Prerequisites

Install the required peer dependencies:

npm i viem @x402/core @x402/evm

📝 Example

Create a viem LocalAccount compatible with Base (Ethereum):

import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount('<YOUR WALLET PRIVATE KEY>');

import { mnemonicToAccount } from 'viem/accounts';

const account = mnemonicToAccount('<YOUR MNEMONIC PHRASE>');

Then pass it to createX402Signer and use the Linkup client:

import { LinkupClient } from 'linkup-sdk';
import { createX402Signer } from 'linkup-sdk/x402';

const signer = createX402Signer(account);
const client = new LinkupClient({ signer });

const response = await client.search({
  query: 'What is the X402 payment protocol?',
  depth: 'standard',
  outputType: 'sourcedAnswer',
});