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

# BugHerd API reference

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

## Columns

### create

`columns.create`

Add a custom column at the end of a project board.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.columns.create({ project_id: 552668, name: 'In Review' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `name` | `string` | Yes | Column name. It is added at the end of the board. |

**Output**

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

> [accordion] column full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   project_id?: number | null,
>   position?: number | null,
>   tasks_count?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null
> }
> ```

***

### delete

`columns.delete`

Delete an empty column. Cannot be undone.

**Risk:** `destructive`

```ts theme={null}
await corsair.bugherd.api.columns.delete({ project_id: 552668, column_id: 55 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `column_id` | `number` | Yes | — |

**Output**

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

***

### list

`columns.list`

List the columns on a project board, built-in and custom.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.columns.list({ project_id: 552668 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |

**Output**

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

> [accordion] columns full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   project_id?: number | null,
>   position?: number | null,
>   tasks_count?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null
> }[]
> ```

***

### show

`columns.show`

Get one column.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.columns.show({ project_id: 552668, column_id: 55 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `column_id` | `number` | Yes | — |

**Output**

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

> [accordion] column full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   project_id?: number | null,
>   position?: number | null,
>   tasks_count?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null
> }
> ```

***

### update

`columns.update`

Rename a custom column.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.columns.update({ project_id: 552668, column_id: 55, name: 'QA' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `column_id` | `number` | Yes | — |
| `name` | `string` | Yes | — |

**Output**

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

> [accordion] column full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   project_id?: number | null,
>   position?: number | null,
>   tasks_count?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null
> }
> ```

***

## Organization

### show

`organization.show`

Get the organization name and id.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.organization.show({});
```

**Input:** *empty object*

**Output**

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

> [accordion] organization full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null
> }
> ```

***

## Projects

### addGuest

`projects.addGuest`

Add a guest (client) to a project by user id, or invite one by email. An email invite sends the person a message.

**Risk:** `destructive`

```ts theme={null}
await corsair.bugherd.api.projects.addGuest({ project_id: 552668, user_id: 123 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `user_id` | `number` | No | Id of an existing user. |
| `email` | `string` | No | Invite a new guest by email. BugHerd emails them an invitation. |

**Output**

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

> [accordion] project full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   created_at?: string | null,
>   tasks?: boolean | null,
>   devurl?: string | null,
>   is_active?: boolean | null,
>   is_public?: boolean | null,
>   has_custom_columns?: boolean | null,
>   guests_see_guests?: boolean | null,
>   owner_name?: string | null,
>   sites?: string[] | null,
>   allow_guests_change_task_status?: boolean | null,
>   assign_guests?: boolean | null,
>   allow_project_summary_email?: boolean | null,
>   allow_task_done_email?: boolean | null,
>   allow_project_owner_notifications?: boolean | null,
>   change_guest_default_column?: boolean | null,
>   members?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   guests?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   columns?: {
>     id: number,
>     name?: string | null,
>     project_id?: number | null,
>     position?: number | null,
>     tasks_count?: number | null,
>     created_at?: string | null,
>     updated_at?: string | null
>   }[] | null
> }
> ```

***

### addMember

`projects.addMember`

Add one or more organization members to a project.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.projects.addMember({ project_id: 552668, user_id: 4561 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `user_id` | `number \| number[]` | Yes | Id of an organization member, or a list of ids. |

**Output**

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

> [accordion] project full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   created_at?: string | null,
>   tasks?: boolean | null,
>   devurl?: string | null,
>   is_active?: boolean | null,
>   is_public?: boolean | null,
>   has_custom_columns?: boolean | null,
>   guests_see_guests?: boolean | null,
>   owner_name?: string | null,
>   sites?: string[] | null,
>   allow_guests_change_task_status?: boolean | null,
>   assign_guests?: boolean | null,
>   allow_project_summary_email?: boolean | null,
>   allow_task_done_email?: boolean | null,
>   allow_project_owner_notifications?: boolean | null,
>   change_guest_default_column?: boolean | null,
>   members?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   guests?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   columns?: {
>     id: number,
>     name?: string | null,
>     project_id?: number | null,
>     position?: number | null,
>     tasks_count?: number | null,
>     created_at?: string | null,
>     updated_at?: string | null
>   }[] | null
> }
> ```

***

### create

`projects.create`

Create a project for a website. Members and guests are added separately.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.projects.create({ name: 'Marketing site', devurl: 'https://www.example.com' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Project name. |
| `devurl` | `string` | Yes | The website the project gives feedback on. |
| `is_active` | `boolean` | No | — |
| `is_public` | `boolean` | No | Let anyone leave feedback without a login. |
| `guests_see_guests` | `boolean` | No | Let guests see other guests' feedback. |

**Output**

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

> [accordion] project full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   created_at?: string | null,
>   tasks?: boolean | null,
>   devurl?: string | null,
>   is_active?: boolean | null,
>   is_public?: boolean | null,
>   has_custom_columns?: boolean | null,
>   guests_see_guests?: boolean | null,
>   owner_name?: string | null,
>   sites?: string[] | null,
>   allow_guests_change_task_status?: boolean | null,
>   assign_guests?: boolean | null,
>   allow_project_summary_email?: boolean | null,
>   allow_task_done_email?: boolean | null,
>   allow_project_owner_notifications?: boolean | null,
>   change_guest_default_column?: boolean | null,
>   members?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   guests?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   columns?: {
>     id: number,
>     name?: string | null,
>     project_id?: number | null,
>     position?: number | null,
>     tasks_count?: number | null,
>     created_at?: string | null,
>     updated_at?: string | null
>   }[] | null
> }
> ```

***

### delete

`projects.delete`

Delete a project and all its tasks. Cannot be undone.

**Risk:** `destructive`

```ts theme={null}
await corsair.bugherd.api.projects.delete({ project_id: 552668 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |

**Output**

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

***

### list

`projects.list`

List every project in the organization, active and inactive. 100 per page.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.projects.list({ page: 1 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] projects full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   created_at?: string | null,
>   tasks?: boolean | null,
>   devurl?: string | null,
>   is_active?: boolean | null,
>   is_public?: boolean | null,
>   has_custom_columns?: boolean | null,
>   guests_see_guests?: boolean | null,
>   owner_name?: string | null,
>   sites?: string[] | null,
>   allow_guests_change_task_status?: boolean | null,
>   assign_guests?: boolean | null,
>   allow_project_summary_email?: boolean | null,
>   allow_task_done_email?: boolean | null,
>   allow_project_owner_notifications?: boolean | null,
>   change_guest_default_column?: boolean | null,
>   members?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   guests?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   columns?: {
>     id: number,
>     name?: string | null,
>     project_id?: number | null,
>     position?: number | null,
>     tasks_count?: number | null,
>     created_at?: string | null,
>     updated_at?: string | null
>   }[] | null
> }[]
> ```

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

***

### listActive

`projects.listActive`

List active projects only. 100 per page.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.projects.listActive({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] projects full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   created_at?: string | null,
>   tasks?: boolean | null,
>   devurl?: string | null,
>   is_active?: boolean | null,
>   is_public?: boolean | null,
>   has_custom_columns?: boolean | null,
>   guests_see_guests?: boolean | null,
>   owner_name?: string | null,
>   sites?: string[] | null,
>   allow_guests_change_task_status?: boolean | null,
>   assign_guests?: boolean | null,
>   allow_project_summary_email?: boolean | null,
>   allow_task_done_email?: boolean | null,
>   allow_project_owner_notifications?: boolean | null,
>   change_guest_default_column?: boolean | null,
>   members?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   guests?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   columns?: {
>     id: number,
>     name?: string | null,
>     project_id?: number | null,
>     position?: number | null,
>     tasks_count?: number | null,
>     created_at?: string | null,
>     updated_at?: string | null
>   }[] | null
> }[]
> ```

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

***

### show

`projects.show`

Get one project with its members, guests and columns.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.projects.show({ project_id: 552668 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |

**Output**

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

> [accordion] project full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   created_at?: string | null,
>   tasks?: boolean | null,
>   devurl?: string | null,
>   is_active?: boolean | null,
>   is_public?: boolean | null,
>   has_custom_columns?: boolean | null,
>   guests_see_guests?: boolean | null,
>   owner_name?: string | null,
>   sites?: string[] | null,
>   allow_guests_change_task_status?: boolean | null,
>   assign_guests?: boolean | null,
>   allow_project_summary_email?: boolean | null,
>   allow_task_done_email?: boolean | null,
>   allow_project_owner_notifications?: boolean | null,
>   change_guest_default_column?: boolean | null,
>   members?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   guests?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   columns?: {
>     id: number,
>     name?: string | null,
>     project_id?: number | null,
>     position?: number | null,
>     tasks_count?: number | null,
>     created_at?: string | null,
>     updated_at?: string | null
>   }[] | null
> }
> ```

***

### update

`projects.update`

Change a project's name, URL or settings. Only the fields given change.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.projects.update({ project_id: 552668, is_public: false });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `name` | `string` | No | — |
| `devurl` | `string` | No | — |
| `is_active` | `boolean` | No | — |
| `is_public` | `boolean` | No | — |
| `has_custom_columns` | `boolean` | No | — |
| `guests_see_guests` | `boolean` | No | — |

**Output**

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

> [accordion] project full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   created_at?: string | null,
>   tasks?: boolean | null,
>   devurl?: string | null,
>   is_active?: boolean | null,
>   is_public?: boolean | null,
>   has_custom_columns?: boolean | null,
>   guests_see_guests?: boolean | null,
>   owner_name?: string | null,
>   sites?: string[] | null,
>   allow_guests_change_task_status?: boolean | null,
>   assign_guests?: boolean | null,
>   allow_project_summary_email?: boolean | null,
>   allow_task_done_email?: boolean | null,
>   allow_project_owner_notifications?: boolean | null,
>   change_guest_default_column?: boolean | null,
>   members?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   guests?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   columns?: {
>     id: number,
>     name?: string | null,
>     project_id?: number | null,
>     position?: number | null,
>     tasks_count?: number | null,
>     created_at?: string | null,
>     updated_at?: string | null
>   }[] | null
> }
> ```

***

## Tasks

### create

`tasks.create`

Create a task in a project. Without a status it lands in the Feedback panel.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.tasks.create({ project_id: 552668, description: 'Login button does nothing on Safari', priority: 'important', status: 'todo', tag_names: ['safari'] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `description` | `string` | Yes | What the task is about. |
| `priority` | `not set \| critical \| important \| normal \| minor` | No | Task priority. |
| `status` | `string` | No | Column name. Leave it out to put the task in the Feedback panel. |
| `requester_id` | `number` | No | — |
| `requester_email` | `string` | No | — |
| `assigned_to_id` | `number` | No | — |
| `assigned_to_email` | `string` | No | Must be a member of the project. |
| `tag_names` | `string[]` | No | — |
| `external_id` | `string` | No | Your own reference for the task. |

**Output**

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

> [accordion] task full type
>
> ```ts theme={null}
> {
>   id: number,
>   local_task_id?: number | null,
>   project_id?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null,
>   closed_at?: string | null,
>   deleted_at?: string | null,
>   title?: string | null,
>   description?: string | null,
>   status?: string | null,
>   status_id?: number | null,
>   priority?: string | null,
>   priority_id?: number | null,
>   site?: string | null,
>   url?: string | null,
>   tag_names?: string[] | null,
>   external_id?: string | null,
>   requester_email?: string | null,
>   attachments?: {
>     id: number,
>     file_name?: string | null,
>     url?: string | null,
>     created_at?: string | null
>   }[] | null,
>   screenshot_url?: string | null,
>   secret_link?: string | null,
>   admin_link?: string | null,
>   assigned_to?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   requester?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   project_name?: string | null,
>   due_at?: string | null,
>   assignee_ids?: number[] | null,
>   assignees?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   }[] | null,
>   assigned_to_id?: number | null,
>   requester_id?: number | null,
>   column_id?: number | null,
>   metadata?: Record<string, any> | null
> }
> ```

***

### createAttachment

`tasks.createAttachment`

Attach a file to a task from a public URL. BugHerd keeps a copy.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.tasks.createAttachment({ project_id: 552668, task_id: 98765, file_name: 'screenshot.png', url: 'https://example.com/screenshot.png' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |
| `file_name` | `string` | Yes | Name to show for the file. |
| `url` | `string` | Yes | Public URL of the file. BugHerd downloads and keeps a copy. |

**Output**

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

> [accordion] attachment full type
>
> ```ts theme={null}
> {
>   id: number,
>   file_name?: string | null,
>   url?: string | null,
>   created_at?: string | null
> }
> ```

***

### createComment

`tasks.createComment`

Comment on a task, optionally visible to team members only.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.tasks.createComment({ project_id: 552668, task_id: 98765, text: 'Fixed in the next release.', is_private: true });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |
| `text` | `string` | Yes | Comment text. |
| `user_id` | `number` | No | Who the comment is from. |
| `email` | `string` | No | Who the comment is from, by email, instead of user\_id. |
| `is_private` | `boolean` | No | Visible to team members only, not guests. |

**Output**

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

> [accordion] comment full type
>
> ```ts theme={null}
> {
>   id: number,
>   text?: string | null,
>   created_at?: string | null,
>   user_id?: number | null,
>   is_private?: boolean | null
> }
> ```

***

### delete

`tasks.delete`

Delete a task. Cannot be undone.

**Risk:** `destructive`

```ts theme={null}
await corsair.bugherd.api.tasks.delete({ project_id: 552668, task_id: 98765 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |

**Output**

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

***

### deleteAttachment

`tasks.deleteAttachment`

Remove an attachment from a task. Cannot be undone.

**Risk:** `destructive`

```ts theme={null}
await corsair.bugherd.api.tasks.deleteAttachment({ project_id: 552668, task_id: 98765, attachment_id: 331 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |
| `attachment_id` | `number` | Yes | — |

**Output**

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

***

### list

`tasks.list`

List tasks in a project, filtered by status, priority, tag, assignee, external id or date. 100 per page.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.list({ project_id: 552668, status: 'todo', priority: 'critical' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `updated_since` | `string` | No | Only records updated after this ISO 8601 timestamp. |
| `created_since` | `string` | No | Only records created after this ISO 8601 timestamp. |
| `status` | `string` | No | Column name: backlog, todo, doing, done, closed or a custom column. |
| `priority` | `not set \| critical \| important \| normal \| minor` | No | Task priority. |
| `tag` | `string` | No | Only tasks with this tag. |
| `assigned_to_id` | `number` | No | Only tasks assigned to this user. |
| `external_id` | `string` | No | — |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] tasks full type
>
> ```ts theme={null}
> {
>   id: number,
>   local_task_id?: number | null,
>   project_id?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null,
>   closed_at?: string | null,
>   deleted_at?: string | null,
>   title?: string | null,
>   description?: string | null,
>   status?: string | null,
>   status_id?: number | null,
>   priority?: string | null,
>   priority_id?: number | null,
>   site?: string | null,
>   url?: string | null,
>   tag_names?: string[] | null,
>   external_id?: string | null,
>   requester_email?: string | null,
>   attachments?: {
>     id: number,
>     file_name?: string | null,
>     url?: string | null,
>     created_at?: string | null
>   }[] | null,
>   screenshot_url?: string | null,
>   secret_link?: string | null,
>   admin_link?: string | null,
>   assigned_to?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   requester?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   project_name?: string | null,
>   due_at?: string | null,
>   assignee_ids?: number[] | null,
>   assignees?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   }[] | null,
>   assigned_to_id?: number | null,
>   requester_id?: number | null,
>   column_id?: number | null,
>   metadata?: Record<string, any> | null
> }[]
> ```

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

***

### listArchived

`tasks.listArchived`

List closed and archived tasks in a project.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.listArchived({ project_id: 552668 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] tasks full type
>
> ```ts theme={null}
> {
>   id: number,
>   local_task_id?: number | null,
>   project_id?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null,
>   closed_at?: string | null,
>   deleted_at?: string | null,
>   title?: string | null,
>   description?: string | null,
>   status?: string | null,
>   status_id?: number | null,
>   priority?: string | null,
>   priority_id?: number | null,
>   site?: string | null,
>   url?: string | null,
>   tag_names?: string[] | null,
>   external_id?: string | null,
>   requester_email?: string | null,
>   attachments?: {
>     id: number,
>     file_name?: string | null,
>     url?: string | null,
>     created_at?: string | null
>   }[] | null,
>   screenshot_url?: string | null,
>   secret_link?: string | null,
>   admin_link?: string | null,
>   assigned_to?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   requester?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   project_name?: string | null,
>   due_at?: string | null,
>   assignee_ids?: number[] | null,
>   assignees?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   }[] | null,
>   assigned_to_id?: number | null,
>   requester_id?: number | null,
>   column_id?: number | null,
>   metadata?: Record<string, any> | null
> }[]
> ```

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

***

### listAttachments

`tasks.listAttachments`

List the files attached to a task.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.listAttachments({ project_id: 552668, task_id: 98765 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |

**Output**

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

> [accordion] attachments full type
>
> ```ts theme={null}
> {
>   id: number,
>   file_name?: string | null,
>   url?: string | null,
>   created_at?: string | null
> }[]
> ```

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

***

### listComments

`tasks.listComments`

List the comments on a task.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.listComments({ project_id: 552668, task_id: 98765 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |

**Output**

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

> [accordion] comments full type
>
> ```ts theme={null}
> {
>   id: number,
>   text?: string | null,
>   created_at?: string | null,
>   user_id?: number | null,
>   is_private?: boolean | null
> }[]
> ```

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

***

### listFeedback

`tasks.listFeedback`

List tasks in the Feedback panel (new, not yet triaged).

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.listFeedback({ project_id: 552668 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] tasks full type
>
> ```ts theme={null}
> {
>   id: number,
>   local_task_id?: number | null,
>   project_id?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null,
>   closed_at?: string | null,
>   deleted_at?: string | null,
>   title?: string | null,
>   description?: string | null,
>   status?: string | null,
>   status_id?: number | null,
>   priority?: string | null,
>   priority_id?: number | null,
>   site?: string | null,
>   url?: string | null,
>   tag_names?: string[] | null,
>   external_id?: string | null,
>   requester_email?: string | null,
>   attachments?: {
>     id: number,
>     file_name?: string | null,
>     url?: string | null,
>     created_at?: string | null
>   }[] | null,
>   screenshot_url?: string | null,
>   secret_link?: string | null,
>   admin_link?: string | null,
>   assigned_to?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   requester?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   project_name?: string | null,
>   due_at?: string | null,
>   assignee_ids?: number[] | null,
>   assignees?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   }[] | null,
>   assigned_to_id?: number | null,
>   requester_id?: number | null,
>   column_id?: number | null,
>   metadata?: Record<string, any> | null
> }[]
> ```

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

***

### listForUser

`tasks.listForUser`

List tasks assigned to a user across all projects.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.listForUser({ user_id: 4561 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `user_id` | `number` | Yes | BugHerd user id. |
| `updated_since` | `string` | No | Only records updated after this ISO 8601 timestamp. |
| `created_since` | `string` | No | Only records created after this ISO 8601 timestamp. |
| `priority` | `not set \| critical \| important \| normal \| minor` | No | Task priority. |
| `tag` | `string` | No | Only tasks with this tag. |
| `assigned_to_id` | `number` | No | Only tasks assigned to this user. |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

`GET /users/{user_id}/tasks.json`. BugHerd answers with a bare array; the plugin returns it as `{ tasks }` like the other task lists.

**Output**

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

> [accordion] tasks full type
>
> ```ts theme={null}
> {
>   id: number,
>   local_task_id?: number | null,
>   project_id?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null,
>   closed_at?: string | null,
>   deleted_at?: string | null,
>   title?: string | null,
>   description?: string | null,
>   status?: string | null,
>   status_id?: number | null,
>   priority?: string | null,
>   priority_id?: number | null,
>   site?: string | null,
>   url?: string | null,
>   tag_names?: string[] | null,
>   external_id?: string | null,
>   requester_email?: string | null,
>   attachments?: {
>     id: number,
>     file_name?: string | null,
>     url?: string | null,
>     created_at?: string | null
>   }[] | null,
>   screenshot_url?: string | null,
>   secret_link?: string | null,
>   admin_link?: string | null,
>   assigned_to?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   requester?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   project_name?: string | null,
>   due_at?: string | null,
>   assignee_ids?: number[] | null,
>   assignees?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   }[] | null,
>   assigned_to_id?: number | null,
>   requester_id?: number | null,
>   column_id?: number | null,
>   metadata?: Record<string, any> | null
> }[]
> ```

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

***

### listTaskboard

`tasks.listTaskboard`

List the active tasks on the project taskboard.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.listTaskboard({ project_id: 552668 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] tasks full type
>
> ```ts theme={null}
> {
>   id: number,
>   local_task_id?: number | null,
>   project_id?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null,
>   closed_at?: string | null,
>   deleted_at?: string | null,
>   title?: string | null,
>   description?: string | null,
>   status?: string | null,
>   status_id?: number | null,
>   priority?: string | null,
>   priority_id?: number | null,
>   site?: string | null,
>   url?: string | null,
>   tag_names?: string[] | null,
>   external_id?: string | null,
>   requester_email?: string | null,
>   attachments?: {
>     id: number,
>     file_name?: string | null,
>     url?: string | null,
>     created_at?: string | null
>   }[] | null,
>   screenshot_url?: string | null,
>   secret_link?: string | null,
>   admin_link?: string | null,
>   assigned_to?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   requester?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   project_name?: string | null,
>   due_at?: string | null,
>   assignee_ids?: number[] | null,
>   assignees?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   }[] | null,
>   assigned_to_id?: number | null,
>   requester_id?: number | null,
>   column_id?: number | null,
>   metadata?: Record<string, any> | null
> }[]
> ```

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

***

### move

`tasks.move`

Move tasks to another project, by their #numbers.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.tasks.move({ project_id: 552668, destination_project_id: 552669, task_ids: [42, 43] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | The project the tasks are in now. |
| `destination_project_id` | `number` | Yes | The project to move them to. |
| `task_ids` | `number[]` | Yes | The tasks' #numbers (local\_task\_id), not their global ids. |

`POST /projects/{project_id}/move_tasks.json`. BugHerd notes the route may not be enabled on every account (404).

**Output:** *empty object*

***

### show

`tasks.show`

Get one task by its global id, with or without the project id.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.show({ task_id: 98765 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |
| `project_id` | `number` | No | Project id. Without it the task is looked up by its global id alone. |

`GET /projects/{project_id}/tasks/{task_id}.json`, or `GET /tasks/{task_id}.json` when no project id is given.

**Output**

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

> [accordion] task full type
>
> ```ts theme={null}
> {
>   id: number,
>   local_task_id?: number | null,
>   project_id?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null,
>   closed_at?: string | null,
>   deleted_at?: string | null,
>   title?: string | null,
>   description?: string | null,
>   status?: string | null,
>   status_id?: number | null,
>   priority?: string | null,
>   priority_id?: number | null,
>   site?: string | null,
>   url?: string | null,
>   tag_names?: string[] | null,
>   external_id?: string | null,
>   requester_email?: string | null,
>   attachments?: {
>     id: number,
>     file_name?: string | null,
>     url?: string | null,
>     created_at?: string | null
>   }[] | null,
>   screenshot_url?: string | null,
>   secret_link?: string | null,
>   admin_link?: string | null,
>   assigned_to?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   requester?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   project_name?: string | null,
>   due_at?: string | null,
>   assignee_ids?: number[] | null,
>   assignees?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   }[] | null,
>   assigned_to_id?: number | null,
>   requester_id?: number | null,
>   column_id?: number | null,
>   metadata?: Record<string, any> | null
> }
> ```

***

### showAttachment

`tasks.showAttachment`

Get one attachment on a task.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.showAttachment({ project_id: 552668, task_id: 98765, attachment_id: 331 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |
| `attachment_id` | `number` | Yes | — |

**Output**

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

> [accordion] attachment full type
>
> ```ts theme={null}
> {
>   id: number,
>   file_name?: string | null,
>   url?: string | null,
>   created_at?: string | null
> }
> ```

***

### showByLocalId

`tasks.showByLocalId`

Get a task by the #number shown in the BugHerd UI.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.tasks.showByLocalId({ project_id: 552668, local_task_id: 42 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `local_task_id` | `number` | Yes | The #number shown in the BugHerd UI. |

**Output**

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

> [accordion] task full type
>
> ```ts theme={null}
> {
>   id: number,
>   local_task_id?: number | null,
>   project_id?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null,
>   closed_at?: string | null,
>   deleted_at?: string | null,
>   title?: string | null,
>   description?: string | null,
>   status?: string | null,
>   status_id?: number | null,
>   priority?: string | null,
>   priority_id?: number | null,
>   site?: string | null,
>   url?: string | null,
>   tag_names?: string[] | null,
>   external_id?: string | null,
>   requester_email?: string | null,
>   attachments?: {
>     id: number,
>     file_name?: string | null,
>     url?: string | null,
>     created_at?: string | null
>   }[] | null,
>   screenshot_url?: string | null,
>   secret_link?: string | null,
>   admin_link?: string | null,
>   assigned_to?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   requester?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   project_name?: string | null,
>   due_at?: string | null,
>   assignee_ids?: number[] | null,
>   assignees?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   }[] | null,
>   assigned_to_id?: number | null,
>   requester_id?: number | null,
>   column_id?: number | null,
>   metadata?: Record<string, any> | null
> }
> ```

***

### update

`tasks.update`

Change a task: status (column), priority, assignees, tags, description.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.tasks.update({ project_id: 552668, task_id: 98765, status: 'doing', assigned_to_id: 4561 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |
| `description` | `string` | No | — |
| `priority` | `not set \| critical \| important \| normal \| minor` | No | Task priority. |
| `status` | `string` | No | Column name, or `feedback` to move it back to the Feedback panel. |
| `assigned_to_id` | `number` | No | Assign this project member. Use unassign\_user to remove one. |
| `assigned_to_email` | `string` | No | — |
| `unassign_user` | `number` | No | Remove this assignee from the task. |
| `tag_names` | `string[]` | No | — |
| `external_id` | `string` | No | — |
| `site` | `string` | No | — |
| `url` | `string` | No | — |
| `updater_email` | `string` | No | Who to credit the change to in the task history. |

**Output**

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

> [accordion] task full type
>
> ```ts theme={null}
> {
>   id: number,
>   local_task_id?: number | null,
>   project_id?: number | null,
>   created_at?: string | null,
>   updated_at?: string | null,
>   closed_at?: string | null,
>   deleted_at?: string | null,
>   title?: string | null,
>   description?: string | null,
>   status?: string | null,
>   status_id?: number | null,
>   priority?: string | null,
>   priority_id?: number | null,
>   site?: string | null,
>   url?: string | null,
>   tag_names?: string[] | null,
>   external_id?: string | null,
>   requester_email?: string | null,
>   attachments?: {
>     id: number,
>     file_name?: string | null,
>     url?: string | null,
>     created_at?: string | null
>   }[] | null,
>   screenshot_url?: string | null,
>   secret_link?: string | null,
>   admin_link?: string | null,
>   assigned_to?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   requester?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   } | null,
>   project_name?: string | null,
>   due_at?: string | null,
>   assignee_ids?: number[] | null,
>   assignees?: {
>     id?: number | null,
>     email?: string | null,
>     display_name?: string | null
>   }[] | null,
>   assigned_to_id?: number | null,
>   requester_id?: number | null,
>   column_id?: number | null,
>   metadata?: Record<string, any> | null
> }
> ```

***

### uploadAttachment

`tasks.uploadAttachment`

Upload a file to a task (a URL, or base64 for a small file).

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.tasks.uploadAttachment({ project_id: 552668, task_id: 98765, file: { url: 'https://example.com/report.pdf' } });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project_id` | `number` | Yes | BugHerd project id. |
| `task_id` | `number` | Yes | Global task id (the `id` field, not the #number shown in the UI). |
| `file` | `string \| object` | Yes | A file: a public URL to it, or \{url, filename?, contentType?}, or \{base64, filename?, contentType?} for a small one. |

`POST /projects/{project_id}/tasks/{task_id}/attachments/upload?file_name=...` with the file as the raw request body. BugHerd's reference shows multipart, but the live API stores a multipart upload without its file name. BugHerd allows about 30 seconds per upload; use `tasks.createAttachment` with a URL for large files.

> [accordion] file full type
>
> ```ts theme={null}
> string | {
>   url: string,
>   filename?: string,
>   contentType?: string
> } | {
>   base64: string,
>   filename?: string,
>   contentType?: string
> }
> ```

**Output**

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

> [accordion] attachment full type
>
> ```ts theme={null}
> {
>   id: number,
>   file_name?: string | null,
>   url?: string | null,
>   created_at?: string | null
> }
> ```

***

## Users

### list

`users.list`

List everyone in the organization, members and guests.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.users.list({ updated_since: '2026-11-01T00:00:00Z' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `updated_since` | `string` | No | Only records updated after this ISO 8601 timestamp. |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] users full type
>
> ```ts theme={null}
> {
>   id: number,
>   email?: string | null,
>   display_name?: string | null,
>   avatar_url?: string | null
> }[]
> ```

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

***

### listGuests

`users.listGuests`

List guests (clients) across all projects.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.users.listGuests({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] users full type
>
> ```ts theme={null}
> {
>   id: number,
>   email?: string | null,
>   display_name?: string | null,
>   avatar_url?: string | null
> }[]
> ```

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

***

### listMembers

`users.listMembers`

List team members (not guests).

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.users.listMembers({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] users full type
>
> ```ts theme={null}
> {
>   id: number,
>   email?: string | null,
>   display_name?: string | null,
>   avatar_url?: string | null
> }[]
> ```

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

***

### listProjects

`users.listProjects`

List the projects a user belongs to.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.users.listProjects({ user_id: 4561, is_active: true });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `user_id` | `number` | Yes | BugHerd user id. |
| `is_active` | `boolean` | No | Only active or inactive projects. |
| `created_since` | `string` | No | Only records created after this ISO 8601 timestamp. |
| `page` | `number` | No | Page number, from 1. Pages hold up to 100 records. |

**Output**

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

> [accordion] projects full type
>
> ```ts theme={null}
> {
>   id: number,
>   name?: string | null,
>   created_at?: string | null,
>   tasks?: boolean | null,
>   devurl?: string | null,
>   is_active?: boolean | null,
>   is_public?: boolean | null,
>   has_custom_columns?: boolean | null,
>   guests_see_guests?: boolean | null,
>   owner_name?: string | null,
>   sites?: string[] | null,
>   allow_guests_change_task_status?: boolean | null,
>   assign_guests?: boolean | null,
>   allow_project_summary_email?: boolean | null,
>   allow_task_done_email?: boolean | null,
>   allow_project_owner_notifications?: boolean | null,
>   change_guest_default_column?: boolean | null,
>   members?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   guests?: {
>     id: number,
>     email?: string | null,
>     display_name?: string | null,
>     avatar_url?: string | null
>   }[] | null,
>   columns?: {
>     id: number,
>     name?: string | null,
>     project_id?: number | null,
>     position?: number | null,
>     tasks_count?: number | null,
>     created_at?: string | null,
>     updated_at?: string | null
>   }[] | null
> }[]
> ```

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

***

## Webhooks

### create

`webhooks.create`

Subscribe a URL to one BugHerd event, for one project or all of them.

**Risk:** `write`

```ts theme={null}
await corsair.bugherd.api.webhooks.create({ target_url: 'https://example.com/bugherd', event: 'task_create', project_id: 552668 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `target_url` | `string` | Yes | Where BugHerd POSTs the event. |
| `event` | `project_create \| task_create \| task_update \| comment \| task_destroy` | Yes | — |
| `project_id` | `number` | No | Leave out for every project. |

**Output**

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

> [accordion] webhook full type
>
> ```ts theme={null}
> {
>   id: number,
>   target_url?: string | null,
>   event?: string | null,
>   project_id?: number | null,
>   project_name?: string | null,
>   success_count?: number | null,
>   error_count?: number | null,
>   last_error_code?: number | null,
>   last_error_at?: string | null,
>   first_error_at?: string | null,
>   first_success_at?: string | null,
>   last_success_at?: string | null
> }
> ```

***

### delete

`webhooks.delete`

Remove a webhook subscription. Cannot be undone.

**Risk:** `destructive`

```ts theme={null}
await corsair.bugherd.api.webhooks.delete({ webhook_id: 22649 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `webhook_id` | `number` | Yes | — |

**Output**

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

***

### list

`webhooks.list`

List the organization webhooks with their delivery counts.

**Risk:** `read`

```ts theme={null}
await corsair.bugherd.api.webhooks.list({});
```

**Input:** *empty object*

**Output**

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

> [accordion] webhooks full type
>
> ```ts theme={null}
> {
>   id: number,
>   target_url?: string | null,
>   event?: string | null,
>   project_id?: number | null,
>   project_name?: string | null,
>   success_count?: number | null,
>   error_count?: number | null,
>   last_error_code?: number | null,
>   last_error_at?: string | null,
>   first_error_at?: string | null,
>   first_success_at?: string | null,
>   last_success_at?: string | null
> }[]
> ```

***


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