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

# API

> API reference for Octen: every `octen.api.*` operation with input and output types.

Every `octen.api.*` operation is listed below with parameter shapes and return types from the plugin Zod schemas.

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

## Answer

### create

`answer.create`

Decompose messages into sub-queries, search, and synthesize an answer

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.answer.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `model` | `openai/gpt-6.1-sol \| openai/gpt-6-astra \| openai/gpt-5.6-sol \| openai/gpt-5.6-terra \| openai/gpt-5.6-luna \| openai/gpt-5.4 \| anthropic/claude-fable-5.1 \| anthropic/claude-fable-5 \| anthropic/claude-opus-5.5 \| anthropic/claude-opus-5 \| anthropic/claude-opus-4.8 \| anthropic/claude-opus-4.6 \| anthropic/claude-sonnet-5.5 \| anthropic/claude-sonnet-5 \| anthropic/claude-sonnet-4.6 \| anthropic/claude-haiku-5.5 \| anthropic/claude-haiku-4.5 \| google/gemini-4-argon \| google/gemini-3.8-flash \| google/gemini-3.5-flash \| google/gemini-3.5-flash-lite \| google/gemini-3.1-pro-preview \| google/gemini-3.1-flash-lite \| google/gemini-3-flash-preview \| moonshotai/kimi-k3 \| moonshotai/kimi-k2.6 \| moonshotai/kimi-k2.5 \| minimax/minimax-m2.5 \| qwen/qwen3.6-plus \| deepseek/deepseek-v4-pro \| deepseek/deepseek-v4-flash-0731` | No | — |
| `messages` | `object[]` | Yes | — |
| `mode` | `queries_only \| queries_and_search \| full` | No | — |
| `max_queries` | `number` | No | — |
| `web_search_options` | `object` | No | — |

> **messages full type**
>
> ```ts theme={null}
> {
>   role: system | developer | user | assistant | tool
> }[]
> ```

