> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Linkup API reference

> API reference for the Linkup plugin in Corsair: every `linkup.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Answers

### get

`answers.get`

Search the web and return a written answer with its sources ($0.006; deep $0.055).

**Risk:** `read`

```ts theme={null}
await corsair.linkup.api.answers.get({ q: 'What is the capital of Norway?' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `q` | `string` | Yes | — |
| `depth` | `flash \| fast \| standard \| deep` | No | flash, fast and standard cost the same and get slower and broader in that order; deep runs several searches and costs 10x. Default fast. |
| `includeInlineCitations` | `boolean` | No | Put numbered citations inside the answer text. |
| `fromDate` | `string` | No | Only sources published on or after this date (YYYY-MM-DD). |
| `toDate` | `string` | No | Only sources published on or before this date (YYYY-MM-DD). |
| `includeDomains` | `string[]` | No | Only search these domains. |
| `excludeDomains` | `string[]` | No | Never return these domains. |

`POST /v1/search` with outputType sourcedAnswer. Source text is not stored.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `answer` | `string` | Yes | — |
| `sources` | `object[]` | Yes | — |

> [accordion] sources full type
>
> ```ts theme={null}
> {
>   name?: string,
>   url: string,
>   snippet?: string,
>   favicon?: string | null,
>   publishedAt?: string
> }[]
> ```

***

## Credits

### get

`credits.get`

Get the account's remaining credit balance in dollars.

**Risk:** `read`

```ts theme={null}
await corsair.linkup.api.credits.get({});
```

**Input:** *empty object*

`GET /v1/credits/balance`. Stores the balance.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `credit` | `object` | Yes | — |

> [accordion] credit full type
>
> ```ts theme={null}
> {
>   id: balance,
>   balance: number
> }
> ```

***

## Pages

### fetch

`pages.fetch`

Fetch one web page or PDF as markdown, optionally with typed data from a schema ($0.001 to $0.011).

**Risk:** `read`

```ts theme={null}
await corsair.linkup.api.pages.fetch({ url: 'https://example.com' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | — |
| `mode` | `standard \| pro` | No | pro gets past harder pages and costs 5x. Default standard. |
| `renderJs` | `boolean` | No | Run the page's JavaScript before reading it (costs 5x). |
| `extractImages` | `boolean` | No | — |
| `includeRawContent` | `boolean` | No | Also return the page's raw text. |
| `schema` | `Record<string, any>` | No | JSON Schema for typed data to pull from the page. |
| `instructions` | `string` | No | What to pull from the page, used with schema. |

`POST /v1/fetch`. Returns markdown and does not store the page.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `markdown` | `string` | Yes | — |
| `data` | `Record<string, any>` | No | — |
| `rawContent` | `string` | No | — |
| `images` | `any[]` | No | — |
| `contentType` | `string` | No | — |

***

## Research

### create

`research.create`

Start a multi-step research task ($0.25 to $2.50 by reasoningDepth). Poll research.get for the result.

**Risk:** `destructive`

```ts theme={null}
await corsair.linkup.api.research.create({ q: 'When did the Oslo Opera House open?', reasoningDepth: 'S' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `q` | `string` | Yes | The research question. |
| `reasoningDepth` | `S \| M \| L \| XL` | No | How hard to work: S $0.25 (default here), M $0.50, L $1.50, XL $2.50 per task. |
| `mode` | `auto \| answer \| investigate \| research` | No | — |
| `outputType` | `sourcedAnswer \| structured` | No | — |
| `schema` | `Record<string, any>` | No | JSON Schema for structured output; needed when outputType is structured. |
| `fromDate` | `string` | No | Only sources published on or after this date (YYYY-MM-DD). |
| `toDate` | `string` | No | Only sources published on or before this date (YYYY-MM-DD). |
| `includeDomains` | `string[]` | No | Only search these domains. |
| `excludeDomains` | `string[]` | No | Never return these domains. |

`POST /v1/research`. Returns the task; poll research.get.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `task` | `object` | Yes | — |

> [accordion] task full type
>
> ```ts theme={null}
> {
>   id: string,
>   type?: string,
>   status: string,
>   createdAt?: string,
>   updatedAt?: string,
>   error?: string | null,
>   input?: Record<string, any>,
>   output?: any
> }
> ```

***

### get

`research.get`

Get a research task: status, and the answer or structured data once completed.

**Risk:** `read`

```ts theme={null}
await corsair.linkup.api.research.get({ id: '4b26323e-c449-45ec-bf92-cd969ae98f7b' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

`GET /v1/research/{id}`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `task` | `object` | Yes | — |

> [accordion] task full type
>
> ```ts theme={null}
> {
>   id: string,
>   type?: string,
>   status: string,
>   createdAt?: string,
>   updatedAt?: string,
>   error?: string | null,
>   input?: Record<string, any>,
>   output?: any
> }
> ```

***

### list

`research.list`

List research tasks, newest or oldest first, paged.

**Risk:** `read`

```ts theme={null}
await corsair.linkup.api.research.list({ pageSize: 10, sortBy: 'createdAt', sortDirection: 'desc' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | — |
| `pageSize` | `number` | No | — |
| `sortBy` | `createdAt \| updatedAt` | No | — |
| `sortDirection` | `asc \| desc` | No | — |

`GET /v1/research`, paged.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tasks` | `object[]` | Yes | — |
| `meta` | `object` | No | — |
| `quota` | `object` | No | — |

> [accordion] tasks full type
>
> ```ts theme={null}
> {
>   id: string,
>   type?: string,
>   status: string,
>   createdAt?: string,
>   updatedAt?: string,
>   error?: string | null,
>   input?: Record<string, any>,
>   output?: any
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   page?: number,
>   pageSize?: number,
>   total?: number,
>   totalPages?: number
> }
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
>   inFlight?: number,
>   limit?: number
> }
> ```

***

## Responses

### create

`responses.create`

Generate an answer grounded in live web results (OpenAI Responses format). Paid generation.

**Risk:** `destructive`

```ts theme={null}
await corsair.linkup.api.responses.create({ input: 'What changed in the latest Node.js release?', model: 'linkup-standard' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `input` | `string` | Yes | — |
| `model` | `linkup-standard \| linkup-deep` | Yes | linkup-standard is faster; linkup-deep is more thorough. |
| `instructions` | `string` | No | System-style instructions for the answer. |

`POST /v1/responses` (OpenAI Responses format). Stores id, model, and object.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `response` | `object` | Yes | — |
| `outputText` | `string` | Yes | — |

> [accordion] response full type
>
> ```ts theme={null}
> {
>   id: string,
>   model?: string,
>   object?: string
> }
> ```

***

## Search

### run

`search.run`

Search the web and return results with their text content ($0.005 a call; deep $0.05). Filter by date and domain.

**Risk:** `read`

```ts theme={null}
await corsair.linkup.api.search.run({ q: 'Corsair integrations for AI agents', depth: 'fast', maxResults: 5, fromDate: '2026-01-01' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `q` | `string` | Yes | What to search for, in plain language. |
| `depth` | `flash \| fast \| standard \| deep` | No | flash, fast and standard cost the same and get slower and broader in that order; deep runs several searches and costs 10x. Default fast. |
| `maxResults` | `number` | No | — |
| `includeImages` | `boolean` | No | Also return image results. |
| `fromDate` | `string` | No | Only sources published on or after this date (YYYY-MM-DD). |
| `toDate` | `string` | No | Only sources published on or before this date (YYYY-MM-DD). |
| `includeDomains` | `string[]` | No | Only search these domains. |
| `excludeDomains` | `string[]` | No | Never return these domains. |

`POST /v1/search` with outputType searchResults. Stores name, url, type, and date of each result.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   type?: string,
>   name?: string,
>   url: string,
>   content?: string,
>   favicon?: string | null,
>   publishedAt?: string
> }[]
> ```

***

### structured

`search.structured`

Search the web and return JSON shaped by your JSON Schema, optionally with sources ($0.006; deep $0.055).

**Risk:** `read`

```ts theme={null}
await corsair.linkup.api.search.structured({ q: 'Population of Oslo', schema: { type: 'object', properties: { city: { type: 'string' }, population: { type: 'number' } } }, includeSources: true });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `q` | `string` | Yes | — |
| `schema` | `Record<string, any>` | Yes | JSON Schema (type: object) for the data to return. |
| `depth` | `flash \| fast \| standard \| deep` | No | flash, fast and standard cost the same and get slower and broader in that order; deep runs several searches and costs 10x. Default fast. |
| `includeSources` | `boolean` | No | Also return the sources the data came from. |
| `fromDate` | `string` | No | Only sources published on or after this date (YYYY-MM-DD). |
| `toDate` | `string` | No | Only sources published on or before this date (YYYY-MM-DD). |
| `includeDomains` | `string[]` | No | Only search these domains. |
| `excludeDomains` | `string[]` | No | Never return these domains. |

`POST /v1/search` with outputType structured. The schema is sent as a JSON string.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `any` | Yes | — |
| `sources` | `object[]` | No | — |

> [accordion] sources full type
>
> ```ts theme={null}
> {
>   name?: string,
>   url: string,
>   snippet?: string,
>   favicon?: string | null,
>   publishedAt?: string
> }[]
> ```

***

## Tasks

### create

`tasks.create`

Queue up to 100 search, fetch or research calls to run in the background, each billed like the direct call. Poll tasks.get.

**Risk:** `destructive`

```ts theme={null}
await corsair.linkup.api.tasks.create({ tasks: [{ type: 'fetch', input: { url: 'https://example.com' } }, { type: 'search', input: { q: 'Oslo weather', depth: 'fast', outputType: 'searchResults' } }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `tasks` | `object[]` | Yes | — |

`POST /v1/tasks` with an array of up to 100 search, fetch or research inputs.

> [accordion] tasks full type
>
> ```ts theme={null}
> (
>   {
>     type: search,
>     input: {
>       q: string,
>       depth: flash | fast | standard | deep,
>       outputType: searchResults | sourcedAnswer | structured
>     }
>   } | {
>     type: fetch,
>     input: {
>       url: string
>     }
>   } | {
>     type: research,
>     input: {
>       q: string,
>       outputType: sourcedAnswer | structured
>     }
>   }
> )[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tasks` | `object[]` | Yes | — |
| `meta` | `object` | No | — |
| `quota` | `object` | No | — |

> [accordion] tasks full type
>
> ```ts theme={null}
> {
>   id: string,
>   type?: string,
>   status: string,
>   createdAt?: string,
>   updatedAt?: string,
>   error?: string | null,
>   input?: Record<string, any>,
>   output?: any
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   page?: number,
>   pageSize?: number,
>   total?: number,
>   totalPages?: number
> }
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
>   inFlight?: number,
>   limit?: number
> }
> ```

***

### get

`tasks.get`

Get one background task with its status and output.

**Risk:** `read`

```ts theme={null}
await corsair.linkup.api.tasks.get({ id: '74eb77e1-4eb7-4429-843b-86d61b504791' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

`GET /v1/tasks/{id}`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `task` | `object` | Yes | — |

> [accordion] task full type
>
> ```ts theme={null}
> {
>   id: string,
>   type?: string,
>   status: string,
>   createdAt?: string,
>   updatedAt?: string,
>   error?: string | null,
>   input?: Record<string, any>,
>   output?: any
> }
> ```

***

### list

`tasks.list`

List background tasks, filtered by type and status, paged, with the in-flight quota.

**Risk:** `read`

```ts theme={null}
await corsair.linkup.api.tasks.list({ type: ['research'], status: ['completed'] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `(search \| fetch \| research)[]` | No | — |
| `status` | `(pending \| processing \| completed \| failed)[]` | No | — |
| `page` | `number` | No | — |
| `pageSize` | `number` | No | — |
| `sortBy` | `createdAt \| updatedAt` | No | — |
| `sortDirection` | `asc \| desc` | No | — |

`GET /v1/tasks`, filtered by type and status, paged.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tasks` | `object[]` | Yes | — |
| `meta` | `object` | No | — |
| `quota` | `object` | No | — |

> [accordion] tasks full type
>
> ```ts theme={null}
> {
>   id: string,
>   type?: string,
>   status: string,
>   createdAt?: string,
>   updatedAt?: string,
>   error?: string | null,
>   input?: Record<string, any>,
>   output?: any
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   page?: number,
>   pageSize?: number,
>   total?: number,
>   totalPages?: number
> }
> ```

> [accordion] quota full type
>
> ```ts theme={null}
> {
>   inFlight?: number,
>   limit?: number
> }
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.