> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/bug-reports/openapi.json](/docs/api/bug-reports/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Bug reports

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

A bug report sends a problem straight to the Kenso team. Your app, your support chat or an AI agent files one with the user's own description, optional diagnostics and up to 10 files. Each person can file 20 reports a day and each workspace 50.

Workspace and account. 2 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/bug-reports/openapi.json](/docs/api/bug-reports/openapi.json).

- `POST /v1/bug-reports` - Create a bug report (`bug-reports.create`): [/docs/api/bug-reports/create.md](/docs/api/bug-reports/create.md)
- `POST /v1/bug-reports/{bugReportId}/notes` - Add a note to a bug report (`bug-reports.notes-create`): [/docs/api/bug-reports/notes-create.md](/docs/api/bug-reports/notes-create.md)

## Create a bug report

`POST /v1/bug-reports` - operationId `bug-reports.create`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 20 requests a day per user; 50 requests a day per workspace |

Sends a bug report to the Kenso team. Kenso keeps the description word for word, attaches every file and answers
202 with `status` set to `received` and the report's opaque `id`. The response carries no issue
id or link. For 24 hours the member who filed the report can add a note to it with
`POST /v1/bug-reports/{bugReportId}/notes`.

Send the body as `multipart/form-data`. Two fields are required:

- `description`: the user's own words, from 1 to 10,000 characters.
- `source`: where the report comes from: `app_form`, `support_chat`, `ken_agent`, or
`mcp` for an AI assistant connected to Kenso, such as Claude or ChatGPT.

The other fields are optional:

- `title`: at most 120 characters. Without it, Kenso uses the first line of `description`, cut to 80
characters.
- `summary`: at most 10,000 characters, usually written by an agent: steps to reproduce, the expected result
and the actual one.
- `clientName`: the AI assistant's name, at most 100 characters.
- `pageUrl`: the page the user was on, at most 2,000 characters.
- `userAgent`: the browser's user agent, at most 500 characters.
- `diagnostics`: at most 20,000 characters of JSON text.
- `transcript`: a conversation as plain text, at most 60,000 characters.
- `supportAttachmentIds`: repeat the field for up to 5 files the caller uploaded to the support chat.
- `files`: repeat the field for up to 10 files of at most 25 MB each. Kenso refuses programs and scripts by
extension, such as .exe, .js, .sh, .py, .html and .svg, disk images such as .iso, and macro Office files such
as .xlsm.

Each report counts once toward the caller's daily limit of 20 and the workspace's daily limit of 50. A report
that Kenso could not file does not count.

Errors:

- `400 validation_failed`: a field is missing, too long or not allowed. The error detail names the field.
- `413 validation_failed`: a file is larger than 25 MB, or the whole request is too large.
- `429 quota_exceeded`: the caller or the workspace reached its daily limit. Wait for the seconds in
`Retry-After`, or until `quotaResetAt`.
- `503 service_unavailable`: Kenso could not file the report or upload a file, so nothing was filed. Try
again later.

Open to any workspace member, Client seats included.

Needs the `bug_reports` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/bug-reports/POST/v1/bug-reports)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`multipart/form-data`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Description` | string | yes | What went wrong, in the user's own words. Required, from 1 to 10000 characters, and filed exactly as sent. |
| `Title` | string | no | A short title for the report, at most 120 characters. When omitted, Kenso uses the first line of `description`, cut to 80 characters. |
| `Summary` | string | no | A summary written by an AI agent: the steps to reproduce, the expected result and the actual result. At most 10000 characters. |
| `Source` | string | yes | Where the report was written: `app_form` (the bug report form in the Kenso app), `support_chat` (the support chat), `ken_agent` (Ken) or `mcp` (an AI assistant connected to Kenso). Required. |
| `ClientName` | string | no | The name of the AI assistant that filed the report, such as Claude, ChatGPT or Cursor. At most 100 characters. |
| `PageUrl` | string | no | The URL of the page the user was on, at most 2000 characters. |
| `UserAgent` | string | no | The user agent string of the user's browser, at most 500 characters. |
| `Diagnostics` | string | no | Diagnostic data as JSON text, at most 20000 characters. Kenso formats valid JSON for reading and keeps any other text as sent. |
| `Transcript` | string | no | The conversation that led to the report, as plain text with one turn per paragraph (`User: ...` or `Assistant: ...`). At most 60000 characters. |
| `SupportAttachmentIds` | array of string | no | Ids of support chat attachments the calling user uploaded, each 32 hexadecimal characters. Send the field once per id, for at most 5 ids. |
| `Files` | array of string (binary) | no | Files to attach, one form field per file: at most 10 files of at most 25 MB (26,214,400 bytes) each. Kenso refuses empty files and programs or scripts by extension (such as .exe, .js, .sh, .html or .svg), and accepts a file with no extension. |

### Response 202

`data` is a `BugReportReceipt`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The report's opaque id. Send it to `POST /v1/bug-reports/{bugReportId}/notes` to add a note to the report: only the member who filed it, in the same workspace, within 24 hours. Treat it as an opaque string of up to a few hundred characters. Omitted only when the caller has no Kenso user. |
| `status` | string | Always `received`: the Kenso team has the report. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/bug-reports" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -F 'Description=string' \
  -F 'Title=string' \
  -F 'Summary=string' \
  -F 'Source=string' \
  -F 'ClientName=string' \
  -F 'PageUrl=https://example.com' \
  -F 'UserAgent=string' \
  -F 'Diagnostics=string' \
  -F 'Transcript=string' \
  -F 'SupportAttachmentIds=["string"]' \
  -F 'Files=["<binary>"]'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": "string",
    "status": "string"
  }
}
```

## Add a note to a bug report

`POST /v1/bug-reports/{bugReportId}/notes` - operationId `bug-reports.notes-create`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 20 requests a day per user; 50 requests a day per workspace |

Adds the user's note to a bug report they filed, for the Kenso team to read with the report. Use the `id`
from the report's receipt as `bugReportId`. Answers 201 with `status` set to `received`.

Send a JSON body with one required field, `note`: the user's own words, from 1 to 10,000 characters once
leading and trailing spaces are trimmed.

Only the member who filed the report can add a note, in the same workspace, within 24 hours of filing. Each note
counts once toward the same daily limits as reports: 20 for the caller and 50 for the workspace. A note that Kenso
could not add does not count.

Errors:

- `400 validation_failed`: `note` is missing, blank or longer than 10,000 characters.
- `404 not_found`: the id is unknown, expired after 24 hours, or belongs to another member or workspace.
- `429 quota_exceeded`: the caller or the workspace reached its daily limit. Wait for the seconds in
`Retry-After`, or until `quotaResetAt`.
- `503 service_unavailable`: Kenso could not add the note. Try again later.

Open to any workspace member, Client seats included.

Needs the `bug_reports` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/bug-reports/POST/v1/bug-reports/%7BbugReportId%7D/notes)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `bugReportId` | path | string | yes |  |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string | yes | What the user was doing or anything else they want to add, in their own words. Required, from 1 to 10000 characters once leading and trailing spaces are trimmed. |

### Response 201

`data` is a `BugReportNoteReceipt`.

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Always `received`: the Kenso team has the note with the report. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/bug-reports/01JC8Z3K6Q2W4M7N9P5R1T3V5X/notes" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "string"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "status": "string"
  }
}
```

All resources: [/docs.md](/docs.md).
