> ## 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 Cody: every `cody.api.*` operation with input and output types.

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

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

## Bots

### list

`bots.list`

Get all bots with optional keyword filtering

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.bots.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `search` | `string` | No | Keyword to filter bots by name |
| `keyword` | `string` | No | Keyword to filter bots by name |
| `page` | `number` | No | Page number for pagination |
| `per_page` | `number` | No | Number of items per page |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      description?: string,
      model?: string,
      created_at?: number
    }[]
    ```
  </Accordion>

  <Accordion title="meta full type">
    ```ts theme={null}
    {
      pagination?: {
        total?: number,
        count?: number,
        per_page?: number,
        current_page?: number,
        total_pages?: number,
        links?: {
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Conversations

### create

`conversations.create`

Create a new conversation with a specified bot and optional focus mode documents

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.conversations.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Name of the conversation |
| `bot_id` | `string` | Yes | Bot ID to create the conversation with |
| `document_ids` | `string[]` | No | Optional document IDs to limit bot focus to specific knowledge |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      bot_id: string,
      created_at?: number,
      document_ids?: string[]
    }
    ```
  </Accordion>
</AccordionGroup>

***

### delete

`conversations.delete`

Delete a conversation by its ID

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.conversations.delete({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Unique identifier of the conversation to delete |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `boolean \| null` | No | — |
| `success` | `boolean` | No | — |

***

### get

`conversations.get`

Fetch a conversation by its ID from Cody AI

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.conversations.get({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Unique identifier of the conversation |
| `includes` | `string` | No | Extra attributes to include (e.g. document\_ids) |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      bot_id: string,
      created_at?: number,
      document_ids?: string[]
    }
    ```
  </Accordion>
</AccordionGroup>

***

### list

`conversations.list`

Get all conversations with optional filtering by bot, keyword, or includes

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.conversations.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `search` | `string` | No | Keyword to filter conversations by name |
| `keyword` | `string` | No | Keyword to filter conversations by name |
| `bot_id` | `string` | No | Filter conversations by bot ID |
| `includes` | `string` | No | Extra attributes to include (e.g. document\_ids) |
| `page` | `number` | No | Page number for pagination |
| `per_page` | `number` | No | Number of items per page |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      bot_id: string,
      created_at?: number,
      document_ids?: string[]
    }[]
    ```
  </Accordion>

  <Accordion title="meta full type">
    ```ts theme={null}
    {
      pagination?: {
        total?: number,
        count?: number,
        per_page?: number,
        current_page?: number,
        total_pages?: number,
        links?: {
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

### update

`conversations.update`

Update a conversation by its ID including name, bot\_id, and document\_ids

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.conversations.update({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Unique identifier of the conversation |
| `name` | `string` | No | Updated name for the conversation |
| `bot_id` | `string` | No | Updated bot ID for the conversation |
| `document_ids` | `string[]` | No | Updated document IDs for focus mode |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      bot_id: string,
      created_at?: number,
      document_ids?: string[]
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Documents

### create

`documents.create`

Create a new document with text or HTML content in Cody AI

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.documents.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Name of the document |
| `content` | `string` | Yes | Text or HTML content of the document (up to 768 KB) |
| `content_type` | `text/plain \| text/html` | Yes | MIME content type of the content body |
| `folder_id` | `string` | No | Folder ID where the document should be stored |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      status?: string,
      content_url?: string,
      folder_id?: string | null,
      created_at?: number
    }
    ```
  </Accordion>
</AccordionGroup>

***

### createFromFile

`documents.createFromFile`

Create a document by uploading a file (up to 100 MB)

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.documents.createFromFile({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `key` | `string` | Yes | S3 storage key obtained from uploads.getSignedUrl |
| `folder_id` | `string` | No | Folder ID where the document should be stored |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      status?: string,
      content_url?: string,
      folder_id?: string | null,
      created_at?: number
    }
    ```
  </Accordion>
</AccordionGroup>

***

### createFromWebpage

`documents.createFromWebpage`

Create a document from a publicly accessible webpage URL

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.documents.createFromWebpage({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | Publicly accessible webpage URL to import |
| `folder_id` | `string` | No | Folder ID where the document should be stored |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      status?: string,
      content_url?: string,
      folder_id?: string | null,
      created_at?: number
    }
    ```
  </Accordion>
</AccordionGroup>

***

### delete

`documents.delete`

Delete a document by id

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.documents.delete({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Unique identifier of the document to delete |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `boolean \| null` | No | — |
| `success` | `boolean` | No | — |

***

### get

`documents.get`

Retrieve a specific document by its identifier from Cody AI

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.documents.get({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Unique identifier of the document |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      status?: string,
      content_url?: string,
      folder_id?: string | null,
      created_at?: number
    }
    ```
  </Accordion>
</AccordionGroup>

***

### list

`documents.list`

Retrieve all documents from Cody AI account with optional filtering

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.documents.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `search` | `string` | No | Keyword to filter documents by name |
| `keyword` | `string` | No | Keyword to filter documents by name |
| `folder_id` | `string` | No | Filter documents by folder ID |
| `conversation_id` | `string` | No | Filter documents by conversation ID |
| `page` | `number` | No | Page number for pagination |
| `per_page` | `number` | No | Number of items per page |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      status?: string,
      content_url?: string,
      folder_id?: string | null,
      created_at?: number
    }[]
    ```
  </Accordion>

  <Accordion title="meta full type">
    ```ts theme={null}
    {
      pagination?: {
        total?: number,
        count?: number,
        per_page?: number,
        current_page?: number,
        total_pages?: number,
        links?: {
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Folders

### create

`folders.create`

Create a new folder in Cody AI for organizing content

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.folders.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Name of the folder |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      created_at?: number
    }
    ```
  </Accordion>
</AccordionGroup>

***

### get

`folders.get`

Retrieve a specific folder by its identifier

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.folders.get({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Unique identifier of the folder |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      created_at?: number
    }
    ```
  </Accordion>
</AccordionGroup>

***

### list

`folders.list`

Retrieve all folders with optional keyword filtering

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.folders.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `search` | `string` | No | Keyword to filter folders by name |
| `keyword` | `string` | No | Keyword to filter folders by name |
| `page` | `number` | No | Page number for pagination |
| `per_page` | `number` | No | Number of items per page |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      created_at?: number
    }[]
    ```
  </Accordion>

  <Accordion title="meta full type">
    ```ts theme={null}
    {
      pagination?: {
        total?: number,
        count?: number,
        per_page?: number,
        current_page?: number,
        total_pages?: number,
        links?: {
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

### update

`folders.update`

Update a folder by its ID

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.folders.update({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Unique identifier of the folder to update |
| `name` | `string` | Yes | New name for the folder |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      name: string,
      created_at?: number
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Messages

### get

`messages.get`

Fetch a specific message by its ID from Cody AI

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.messages.get({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Unique identifier of the message |
| `includes` | `string` | No | Extra message attributes to include (sources, usage) |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      content: string,
      conversation_id: string,
      machine?: boolean,
      failed_responding?: boolean,
      flagged?: boolean,
      created_at?: number,
      sources?: {
        data?: {
        }[]
      },
      usage?: {
        tokens?: number,
        credits?: number
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

### list

`messages.list`

Retrieve a paginated list of messages from Cody, optionally filtered by conversation

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.messages.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `conversation_id` | `string` | Yes | Conversation ID to retrieve messages for |
| `includes` | `string` | No | Extra message attributes to include (sources, usage) |
| `page` | `number` | No | Page number for pagination |
| `per_page` | `number` | No | Number of items per page |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      content: string,
      conversation_id: string,
      machine?: boolean,
      failed_responding?: boolean,
      flagged?: boolean,
      created_at?: number,
      sources?: {
        data?: {
        }[]
      },
      usage?: {
        tokens?: number,
        credits?: number
      }
    }[]
    ```
  </Accordion>

  <Accordion title="meta full type">
    ```ts theme={null}
    {
      pagination?: {
        total?: number,
        count?: number,
        per_page?: number,
        current_page?: number,
        total_pages?: number,
        links?: {
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

### send

`messages.send`

Send a message to Cody AI and receive an AI-generated response

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.messages.send({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `conversation_id` | `string` | Yes | Conversation ID to send the message in |
| `content` | `string` | Yes | Text content of the message (up to 2000 characters) |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      id: string,
      content: string,
      conversation_id: string,
      machine?: boolean,
      failed_responding?: boolean,
      flagged?: boolean,
      created_at?: number,
      sources?: {
        data?: {
        }[]
      },
      usage?: {
        tokens?: number,
        credits?: number
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

### sendForStream

`messages.sendForStream`

Send a message to Cody AI and receive a Server-Sent Events (SSE) stream URL for the AI response

**Risk:** `write`

```ts theme={null}
await corsair.cody.api.messages.sendForStream({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `conversation_id` | `string` | Yes | Conversation ID to send the streaming message in |
| `content` | `string` | Yes | Text content of the message (up to 2000 characters) |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      stream_url: string
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Uploads

### getSignedUrl

`uploads.getSignedUrl`

Get an AWS S3 signed upload URL for file uploads

**Risk:** `read`

```ts theme={null}
await corsair.cody.api.uploads.getSignedUrl({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `file_name` | `string` | Yes | Original file name with extension to upload (e.g. document.pdf) |
| `content_type` | `string` | Yes | MIME content type of the file (e.g. application/pdf) |

**Output**

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

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      url: string,
      key: string
    }
    ```
  </Accordion>
</AccordionGroup>

***


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