> **web\_search\_options full type**
>
> ```ts theme={null}
> {
>   count?: number,
>   include_domains?: string[],
>   exclude_domains?: string[],
>   include_text?: string[],
>   exclude_text?: string[],
>   time_basis?: auto | published | crawled,
>   time_range?: day | week | month | year | d | w | m | y,
>   start_time?: string,
>   end_time?: string,
>   language?: ar | de | en | es | fr | hi | id | it | ja | ko | nl | pl | pt | ru | th | tr | vi | zh[],
>   highlight?: {
>     enable?: boolean,
>     max_tokens?: number
>   },
>   full_content?: {
>     enable?: boolean,
>     max_tokens?: number
>   },
>   format?: markdown | text,
>   safesearch?: off | strict,
>   include_images?: boolean
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `request_id` | `string` | Yes | — |
| `object` | `chat.completion` | Yes | — |
| `created` | `number` | Yes | — |
| `model` | `string` | Yes | — |
| `choices` | `object[]` | Yes | — |
| `queries` | `string[]` | No | — |
| `search_results` | `object[]` | No | — |
| `meta` | `object` | No | — |
| `warning` | `string` | No | — |

> **choices full type**
>
> ```ts theme={null}
> {
>   index?: number,
>   finish_reason?: stop | length | tool_calls | content_filter | error,
>   message?: {
>     role?: assistant,
>     content?: string | null
>   }
> }[]
> ```

> **search\_results full type**
>
> ```ts theme={null}
> {
>   query?: string,
>   results?: {
>     title?: string,
>     url?: string,
>     highlight?: string,
>     full_content?: string,
>     authors?: string,
>     time_published?: string,
>     time_last_crawled?: string,
>     favicon?: string,
>     cover_image?: {
>       url?: string,
>       description?: string
>     },
>     images?: {
>       url?: string,
>       description?: string
>     }[]
>   }[],
>   latency?: number
> }[]
> ```

> **meta full type**
>
> ```ts theme={null}
> {
>   usage?: {
>     num_search_queries: number,
>     prompt_tokens: number,
>     completion_tokens: number,
>     total_tokens: number
>   },
>   latency?: number
> }
> ```

***

## Broad Search

### post

`broadSearch.post`

Expand one query into sub-queries and search each of them

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.broadSearch.post({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | — |
| `max_queries` | `number` | No | — |
| `search_options` | `object` | No | — |

> **search\_options full type**
>
> ```ts theme={null}
> {
>   count?: number,
>   include_domains?: string[],
>   exclude_domains?: string[],
>   include_text?: string[],
>   exclude_text?: string[],
>   time_basis?: auto | published | crawled,
>   time_range?: day | week | month | year | d | w | m | y,
>   start_time?: string,
>   end_time?: string,
>   language?: ar | de | en | es | fr | hi | id | it | ja | ko | nl | pl | pt | ru | th | tr | vi | zh[],
>   highlight?: {
>     enable?: boolean,
>     max_tokens?: number
>   },
>   full_content?: {
>     enable?: boolean,
>     max_tokens?: number
>   },
>   format?: markdown | text,
>   safesearch?: off | strict,
>   include_images?: boolean
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | No | — |
| `queries` | `string[]` | No | — |
| `search_results` | `object[]` | No | — |

> **search\_results full type**
>
> ```ts theme={null}
> {
>   query?: string,
>   results?: {
>     title?: string,
>     url?: string,
>     highlight?: string,
>     full_content?: string,
>     authors?: string,
>     time_published?: string,
>     time_last_crawled?: string,
>     favicon?: string,
>     cover_image?: {
>       url?: string,
>       description?: string
>     },
>     images?: {
>       url?: string,
>       description?: string
>     }[]
>   }[],
>   latency?: number
> }[]
> ```

***

## Business Search

### post

`businessSearch.post`

Search business pages and return company and people cards

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.businessSearch.post({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | — |
| `count` | `number` | No | — |
| `include_domains` | `string[]` | No | — |
| `exclude_domains` | `string[]` | No | — |
| `time_basis` | `auto \| published \| crawled` | No | — |
| `time_range` | `day \| week \| month \| year \| d \| w \| m \| y` | No | — |
| `start_time` | `string` | No | — |
| `end_time` | `string` | No | — |
| `language` | `ar \| de \| en \| es \| fr \| hi \| id \| it \| ja \| ko \| nl \| pl \| pt \| ru \| th \| tr \| vi \| zh[]` | No | — |
| `highlight` | `object` | No | — |
| `full_content` | `object` | No | — |
| `entities` | `object` | No | — |

> **highlight full type**
>
> ```ts theme={null}
> {
>   enable?: boolean,
>   max_tokens?: number
> }
> ```

> **full\_content full type**
>
> ```ts theme={null}
> {
>   enable?: boolean,
>   max_tokens?: number
> }
> ```

> **entities full type**
>
> ```ts theme={null}
> {
>   enable?: boolean,
>   count?: number,
>   max_activities?: number,
>   max_news?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | No | — |
| `results` | `object[]` | No | — |
| `entities` | `object[]` | No | — |

> **results full type**
>
> ```ts theme={null}
> {
>   title?: string,
>   url?: string,
>   highlight?: string,
>   full_content?: string,
>   authors?: string,
>   time_published?: string,
>   time_last_crawled?: string,
>   favicon?: string,
>   cover_image?: {
>     url?: string,
>     description?: string
>   },
>   images?: {
>     url?: string,
>     description?: string
>   }[]
> }[]
> ```

> **entities full type**
>
> ```ts theme={null}
> {
>   type?: company | person,
>   name?: string
> }[]
> ```

***

## Embedding

### create

`embedding.create`

Create text embeddings with an Octen embedding model

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.embedding.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `input` | `string[]` | Yes | — |
| `model` | `octen-embedding-0.6b \| octen-embedding-4b \| octen-embedding-8b` | No | — |
| `dimension` | `number` | No | — |
| `input_type` | `query \| document` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | No | — |
| `model` | `string` | No | — |

> **results full type**
>
> ```ts theme={null}
> {
>   index?: number,
>   embedding?: number[]
> }[]
> ```

***

## Extract

### post

`extract.post`

Extract page content from up to 20 URLs

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.extract.post({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `urls` | `string[]` | Yes | — |
| `mode` | `standard \| advanced \| auto` | No | — |
| `query` | `string` | No | — |
| `max_age_seconds` | `number` | No | — |
| `format` | `markdown \| text` | No | — |
| `timeout` | `number` | No | — |
| `include_images` | `boolean` | No | — |
| `include_videos` | `boolean` | No | — |
| `include_audio` | `boolean` | No | — |
| `include_links` | `object` | No | — |

> **include\_links full type**
>
> ```ts theme={null}
> {
>   scope?: prefer_internal | prefer_external,
>   max_links?: number
> }
> ```

**Output**

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

> **results full type**
>
> ```ts theme={null}
> {
>   url?: string,
>   status?: success | failed,
>   resolved_mode?: standard | advanced,
>   title?: string | null,
>   full_content?: string | null,
>   highlights?: string[] | null,
>   time_published?: string | null,
>   time_last_crawled?: string,
>   page_structure?: {
>     primary?: Index Page | Content Page | No Main Content,
>     secondary?: string | null
>   } | null,
>   category?: {
>     primary?: string,
>     secondary?: string | null
>   } | null,
>   favicon?: string | null,
>   cover_image?: {
>     url?: string
>   } | null,
>   images?: {
>     url?: string
>   }[],
>   videos?: {
>     url?: string
>   }[],
>   audio?: {
>     url?: string
>   }[],
>   links?: {
>     url?: string,
>     anchor_text?: string,
>     is_external?: boolean
>   }[],
>   error_message?: string
> }[]
> ```

***

## Grounded Generation

### create

`groundedGeneration.create`

Queue a search-grounded image or video generation task

**Risk:** `write`

```ts theme={null}
await corsair.octen.api.groundedGeneration.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `modality` | `image \| video` | Yes | — |
| `prompt` | `string` | Yes | — |
| `model` | `google/gemini-3-pro-image \| google/gemini-3.1-flash-image \| minimax/hailuo-3` | No | — |
| `aspect_ratio` | `16:9 \| 1:1 \| 9:16` | No | — |
| `duration` | `number` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `request_id` | `string` | No | — |
| `generation_id` | `string` | Yes | — |
| `modality` | `image \| video` | Yes | — |
| `status` | `queued` | Yes | — |
| `created_at` | `number` | Yes | — |

***

### get

`groundedGeneration.get`

Get a grounded generation task and its output URL

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.groundedGeneration.get({});
```

**Input**

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

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `request_id` | `string` | No | — |
| `generation_id` | `string` | Yes | — |
| `modality` | `image \| video` | Yes | — |
| `status` | `queued \| running \| succeeded \| failed` | Yes | — |
| `output_url` | `string` | No | — |
| `references` | `object[]` | No | — |
| `search_results` | `object[]` | No | — |
| `error` | `object` | No | — |
| `created_at` | `number` | Yes | — |
| `updated_at` | `number` | Yes | — |
| `usage` | `object` | No | — |

> **references full type**
>
> ```ts theme={null}
> {
>   source_id?: string,
>   url?: string,
>   title?: string,
>   cover_url?: string
> }[]
> ```

> **search\_results full type**
>
> ```ts theme={null}
> {
>   query?: string,
>   results?: {
>     type?: image | video,
>     title?: string,
>     url?: string,
>     source_page?: string,
>     description?: string,
>     cover_url?: string
>   }[]
> }[]
> ```

> **error full type**
>
> ```ts theme={null}
> {
>   code?: MM_GENERATION_CONTENT_POLICY | MM_GENERATION_INPUT_IMAGE_PRIVACY_BLOCKED | MM_GENERATION_CONTENT_NOT_SUPPORTED | MM_GENERATION_NO_REFERENCE_MATERIAL | MM_GENERATION_REJECTED | MM_GENERATION_TIMEOUT | MM_GENERATION_FAILED,
>   message?: string
> }
> ```

> **usage full type**
>
> ```ts theme={null}
> {
>   image_count?: number,
>   video_count?: number,
>   video_seconds?: number
> }
> ```

***

## Image Search

### post

`imageSearch.post`

Search images by text query or by a reference image

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.imageSearch.post({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `inputs` | `object[]` | Yes | — |
| `count` | `number` | No | — |
| `include_domains` | `string[]` | No | — |
| `exclude_domains` | `string[]` | No | — |
| `safesearch` | `off \| strict` | No | — |

> **inputs full type**
>
> ```ts theme={null}
> {
>   type: text | image,
>   url?: string,
>   data?: string
> }[]
> ```

**Output**

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

> **results full type**
>
> ```ts theme={null}
> {
>   title?: string,
>   url?: string,
>   source_page?: string,
>   description?: string,
>   width?: number,
>   height?: number,
>   thumbnail?: string
> }[]
> ```

***

## News Search

### post

`newsSearch.post`

Search news articles, optionally grouped into events

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.newsSearch.post({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | — |
| `count` | `number` | No | — |
| `include_domains` | `string[]` | No | — |
| `exclude_domains` | `string[]` | No | — |
| `time_basis` | `auto \| published \| crawled` | No | — |
| `time_range` | `day \| week \| month \| year \| d \| w \| m \| y` | No | — |
| `start_time` | `string` | No | — |
| `end_time` | `string` | No | — |
| `language` | `ar \| de \| en \| es \| fr \| hi \| id \| it \| ja \| ko \| nl \| pl \| pt \| ru \| th \| tr \| vi \| zh[]` | No | — |
| `highlight` | `object` | No | — |
| `full_content` | `object` | No | — |
| `subjects` | `object` | No | — |

> **highlight full type**
>
> ```ts theme={null}
> {
>   enable?: boolean,
>   max_tokens?: number
> }
> ```

> **full\_content full type**
>
> ```ts theme={null}
> {
>   enable?: boolean,
>   max_tokens?: number
> }
> ```

> **subjects full type**
>
> ```ts theme={null}
> {
>   enable?: boolean,
>   count?: number,
>   max_sub_news?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | No | — |
| `results` | `object[]` | No | — |
| `subjects` | `object[]` | No | — |

> **results full type**
>
> ```ts theme={null}
> {
>   title?: string,
>   url?: string,
>   summary?: string,
>   highlight?: string,
>   full_content?: string,
>   authors?: string,
>   time_published?: string,
>   time_last_crawled?: string,
>   favicon?: string,
>   cover_image?: {
>     url?: string,
>     description?: string
>   },
>   images?: {
>     url?: string,
>     description?: string
>   }[]
> }[]
> ```

> **subjects full type**
>
> ```ts theme={null}
> {
>   name?: string,
>   summary?: string,
>   time_start?: string,
>   time_latest?: string,
>   top_news?: {
>     title?: string,
>     url?: string,
>     summary?: string,
>     highlight?: string,
>     full_content?: string,
>     authors?: string,
>     time_published?: string,
>     time_last_crawled?: string,
>     favicon?: string,
>     cover_image?: {
>       url?: string,
>       description?: string
>     },
>     images?: {
>       url?: string,
>       description?: string
>     }[]
>   },
>   sub_news?: {
>     title?: string,
>     url?: string,
>     summary?: string,
>     highlight?: string,
>     full_content?: string,
>     authors?: string,
>     time_published?: string,
>     time_last_crawled?: string,
>     favicon?: string,
>     cover_image?: {
>       url?: string,
>       description?: string
>     },
>     images?: {
>       url?: string,
>       description?: string
>     }[]
>   }[]
> }[]
> ```

***

## Search

### post

`search.post`

Search the web with ranked, highlightable results

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.search.post({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `count` | `number` | No | — |
| `include_domains` | `string[]` | No | — |
| `exclude_domains` | `string[]` | No | — |
| `include_text` | `string[]` | No | — |
| `exclude_text` | `string[]` | No | — |
| `time_basis` | `auto \| published \| crawled` | No | — |
| `time_range` | `day \| week \| month \| year \| d \| w \| m \| y` | No | — |
| `start_time` | `string` | No | — |
| `end_time` | `string` | No | — |
| `language` | `ar \| de \| en \| es \| fr \| hi \| id \| it \| ja \| ko \| nl \| pl \| pt \| ru \| th \| tr \| vi \| zh[]` | No | — |
| `highlight` | `object` | No | — |
| `full_content` | `object` | No | — |
| `format` | `markdown \| text` | No | — |
| `safesearch` | `off \| strict` | No | — |
| `include_images` | `boolean` | No | — |
| `query` | `string` | Yes | — |

> **highlight full type**
>
> ```ts theme={null}
> {
>   enable?: boolean,
>   max_tokens?: number
> }
> ```

> **full\_content full type**
>
> ```ts theme={null}
> {
>   enable?: boolean,
>   max_tokens?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | No | — |
| `results` | `object[]` | No | — |

> **results full type**
>
> ```ts theme={null}
> {
>   title?: string,
>   url?: string,
>   highlight?: string,
>   full_content?: string,
>   authors?: string,
>   time_published?: string,
>   time_last_crawled?: string,
>   favicon?: string,
>   cover_image?: {
>     url?: string,
>     description?: string
>   },
>   images?: {
>     url?: string,
>     description?: string
>   }[]
> }[]
> ```

***

## Video Generation

### create

`videoGeneration.create`

Queue a text-to-video generation task

**Risk:** `write`

```ts theme={null}
await corsair.octen.api.videoGeneration.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `model` | `minimax/minimax-h3 \| bytedance/seedance-2.5 \| google/veo-3.1 \| google/veo-3.1-fast \| google/veo-3.1-lite` | Yes | — |
| `prompt` | `string` | Yes | — |
| `duration` | `number` | No | — |
| `resolution` | `480p \| 720p \| 768p \| 1080p \| 2K` | No | — |
| `aspect_ratio` | `16:9 \| 4:3 \| 1:1 \| 3:4 \| 9:16 \| 21:9 \| adaptive` | No | — |
| `frame_images` | `object[]` | No | — |
| `input_references` | `object[]` | No | — |
| `generate_audio` | `boolean` | No | — |
| `seed` | `number` | No | — |
| `extra_params` | `object` | No | — |

> **frame\_images full type**
>
> ```ts theme={null}
> {
>   image: string,
>   frame_type: first_frame | last_frame
> }[]
> ```

> **input\_references full type**
>
> ```ts theme={null}
> {
>   image: string
> }[]
> ```

> **extra\_params full type**
>
> ```ts theme={null}
> {
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `model` | `string` | Yes | — |
| `status` | `queued` | Yes | — |
| `created` | `number` | Yes | — |

***

### get

`videoGeneration.get`

Get a video generation task and its download URL

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.videoGeneration.get({});
```

**Input**

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

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `model` | `string` | Yes | — |
| `status` | `queued \| in_progress \| completed \| failed` | Yes | — |
| `created` | `number` | Yes | — |
| `video_url` | `string` | No | — |
| `expires_at` | `number` | No | — |
| `duration` | `number` | No | — |
| `resolution` | `string` | No | — |
| `usage` | `object` | No | — |
| `error` | `string` | No | — |
| `code` | `string` | No | — |

> **usage full type**
>
> ```ts theme={null}
> {
>   video_seconds?: number,
>   video_tokens?: number,
>   input_image_count?: number
> }
> ```

***

## Video Search

### post

`videoSearch.post`

Search videos by a text query

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.videoSearch.post({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `inputs` | `object[]` | Yes | — |
| `count` | `number` | No | — |
| `time_range` | `day \| week \| month \| year \| d \| w \| m \| y` | No | — |
| `start_time` | `string` | No | — |
| `end_time` | `string` | No | — |
| `safesearch` | `off \| strict` | No | — |

> **inputs full type**
>
> ```ts theme={null}
> {
>   type: text,
>   data?: string
> }[]
> ```

**Output**

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

> **results full type**
>
> ```ts theme={null}
> {
>   title?: string,
>   url?: string,
>   source_page?: string,
>   description?: string,
>   cover_url?: string,
>   duration_seconds?: number,
>   authors?: string,
>   time_published?: string,
>   time_last_crawled?: string
> }[]
> ```

***

## Vl Embedding

### create

`vlEmbedding.create`

Create multimodal embeddings from text, images and video

**Risk:** `read`

```ts theme={null}
await corsair.octen.api.vlEmbedding.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `model` | `octen-vl-embedding \| octen-vl-embedding-large` | Yes | — |
| `input` | `object` | Yes | — |
| `enable_fusion` | `boolean` | No | — |
| `dimension` | `number` | No | — |
| `fps` | `number` | No | — |
| `instruct` | `string` | No | — |

> **input full type**
>
> ```ts theme={null}
> {
>   contents: {
>     text?: string,
>     image?: string,
>     video?: string
>   }[]
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | No | — |
| `model` | `string` | No | — |

> **results full type**
>
> ```ts theme={null}
> {
>   index?: number,
>   embedding?: number[],
>   type?: vl | fusion
> }[]
> ```

***


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