🚀 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 standard, deep, and beta fast 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 three depth modes:

• with beta fast depth, the search is optimized for the quickest turnaround on lightweight queries

• with standard depth, the search uses an agentic workflow to handle broader queries across multiple topics or sources while remaining fast

• with deep depth, the search performs several agentic iterations for comprehensive coverage, making it slower but better suited to complex queries

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.

📝 Example

import { LinkupClient } from 'linkup-sdk';

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

const fetchLinkup = async () => client.fetch({
  url: 'https://docs.linkup.so',
  includeRawContent: true,
  renderJs: true,
});

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',
});