> ## 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.

# Context.dev API reference

> API reference for the Context.dev plugin in Corsair: every `contextdev.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).

## Account

### usage

`account.usage`

Get the credit balance, current-period usage, and next refill

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.account.usage({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `credits_remaining` | `number` | Yes | — |
| `period` | `object \| null` | Yes | — |
| `next_refill` | `object \| null` | Yes | — |
| `auto_topup` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] period full type
>
> ```ts theme={null}
> {
>   start: string,
>   credits_used: number
> } | null
> ```

> [accordion] next\_refill full type
>
> ```ts theme={null}
> {
>   at: string,
>   credits: number
> } | null
> ```

> [accordion] auto\_topup full type
>
> ```ts theme={null}
> {
>   enabled: boolean,
>   credits_used_this_period: number,
>   monthly_budget_credits: number | null
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

## Brand

### fonts

`brand.fonts`

List the fonts a website uses and how much of the page each covers

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.brand.fonts({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `domain` | `string` | No | — |
| `directUrl` | `string` | No | — |
| `maxAgeMs` | `number \| null` | No | — |
| `timeoutOpts` | `object` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `finalDOMState` | `loaded \| still-loading` | No | — |
| `status` | `string` | Yes | — |
| `domain` | `string` | Yes | — |
| `fonts` | `object[]` | Yes | — |
| `fontLinks` | `object` | No | — |
| `code` | `number` | Yes | — |
| `cache_metadata` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] fonts full type
>
> ```ts theme={null}
> {
>   font: string,
>   uses: string[],
>   fallbacks: string[],
>   num_elements: number,
>   num_words: number,
>   percent_words: number,
>   percent_elements: number
> }[]
> ```

> [accordion] fontLinks full type
>
> ```ts theme={null}
> Record<string, {
>   type: google | custom,
>   files: Record<string, string>,
>   category?: string,
>   displayName?: string
> }>
> ```

> [accordion] cache\_metadata full type
>
> ```ts theme={null}
> {
>   status: hit | miss | zdr,
>   age_ms: number
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

### naics

`brand.naics`

Classify a brand or business description into NAICS codes

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.brand.naics({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `input` | `string` | Yes | Brand domain, title, or a description of the business |
| `minResults` | `number` | No | — |
| `maxResults` | `number` | No | — |
| `timeoutOpts` | `object` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `partial` | `boolean` | No | — |
| `status` | `string` | No | — |
| `domain` | `string` | No | — |
| `type` | `string` | No | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |
| `codes` | `object[]` | No | — |

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

> [accordion] codes full type
>
> ```ts theme={null}
> {
>   code: string,
>   name: string,
>   confidence: high | medium | low
> }[]
> ```

***

### prefetch

`brand.prefetch`

Queue brand or styleguide data so a later lookup returns sooner

**Risk:** `write`

```ts theme={null}
await corsair.contextdev.api.brand.prefetch({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `brand \| styleguide` | Yes | — |
| `identifier` | `object` | Yes | — |
| `timeoutOpts` | `object` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] identifier full type
>
> ```ts theme={null}
> {
>   domain: string
> } | {
>   email: string
> }
> ```

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `status` | `string` | No | — |
| `message` | `string` | No | — |
| `type` | `brand \| styleguide` | No | — |
| `domain` | `string` | No | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

### retrieve

`brand.retrieve`

Get a brand profile (logos, colors, socials, address, industry) by domain, name, email, ticker, URL, or card transaction

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.brand.retrieve({});
```

**Input:** `object`

> [accordion] Input full type
>
> ```ts theme={null}
> {
>   type: by_domain,
>   domain: string,
>   force_language?: string | null,
>   maxSpeed?: boolean,
>   maxAgeMs?: number,
>   timeoutOpts?: {
>     milliseconds: number,
>     behavior?: fail | return-partial
>   },
>   tags?: string[]
> } | {
>   type: by_name,
>   name: string,
>   country_gl?: string,
>   force_language?: string | null,
>   maxSpeed?: boolean,
>   maxAgeMs?: number,
>   timeoutOpts?: {
>     milliseconds: number,
>     behavior?: fail | return-partial
>   },
>   tags?: string[]
> } | {
>   type: by_email,
>   email: string,
>   force_language?: string | null,
>   maxSpeed?: boolean,
>   maxAgeMs?: number,
>   timeoutOpts?: {
>     milliseconds: number,
>     behavior?: fail | return-partial
>   },
>   tags?: string[]
> } | {
>   type: by_ticker,
>   ticker: string,
>   ticker_exchange?: string,
>   force_language?: string | null,
>   maxSpeed?: boolean,
>   maxAgeMs?: number,
>   timeoutOpts?: {
>     milliseconds: number,
>     behavior?: fail | return-partial
>   },
>   tags?: string[]
> } | {
>   type: by_direct_url,
>   direct_url: string,
>   timeoutOpts?: {
>     milliseconds: number,
>     behavior?: fail | return-partial
>   },
>   tags?: string[]
> } | {
>   type: by_transaction,
>   transaction_info: string,
>   country_gl?: string,
>   city?: string,
>   mcc?: string | number,
>   phone?: string | number,
>   high_confidence_only?: boolean,
>   force_language?: string | null,
>   maxSpeed?: boolean,
>   maxAgeMs?: number,
>   timeoutOpts?: {
>     milliseconds: number,
>     behavior?: fail | return-partial
>   },
>   tags?: string[]
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `partial` | `boolean` | No | — |
| `status` | `string` | Yes | — |
| `brand` | `object` | Yes | — |
| `code` | `number` | Yes | — |
| `cache_metadata` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] brand full type
>
> ```ts theme={null}
> {
>   domain?: string,
>   title?: string,
>   description?: string,
>   slogan?: string,
>   colors?: {
>     hex?: string,
>     name?: string,
>     source?: site | logo
>   }[],
>   logos?: {
>     url?: string,
>     mode?: light | dark | has_opaque_background,
>     colors?: {
>       hex?: string,
>       name?: string
>     }[],
>     resolution?: {
>       width?: number,
>       height?: number,
>       aspect_ratio?: number
>     },
>     type?: icon | logo
>   }[],
>   backdrops?: {
>     url?: string,
>     colors?: {
>       hex?: string,
>       name?: string
>     }[],
>     resolution?: {
>       width?: number,
>       height?: number,
>       aspect_ratio?: number
>     }
>   }[],
>   socials?: {
>     type?: string,
>     url?: string
>   }[],
>   address?: {
>     street?: string,
>     city?: string,
>     country?: string,
>     country_code?: string,
>     state_province?: string,
>     state_code?: string,
>     postal_code?: string
>   },
>   stock?: {
>     ticker?: string,
>     exchange?: string
>   },
>   employees?: {
>     range?: string,
>     exact?: number
>   },
>   is_nsfw?: boolean,
>   email?: string,
>   phone?: string,
>   industries?: {
>     eic?: {
>       industry: string,
>       subindustry: string
>     }[]
>   },
>   links?: {
>     careers?: string | null,
>     privacy?: string | null,
>     terms?: string | null,
>     contact?: string | null,
>     blog?: string | null,
>     pricing?: string | null
>   },
>   primary_language?: string | null
> }
> ```

> [accordion] cache\_metadata full type
>
> ```ts theme={null}
> {
>   status: hit | miss | zdr,
>   age_ms: number
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

### search

`brand.search`

Find up to 10 brands by name or domain

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.brand.search({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | — |
| `autocomplete` | `boolean` | No | — |
| `queryBy` | `(name \| domain)[]` | No | — |
| `typoTolerance` | `number` | No | — |
| `tags` | `string[]` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   domain: string,
>   name: string,
>   logo: string
> }[]
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

### sic

`brand.sic`

Classify a brand or business description into SIC codes

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.brand.sic({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `input` | `string` | Yes | Brand domain, title, or a description of the business |
| `minResults` | `number` | No | — |
| `maxResults` | `number` | No | — |
| `timeoutOpts` | `object` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |
| `type` | `original_sic \| latest_sec` | No | — |

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `partial` | `boolean` | No | — |
| `status` | `string` | No | — |
| `domain` | `string` | No | — |
| `type` | `string` | No | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |
| `classification` | `original_sic \| latest_sec` | No | — |
| `codes` | `object[]` | No | — |

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

> [accordion] codes full type
>
> ```ts theme={null}
> {
>   code: string,
>   name: string,
>   confidence: high | medium | low,
>   majorGroup?: string,
>   majorGroupName?: string,
>   office?: string
> }[]
> ```

***

### styleguide

`brand.styleguide`

Extract a website's colors, typography, spacing, shadows, and button styles

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.brand.styleguide({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `domain` | `string` | No | — |
| `directUrl` | `string` | No | — |
| `maxAgeMs` | `number \| null` | No | — |
| `timeoutOpts` | `object` | No | — |
| `colorScheme` | `light \| dark` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `finalDOMState` | `loaded \| still-loading` | No | — |
| `status` | `string` | No | — |
| `domain` | `string` | No | — |
| `styleguide` | `object` | No | — |
| `code` | `number` | No | — |
| `cache_metadata` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] styleguide full type
>
> ```ts theme={null}
> {
>   mode: light | dark,
>   colors: {
>     accent: string,
>     background: string,
>     text: string
>   },
>   typography: {
>     headings: {
>       h1?: {
>         fontFamily: string,
>         fontFallbacks: string[],
>         fontSize: string,
>         fontWeight: number,
>         lineHeight: string,
>         letterSpacing: string
>       },
>       h2?: {
>         fontFamily: string,
>         fontFallbacks: string[],
>         fontSize: string,
>         fontWeight: number,
>         lineHeight: string,
>         letterSpacing: string
>       },
>       h3?: {
>         fontFamily: string,
>         fontFallbacks: string[],
>         fontSize: string,
>         fontWeight: number,
>         lineHeight: string,
>         letterSpacing: string
>       },
>       h4?: {
>         fontFamily: string,
>         fontFallbacks: string[],
>         fontSize: string,
>         fontWeight: number,
>         lineHeight: string,
>         letterSpacing: string
>       }
>     },
>     p?: {
>       fontFamily: string,
>       fontFallbacks: string[],
>       fontSize: string,
>       fontWeight: number,
>       lineHeight: string,
>       letterSpacing: string
>     }
>   },
>   elementSpacing: {
>     xs: string,
>     sm: string,
>     md: string,
>     lg: string,
>     xl: string
>   },
>   shadows: {
>     sm: string,
>     md: string,
>     lg: string,
>     xl: string,
>     inner: string
>   },
>   fontLinks: Record<string, {
>     type: google | custom,
>     files: Record<string, string>,
>     category?: string,
>     displayName?: string
>   }>,
>   components: {
>     button: {
>       primary?: {
>         backgroundColor: string,
>         color: string,
>         borderColor: string,
>         borderRadius: string,
>         borderWidth: string,
>         borderStyle: string,
>         padding: string,
>         minWidth: string,
>         minHeight: string,
>         fontSize: string,
>         fontWeight: number,
>         fontFamily?: string,
>         fontFallbacks?: string[],
>         textDecoration: string,
>         textDecorationColor?: string,
>         boxShadow: string,
>         css: string
>       },
>       secondary?: {
>         backgroundColor: string,
>         color: string,
>         borderColor: string,
>         borderRadius: string,
>         borderWidth: string,
>         borderStyle: string,
>         padding: string,
>         minWidth: string,
>         minHeight: string,
>         fontSize: string,
>         fontWeight: number,
>         fontFamily?: string,
>         fontFallbacks?: string[],
>         textDecoration: string,
>         textDecorationColor?: string,
>         boxShadow: string,
>         css: string
>       },
>       link?: {
>         backgroundColor: string,
>         color: string,
>         borderColor: string,
>         borderRadius: string,
>         borderWidth: string,
>         borderStyle: string,
>         padding: string,
>         minWidth: string,
>         minHeight: string,
>         fontSize: string,
>         fontWeight: number,
>         fontFamily?: string,
>         fontFallbacks?: string[],
>         textDecoration: string,
>         textDecorationColor?: string,
>         boxShadow: string,
>         css: string
>       }
>     },
>     card?: {
>       backgroundColor: string,
>       borderColor: string,
>       borderRadius: string,
>       borderWidth: string,
>       borderStyle: string,
>       padding: string,
>       boxShadow: string,
>       textColor: string,
>       css: string
>     }
>   }
> }
> ```

> [accordion] cache\_metadata full type
>
> ```ts theme={null}
> {
>   status: hit | miss | zdr,
>   age_ms: number
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

## News

### search

`news.search`

Search company news by name, domain, ticker, or ISIN, paginated by cursor

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.news.search({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `searchBy` | `object` | Yes | — |
| `filterBy` | `object` | No | — |
| `sortBy` | `object` | No | — |
| `limit` | `number` | No | — |
| `cursor` | `string \| null` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] searchBy full type
>
> ```ts theme={null}
> {
>   type: entity,
>   entity: {
>     type: name,
>     name: string
>   } | {
>     type: domain,
>     domain: string
>   } | {
>     type: ticker,
>     ticker: string,
>     exchange?: string
>   } | {
>     type: isin,
>     isin: string
>   }
> }
> ```

> [accordion] filterBy full type
>
> ```ts theme={null}
> {
>   sourceDomain?: string[],
>   sourceCountry?: string[],
>   articleLanguage?: string[],
>   articleType?: (editorial | press_release | regulatory_filing | advisory)[],
>   date?: {
>     from?: number,
>     to?: number
>   }
> }
> ```

> [accordion] sortBy full type
>
> ```ts theme={null}
> {
>   type: relevance | newest
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[]` | Yes | — |
| `has_more` | `boolean` | Yes | — |
| `next_cursor` | `string \| null` | Yes | — |
| `meta` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   id: string,
>   story_id: string,
>   url: string,
>   title: string,
>   description: string | null,
>   language: string | null,
>   authors: string[],
>   image_url: string | null,
>   published_at: string | null,
>   type: editorial | press_release | regulatory_filing | advisory,
>   source: {
>     name: string,
>     domain: string,
>     direct: boolean
>   },
>   match: {
>     level: primary | secondary,
>     confidence: number | null
>   }
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   count: number
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

## People

### enrich

`people.enrich`

Find a person from an email, profile URLs, or name and return their profile with a match score

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.people.enrich({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `social_urls` | `string[]` | No | — |
| `name` | `object` | No | — |
| `email` | `string` | No | — |
| `company` | `object` | No | — |
| `education` | `object[]` | No | — |
| `location` | `object` | No | — |
| `timeoutOpts` | `object` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] name full type
>
> ```ts theme={null}
> {
>   first?: string,
>   last?: string
> }
> ```

> [accordion] company full type
>
> ```ts theme={null}
> {
>   name?: string,
>   domain?: string
> }
> ```

> [accordion] education full type
>
> ```ts theme={null}
> {
>   institution?: {
>     name?: string,
>     domain?: string
>   },
>   degree?: string,
>   field_of_study?: string,
>   graduation_year?: number
> }[]
> ```

> [accordion] location full type
>
> ```ts theme={null}
> {
>   city?: string,
>   region?: string,
>   country?: string
> }
> ```

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `partial` | `boolean` | No | — |
| `match` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] match full type
>
> ```ts theme={null}
> {
>   status: candidate,
>   score: number,
>   person: {
>     name?: {
>       full?: string,
>       first?: string,
>       last?: string
>     },
>     email?: string,
>     avatar_url?: string,
>     bio?: string,
>     location?: {
>       display?: string,
>       city?: string,
>       region?: string,
>       country?: string,
>       country_code?: string
>     },
>     social_urls: string[],
>     website_urls: string[],
>     current_role?: {
>       title: string,
>       organization: {
>         name: string,
>         domain?: string
>       },
>       location?: string,
>       description?: string,
>       start_date?: {
>         year: number,
>         month?: number,
>         day?: number
>       },
>       end_date?: {
>         year: number,
>         month?: number,
>         day?: number
>       },
>       is_current?: boolean
>     },
>     current_role_status: present | none | unknown,
>     experience: {
>       title: string,
>       organization: {
>         name: string,
>         domain?: string
>       },
>       location?: string,
>       description?: string,
>       start_date?: {
>         year: number,
>         month?: number,
>         day?: number
>       },
>       end_date?: {
>         year: number,
>         month?: number,
>         day?: number
>       },
>       is_current?: boolean
>     }[],
>     education: {
>       institution: {
>         name: string,
>         domain?: string
>       },
>       degree?: string,
>       field_of_study?: string,
>       description?: string,
>       start_date?: {
>         year: number,
>         month?: number,
>         day?: number
>       },
>       end_date?: {
>         year: number,
>         month?: number,
>         day?: number
>       }
>     }[],
>     skills: string[],
>     last_updated?: string,
>     checked_at?: string
>   }
> } | {
>   status: not_found,
>   score: null,
>   person: null
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

## Web

### answers

`web.answers`

Research a task on the web and return a sourced answer in a requested JSON shape

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.web.answers({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `task` | `string` | Yes | — |
| `mode` | `fast \| ultra` | No | — |
| `json_format` | `Record<string, any>` | No | — |
| `timeoutOpts` | `object` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `partial` | `boolean` | No | — |
| `json_content` | `Record<string, any>` | Yes | — |
| `sources` | `string[]` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | No | — |

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

### crawl

`web.crawl`

Crawl a website (up to 500 pages) and return each page as Markdown

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.web.crawl({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | — |
| `maxPages` | `number` | No | — |
| `urlRegex` | `string` | No | — |
| `includeLinks` | `boolean` | No | — |
| `includeImages` | `boolean` | No | — |
| `shortenBase64Images` | `boolean` | No | — |
| `useMainContentOnly` | `boolean` | No | — |
| `pdf` | `object` | No | — |
| `includeSelectors` | `string[] \| null` | No | — |
| `excludeSelectors` | `string[] \| null` | No | — |
| `country` | `string` | No | — |
| `maxDepth` | `number` | No | — |
| `followSubdomains` | `boolean` | No | — |
| `includeFrames` | `boolean` | No | — |
| `maxAgeMs` | `number \| null` | No | — |
| `waitForMs` | `number \| null` | No | — |
| `settleAnimations` | `boolean` | No | — |
| `stopAfterMs` | `number` | No | — |
| `timeoutOpts` | `object` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] pdf full type
>
> ```ts theme={null}
> {
>   shouldParse?: boolean,
>   start?: number,
>   end?: number,
>   ocr?: boolean
> }
> ```

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `partial` | `boolean` | No | — |
| `results` | `object[]` | Yes | — |
| `metadata` | `object` | Yes | — |
| `cache_metadata` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   markdown: string,
>   metadata: {
>     title: string,
>     description?: string,
>     language?: string,
>     keywords?: string[],
>     canonicalUrl?: string,
>     author?: string,
>     siteName?: string,
>     image?: string,
>     favicon?: string,
>     publishedTime?: string,
>     modifiedTime?: string,
>     robots?: string,
>     openGraph?: Record<string, string | string[]>,
>     twitter?: Record<string, string | string[]>,
>     alternates?: {
>       href: string,
>       hreflang?: string,
>       type?: string,
>       title?: string
>     }[],
>     headings?: {
>       level: number,
>       text: string
>     }[],
>     jsonLd?: Record<string, any>[],
>     additionalMeta?: Record<string, string | string[]>,
>     sourceUrl: string,
>     finalUrl: string,
>     url: string,
>     crawlDepth: number,
>     statusCode: number,
>     success: boolean
>   }
> }[]
> ```

> [accordion] metadata full type
>
> ```ts theme={null}
> {
>   numUrls: number,
>   maxCrawlDepth: number,
>   numSucceeded: number,
>   numFailed: number,
>   numSkipped: number
> }
> ```

> [accordion] cache\_metadata full type
>
> ```ts theme={null}
> {
>   status: hit | miss | zdr,
>   age_ms: number
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

### extract

`web.extract`

Extract structured data from a website using a JSON Schema

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.web.extract({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | — |
| `schema` | `Record<string, any>` | Yes | — |
| `instructions` | `string` | No | — |
| `factCheck` | `boolean` | No | — |
| `maxPages` | `number` | No | — |
| `pdf` | `object` | No | — |
| `actions` | `object[] \| null` | No | — |
| `maxDepth` | `number` | No | — |
| `followSubdomains` | `boolean` | No | — |
| `includeFrames` | `boolean` | No | — |
| `maxAgeMs` | `number \| null` | No | — |
| `waitForMs` | `number \| null` | No | — |
| `settleAnimations` | `boolean` | No | — |
| `stopAfterMs` | `number` | No | — |
| `timeoutOpts` | `object` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] pdf full type
>
> ```ts theme={null}
> {
>   shouldParse?: boolean,
>   start?: number,
>   end?: number
> }
> ```

> [accordion] actions full type
>
> ```ts theme={null}
> (
>   {
>     do: wait,
>     timeMs: number
>   } | {
>     do: perform,
>     action: string
>   } | {
>     do: scroll,
>     direction?: up | down | left | right,
>     amount?: number | viewport | max,
>     container?: string,
>     maxScrolls?: number
>   }
> )[] | null
> ```

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `partial` | `boolean` | No | — |
| `status` | `string` | Yes | — |
| `url` | `string` | Yes | — |
| `urls_analyzed` | `string[]` | Yes | — |
| `data` | `Record<string, any>` | Yes | — |
| `metadata` | `object` | Yes | — |
| `cache_metadata` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] metadata full type
>
> ```ts theme={null}
> {
>   numUrls: number,
>   maxCrawlDepth: number,
>   numSucceeded: number,
>   numFailed: number,
>   numSkipped: number,
>   numBlocked: number,
>   actionsApplied?: {
>     instruction: string,
>     status: applied | failed | skipped,
>     method?: string,
>     targetDescription?: string,
>     completionEvidence?: string,
>     error?: string,
>     durationMs?: number
>   }[]
> }
> ```

> [accordion] cache\_metadata full type
>
> ```ts theme={null}
> {
>   status: hit | miss | zdr,
>   age_ms: number
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

### scrape

`web.scrape`

Scrape a URL as HTML, Markdown, screenshot, images, highlights, or schema-driven JSON

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.web.scrape({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | — |
| `formats` | `object` | Yes | — |
| `markdownParams` | `object` | No | — |
| `screenshotParams` | `object` | No | — |
| `imageParams` | `object` | No | — |
| `highlightsParams` | `object` | No | — |
| `jsonParams` | `object` | No | — |
| `parseParams` | `object` | No | — |
| `productParams` | `object` | No | — |
| `sharedParams` | `object` | No | — |
| `maxAgeMs` | `number` | No | — |
| `timeoutOpts` | `object` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] formats full type
>
> ```ts theme={null}
> {
>   html?: boolean,
>   markdown?: boolean,
>   screenshot?: boolean,
>   images?: boolean,
>   bytes?: boolean,
>   parse?: boolean,
>   highlights?: boolean,
>   json?: boolean,
>   product?: boolean
> }
> ```

> [accordion] markdownParams full type
>
> ```ts theme={null}
> {
>   includeLinks?: boolean,
>   includeImages?: boolean,
>   inlineImages?: placeholder | preserve
> }
> ```

> [accordion] screenshotParams full type
>
> ```ts theme={null}
> {
>   area?: viewport | fullPage | {
>     selector: string
>   } | {
>     x: number,
>     y: number,
>     width: number,
>     height: number
>   },
>   format?: png | jpeg | webp
> }
> ```

> [accordion] imageParams full type
>
> ```ts theme={null}
> {
>   enrich?: (dimensions | classification | file)[],
>   dedupe?: none | visual
> }
> ```

> [accordion] highlightsParams full type
>
> ```ts theme={null}
> {
>   query: string,
>   maxCharacters?: number
> }
> ```

> [accordion] jsonParams full type
>
> ```ts theme={null}
> {
>   schema: Record<string, any>,
>   instructions?: string
> }
> ```

> [accordion] parseParams full type
>
> ```ts theme={null}
> {
>   type?: custom,
>   rules: Record<string, string | {
>     selector: string,
>     type?: item | list,
>     output?: string | (recursive)
>   }>
> } | {
>   type: prebuilt,
>   parser: google-maps | google-play | google-play-reviews | app-store | app-store-reviews | emails | phone-numbers | links
> }
> ```

> [accordion] productParams full type
>
> ```ts theme={null}
> {
>   dedupeImages?: boolean
> }
> ```

> [accordion] sharedParams full type
>
> ```ts theme={null}
> {
>   country?: string,
>   headers?: Record<string, string>,
>   viewport?: {
>     width?: number,
>     height?: number
>   },
>   theme?: light | dark,
>   dismissCookies?: boolean,
>   dismissPopups?: boolean,
>   actions?: (
>     {
>       type: perform,
>       action: string
>     } | {
>       type: scroll,
>       direction?: down | up | left | right,
>       amount?: number | viewport | max,
>       selector?: string,
>       maxScrolls?: number
>     } | {
>       type: wait,
>       milliseconds: number
>     } | {
>       type: waitFor,
>       selector: string
>     }
>   )[],
>   waitFor?: number | string,
>   settleAnimations?: boolean,
>   mainContentOnly?: boolean,
>   includeSelectors?: string[],
>   excludeSelectors?: string[],
>   includeFrames?: boolean,
>   parsers?: {
>     pdf?: {
>       startPage?: number,
>       endPage?: number,
>       ocr?: off | auto
>     }
>   },
>   profile?: {
>     type: existing,
>     profileId: string
>   } | {
>     type: new,
>     identifier: string,
>     password: string
>   }
> }
> ```

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | — |
| `html` | `object` | Yes | — |
| `markdown` | `object` | Yes | — |
| `screenshot` | `object` | Yes | — |
| `images` | `object` | Yes | — |
| `bytes` | `object` | Yes | — |
| `parsed` | `object` | Yes | — |
| `highlights` | `object` | Yes | — |
| `json` | `object` | Yes | — |
| `product` | `object` | Yes | — |
| `profile` | `object \| null` | Yes | — |
| `isPartial` | `true` | No | — |
| `metadata` | `object` | Yes | — |
| `cache_metadata` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] html full type
>
> ```ts theme={null}
> {
>   requested: boolean,
>   success: boolean | null,
>   data: string | null,
>   error_code?: string,
>   message?: string
> }
> ```

> [accordion] markdown full type
>
> ```ts theme={null}
> {
>   requested: boolean,
>   success: boolean | null,
>   data: string | null,
>   error_code?: string,
>   message?: string
> }
> ```

> [accordion] screenshot full type
>
> ```ts theme={null}
> {
>   requested: boolean,
>   success: boolean | null,
>   data: string | null,
>   error_code?: string,
>   message?: string
> }
> ```

> [accordion] images full type
>
> ```ts theme={null}
> {
>   requested: boolean,
>   success: boolean | null,
>   data: {
>     url: string,
>     alt: string | null,
>     width?: number,
>     height?: number,
>     classification?: photography | illustration | logo | wordmark | icon | pattern | graphic | other,
>     fileUrl?: string
>   }[] | null,
>   error_code?: string,
>   message?: string
> }
> ```

> [accordion] bytes full type
>
> ```ts theme={null}
> {
>   requested: boolean,
>   success: boolean | null,
>   data: {
>     contentType: string,
>     base64: string
>   } | null,
>   error_code?: string,
>   message?: string
> }
> ```

> [accordion] parsed full type
>
> ```ts theme={null}
> {
>   requested: boolean,
>   success: boolean | null,
>   data: Record<string, any> | null,
>   error_code?: string,
>   message?: string,
>   type: google-maps | google-play | google-play-reviews | app-store | app-store-reviews | emails | phone-numbers | links | custom
> }
> ```

> [accordion] highlights full type
>
> ```ts theme={null}
> {
>   requested: boolean,
>   success: boolean | null,
>   data: string[] | null,
>   error_code?: string,
>   message?: string
> }
> ```

> [accordion] json full type
>
> ```ts theme={null}
> {
>   requested: boolean,
>   success: boolean | null,
>   data: Record<string, any> | null,
>   error_code?: string,
>   message?: string,
>   isTruncated?: true
> }
> ```

> [accordion] product full type
>
> ```ts theme={null}
> {
>   requested: boolean,
>   success: boolean | null,
>   data: {
>     isProductPage: boolean,
>     product: {
>       name: string,
>       description: string | null,
>       brand: string | null,
>       sku: string | null,
>       price: number | null,
>       regularPrice: number | null,
>       currency: string | null,
>       availability: in_stock | out_of_stock | limited_availability | preorder | backorder | made_to_order | discontinued | null,
>       category: string | null,
>       imageUrl: string | null,
>       images: string[],
>       dimensions: string[],
>       features: string[],
>       targetAudience: string[],
>       tags: string[],
>       variants: {
>         sku: string | null,
>         attributes: Record<string, string>,
>         url: string | null,
>         images: string[]
>       }[]
>     } | null
>   } | null,
>   error_code?: string,
>   message?: string
> }
> ```

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   id: string
> } | null
> ```

> [accordion] metadata full type
>
> ```ts theme={null}
> {
>   title?: string,
>   description?: string,
>   language?: string,
>   keywords?: string[],
>   canonicalUrl?: string,
>   author?: string,
>   siteName?: string,
>   image?: string,
>   favicon?: string,
>   publishedTime?: string,
>   modifiedTime?: string,
>   robots?: string,
>   openGraph?: Record<string, string | string[]>,
>   twitter?: Record<string, string | string[]>,
>   alternates?: {
>     href: string,
>     hreflang?: string,
>     type?: string,
>     title?: string
>   }[],
>   headings?: {
>     level: number,
>     text: string
>   }[],
>   jsonLd?: Record<string, any>[],
>   additionalMeta?: Record<string, string | string[]>
> }
> ```

> [accordion] cache\_metadata full type
>
> ```ts theme={null}
> {
>   status: hit | miss | zdr,
>   age_ms: number
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

### search

`web.search`

Search the web, optionally with page Markdown or highlights per result

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.web.search({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | — |
| `numResults` | `number` | No | — |
| `includeDomains` | `string[]` | No | — |
| `excludeDomains` | `string[]` | No | — |
| `freshness` | `last_24_hours \| last_week \| last_month \| last_year` | No | — |
| `country` | `string` | No | — |
| `queryFanout` | `boolean` | No | — |
| `markdownOptions` | `object \| null` | No | — |
| `highlightsOptions` | `object \| null` | No | — |
| `descriptionMaxCharacters` | `number \| null` | No | — |
| `timeoutOpts` | `object` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] markdownOptions full type
>
> ```ts theme={null}
> {
>   enabled?: boolean,
>   includeLinks?: boolean,
>   includeImages?: boolean,
>   shortenBase64Images?: boolean,
>   useMainContentOnly?: boolean,
>   pdf?: {
>     shouldParse?: boolean,
>     start?: number,
>     end?: number
>   },
>   includeFrames?: boolean,
>   maxAgeMs?: number | null,
>   waitForMs?: number | null,
>   timeoutOpts?: {
>     milliseconds: number,
>     behavior?: fail | return-partial
>   }
> } | null
> ```

> [accordion] highlightsOptions full type
>
> ```ts theme={null}
> {
>   enabled?: boolean,
>   maxCharacters?: number
> } | null
> ```

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `partial` | `boolean` | No | — |
| `query` | `string` | Yes | — |
| `results` | `object[]` | Yes | — |
| `cache_metadata` | `object` | Yes | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   url: string,
>   title: string,
>   description: string,
>   relevance: high | medium | low,
>   markdown: {
>     finalDOMState?: loaded | still-loading,
>     markdown: string | null,
>     code: SUCCESS | NOT_REQUESTED | TIMEOUT | CONTENT_TOO_LARGE | WEBSITE_ACCESS_ERROR | WEBSITE_BLOCKED | ERROR
>   },
>   highlights: {
>     highlights: string[] | null,
>     code: SUCCESS | NOT_REQUESTED | TIMEOUT | CONTENT_TOO_LARGE | WEBSITE_ACCESS_ERROR | WEBSITE_BLOCKED | ERROR
>   }
> }[]
> ```

> [accordion] cache\_metadata full type
>
> ```ts theme={null}
> {
>   status: hit | miss | zdr,
>   age_ms: number
> }
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***

### urls

`web.urls`

Map a domain's URLs with titles and descriptions

**Risk:** `read`

```ts theme={null}
await corsair.contextdev.api.web.urls({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `domain` | `string` | Yes | — |
| `headers` | `Record<string, string>` | No | — |
| `includeSubdomains` | `boolean` | No | — |
| `maxLinks` | `number` | No | — |
| `sitemapUrl` | `string` | No | — |
| `urlRegex` | `string` | No | — |
| `search` | `string` | No | — |
| `timeoutOpts` | `object` | No | — |
| `zdr` | `enabled \| disabled` | No | — |
| `tags` | `string[]` | No | — |

> [accordion] timeoutOpts full type
>
> ```ts theme={null}
> {
>   milliseconds: number,
>   behavior?: fail | return-partial
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | — |
| `domain` | `string` | Yes | — |
| `urls` | `object[]` | Yes | — |
| `partial` | `boolean` | No | — |
| `key_metadata` | `object` | No | — |
| `request_id` | `string` | Yes | — |

> [accordion] urls full type
>
> ```ts theme={null}
> {
>   url: string,
>   title?: string,
>   description?: string,
>   keywords?: string[],
>   language?: string
> }[]
> ```

> [accordion] key\_metadata full type
>
> ```ts theme={null}
> {
>   credits_consumed: number,
>   credits_remaining: number
> }
> ```

***


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