# Giving feedback

## Summary

A signed-in person can send feedback to the Talewright team: a bug report, an
idea or anything else. A report holds a message, technical context about where
the person was in the app, and up to five images such as screenshots.

Reports are only saved. No email is sent, nothing answers a report, and a
report cannot be read back, changed or withdrawn through the API. The people
who run Talewright read the reports and decide what to do with them.

Feedback belongs to the account, not to an organization. Organization roles
play no part.

## Who can do what

| Action | Signed-out visitor | Signed-in person | API key or connected app |
| --- | --- | --- | --- |
| Send a report | No | Yes, verified or not, in any organization or in none | No: `FORBIDDEN`, reason `SESSION_REQUIRED` |
| Read a report back, list reports, change or withdraw one | No | No | No |
| Read someone else's report | No | No | No |

- Owners and admins do not see the reports their members send.
- Sending feedback is not an MCP tool. No credential scope grants it.

## How it works

### What a report holds

- **`kind`**: `bug`, `idea` or `other`.
- **`message`**: 1 to 5,000 characters. Line breaks are kept. Spaces and line
  breaks at the start and the end are removed.
- **`context`**: technical context the browser adds. See below. Optional.
- **`organizationID` and `workspaceID`**: the organization and workspace the
  person had open. Both are optional.
- **`attachments`**: up to 5 images. Optional.
- Talewright adds who sent the report and when.

### The technical context

The context is sent by the browser with the report and is stored as sent.
Every field is optional. What the app puts into each field is listed under
[What the app sends along](#what-the-app-sends-along).

| Field | What it is | Limit |
| --- | --- | --- |
| `route` | The page the person was on. | Up to 500 characters |
| `appVersion` | The version of the app. | Up to 100 characters |
| `userAgent` | The browser and device. | Up to 500 characters |
| `language` | The browser's language. | Up to 35 characters |
| `viewport` | `width` and `height` of the window, in pixels. | Whole numbers |
| `recentActions` | The person's latest actions, oldest first. | Up to 20 |

- Each recent action has `kind` (`page` or `command`), `name` (the name of
  the page opened or the command run, 1 to 200 characters) and optionally
  `at`, the time.
- Recent actions are names of pages and commands. They never hold the content
  of a file.
- Text values are on one line and are trimmed.
- A field the context does not know is refused with `422 VALIDATION_FAILED`.
  Nothing else can be put into the context.
- The whole context holds at most 16 KiB as JSON.

### The organization and workspace

- `workspaceID` is recorded when the sender can open that workspace. Its
  organization is then recorded too, whatever `organizationID` says.
- `organizationID` is recorded when the sender is a member of that
  organization.
- An ID of a place the sender cannot open is left out. The report is still
  saved, without it. It is not an error.
- So a report never names an organization or workspace of someone else.

### Images

- An image is sent inside the report, as base64 text (the standard alphabet,
  with padding) in `attachments`.
- PNG, JPEG, WebP and GIF are accepted. The type is judged by the image's
  bytes. There is no file name and no declared type.
- Each image holds at most 5 MiB.
- Anything else is refused: a PDF, an SVG, a video, a text file, an empty
  attachment.
- One refused image refuses the whole report. Nothing of it is saved.
- Every image is scanned for malware after the report is saved. The Talewright
  team can open an image only once it scanned clean. An image the scan flags
  is deleted.
- The images are not files of a workspace or the organization folder. They
  do not appear in any listing, have no public link, and nothing serves them
  to customers.

### Sending

- The report is sent in one request and saved whole or not at all.
- The answer is `201` with the report's `id`. The `id` is a receipt. Nothing
  can be looked up with it through the API.
- There is no `requestID`. Sending the same report twice saves two reports.
- A person sends at most 10 reports in one hour. The eleventh is refused with
  `429 RATE_LIMITED` until the hour ends.
- Refused reports count toward the 10 as well.
- Each person has their own count. One person's reports never use up
  another's.
- No email is sent to the person or to anyone else.
- Sending feedback is not recorded in the audit trail.

### When the sender deletes their account

- The reports stay, with their message, context and images.
- They no longer name the person. The link between a report and the account
  is cut the moment the account is deleted.
- See [Deleting an account](delete-account.md#what-deletion-keeps).

### When an organization or workspace is deleted for good

- The reports stay.
- They no longer name that organization or workspace.

## In the app

### Opening the dialog

- "Give feedback" is in the sidebar, under "Search".
- With the sidebar collapsed to icons it is the speech bubble above the
  account menu. Its tooltip reads "Give feedback".
- On a narrow window it is in the navigation that "Open navigation" opens.
- The command palette offers "Give feedback" as well.
- All of them open the dialog "Give feedback", on any page of the app.

### Writing a report

1. Choose the "Type": "Bug", "Idea" or "Other". "Bug" is chosen at first.
2. Write the "Message". It takes up to 5,000 characters.
3. Attach images if you like. Choose "Attach images", drop image files
   anywhere in the window while the dialog is open, or paste a screenshot
   from the clipboard.
4. Choose "Send".

- "Send" with an empty message sends nothing. The field says "Write a
  message, up to 5,000 characters."
- Attached images are listed under "Attached images" with their name and
  size. "Remove {name}" takes one out.
- Beside "Attach images" the dialog counts the images, such as "2 of 5".
  With no image it reads "Or drop or paste a screenshot".
- With five images attached, "Attach images" is disabled.
- An image the report cannot take is not attached, and the dialog says why.
  See [Images the dialog leaves out](#images-the-dialog-leaves-out).
- Text pasted from the clipboard goes into the message as usual. A paste
  attaches an image only when the clipboard holds an image and no text.
- After sending, the dialog closes and the app says "Thanks - feedback
  sent". The dialog is empty the next time it opens.
- While a report is being sent, the dialog cannot be closed.

### Closing without sending

- "Cancel", the close button and Escape close the dialog. What you wrote,
  the type you chose and the images you attached are kept.
- Opening the dialog again shows them, on any page.
- The kept report is gone once it is sent, when the page is reloaded, when
  you sign out, and when another account signs in in the same tab.
- It is kept in the memory of the open browser tab. Another browser tab or
  window starts empty.

### Images the dialog leaves out

The dialog checks each image before it is attached and names the ones it
left out:

| Message | When |
| --- | --- |
| "{name} is not a PNG, JPEG, WebP or GIF image." | The file is of another type, such as a PDF or a video. |
| "{name} is empty." | The file holds no bytes. |
| "{name} is larger than 5 MiB." | The file is over 5,242,880 bytes. |
| "{name} was not attached: a report takes up to 5 images." | Five images are attached already. |

- The other images of the same choice, drop or paste are attached.
- The messages go away with the next image attached or removed, and when
  the dialog opens again.
- The dialog goes by the type the browser gives the file. The API judges
  the bytes, so a PDF renamed to `.png` is attached and then refused when
  the report is sent.

### What the app sends along

The dialog says "Includes technical details". "See what is sent" beside it
opens the list "Technical details" with every value. The values are read at
the moment the dialog opens, and exactly these are sent:

| In the list | Sent as | What the app puts there |
| --- | --- | --- |
| "Page" | `context.route` | The open page as its pattern, with names in place of IDs, such as `/w/$workspaceID/files/$fileID`. Never the address itself, and never its search. |
| "App version" | `context.appVersion` | The version of the app. Left out when the app has none, as in local development. |
| "Browser" | `context.userAgent` | The browser's user agent, up to 500 characters. |
| "Language" | `context.language` | The browser's language, such as `en-US`. |
| "Window" | `context.viewport` | The window's width and height, such as "1440 × 900". |
| "Workspace" | `workspaceID` | The open workspace, shown by its name. Left out on pages outside a workspace, such as Settings. |
| "Organization" | `organizationID` | The open workspace's organization, or the organization whose settings are open, shown by its name. |
| "Latest actions" | `context.recentActions` | The last pages opened and commands run, up to 20, oldest first, each with its time. "None" when there are none. |

- A page among the latest actions reads "Opened" and its pattern, like
  "Page" above. A command reads "Ran" and its ID, such as `files.rename` or
  `feedback.open`.
- What a command acted on is not recorded: no file, no folder, no value.
- No file name, folder name, search text or other content is part of the
  technical details.
- Opening a folder, searching, filtering and sorting change only the search
  of the address. They are not recorded as pages.
- A command counts when it is run from the command palette, a keyboard
  shortcut, a menu or a button that runs it. Opening the dialog is itself
  the command `feedback.open`, so it is usually the last action listed.
- The latest actions are kept in the memory of the open browser tab. The
  list starts empty after a reload and when another account signs in.
  Nothing of it is stored in the browser.
- The app adds nothing else to a report: no screenshot of its own and no
  analytics identifier.

### When sending is refused

The dialog stays open with everything you wrote and attached, and says why:

| Message | When |
| --- | --- |
| "You have reached the limit of 10 reports in an hour. You can send more in 12 minutes." | `429 RATE_LIMITED`: the eleventh report within the hour. The time is the wait the API gives; without one it reads "later". |
| "An image is larger than 5 MiB. Remove it or attach a smaller one." | `413 PAYLOAD_TOO_LARGE`. |
| "Only PNG, JPEG, WebP and GIF images can be sent. Remove the other files." | `415 UNSUPPORTED_MEDIA_TYPE`: a file whose bytes are not the image its name says. |
| "Write a message, up to 5,000 characters.", under the field | `422 VALIDATION_FAILED` on `message`. |
| "A report takes up to 5 images." | `422 VALIDATION_FAILED` on `attachments`. |
| "Sending took too long and nothing was sent. Try smaller or fewer images." | `503 TIMEOUT`. |
| "Could not send your feedback. Try again." | The server failed, or the app could not reach it. |

- Any other refusal shows the API's own message.
- Editing the report clears the message. "Send" tries again.

## For agents

Sending feedback is for a person in a browser. It is not an MCP tool.

| Operation | Capability ID | Access | MCP |
| --- | --- | --- | --- |
| `POST /v1/me/feedback` | `account.feedback.send` | session only | none |

- A valid bearer token is refused with `403 FORBIDDEN`, `details.reason`
  `SESSION_REQUIRED`.
- The request carries the session cookie and an `Origin` header equal to the
  app's origin, as every change from a browser session does. See
  [The REST API](../agents/rest-api.md#signing-in-with-a-browser-session).
- The body is JSON, sent with `Content-Type: application/json`. It may hold
  up to 35,018,076 bytes, more than other operations take, to make room for
  five images.

```json
{
  "kind": "bug",
  "message": "The upload button does nothing after I pick a file.",
  "context": {
    "route": "/w/0192e7c4-0b10-7a11-9c01-000000000001/files",
    "appVersion": "2026.11.15",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15",
    "language": "en-US",
    "viewport": { "width": 1440, "height": 900 },
    "recentActions": [
      { "kind": "page", "name": "Files", "at": "2026-11-15T09:00:00Z" },
      { "kind": "command", "name": "files.upload", "at": "2026-11-15T09:00:12Z" }
    ]
  },
  "organizationID": "0192a6c1-5a0e-7c33-b0de-2f6f0d1c9a10",
  "workspaceID": "0192e7c4-0b10-7a11-9c01-000000000001",
  "attachments": ["iVBORw0KGgoAAAANSUhEUgAA..."]
}
```

The answer is `201`:

```json
{ "id": "0192f4b0-7d11-7e55-9a10-3c2f1d0e9b77" }
```

- Only `kind` and `message` are required.
- The example shows what the API accepts. The app itself sends `route` and
  the names of pages as patterns such as `/w/$workspaceID/files`, and the
  names of commands as their IDs. See
  [What the app sends along](#what-the-app-sends-along).
- There is no operation that lists, reads, changes or deletes reports.

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| A report names a workspace the sender was removed from a moment ago | `201`. The report is saved without the workspace. | A place the sender cannot open is left out, and feedback is never lost over it. |
| A report names another organization's ID | `201`. The report is saved without it. | The same rule. Nothing tells whether the ID exists. |
| A report names a workspace and another organization than the workspace's | The workspace and its own organization are recorded. | The workspace decides. |
| A report names an organization that is deleted and waiting out its 30 days | It is saved without the organization. | A deleted organization cannot be opened. |
| The sender belongs to no organization | `201`. | Feedback belongs to the account. |
| The sender's email is not verified | `201`. | Feedback needs no verified email. |
| The message is only spaces | `422 VALIDATION_FAILED` on `message`. | After trimming it is empty. |
| The context holds a field it does not know, such as `clipboard` | `422 VALIDATION_FAILED`. Nothing is saved. | Only the known fields are taken. |
| 21 recent actions are sent | `422 VALIDATION_FAILED` on `context.recentActions`. | At most 20. |
| Every field of the context is within its limit, but the whole is over 16 KiB | `422 VALIDATION_FAILED` on `context`. | Characters outside ASCII take several bytes each. |
| Six images are sent | `422 VALIDATION_FAILED` on `attachments`. Nothing is saved. | At most 5. |
| One of three images is a PDF | `415 UNSUPPORTED_MEDIA_TYPE`. Nothing is saved, not even the two good images. | A report is saved whole or not at all. |
| An image file is renamed from `.pdf` to `.png` before it is attached | `415 UNSUPPORTED_MEDIA_TYPE`. | The type is judged by the bytes. |
| An image of 5 MiB and one byte | `413 PAYLOAD_TOO_LARGE`, `details.limitBytes` 5242880. | Each image holds at most 5 MiB. |
| An attachment is not base64 | `422 VALIDATION_FAILED` on `attachments`. | Images are sent as base64 text. |
| The same report is sent twice | Two reports are saved. | There is no `requestID`. |
| Ten reports were refused for a wrong field, then a correct one is sent within the hour | `429 RATE_LIMITED`. | Refused reports count. |
| A connection is slow and sending takes more than 30 seconds | `503 TIMEOUT`. Nothing is saved. | Every request has 30 seconds. Send smaller or fewer images. |
| An image carries malware | The report is saved. The image is deleted after the scan and the team cannot open it. | Images are scanned before anyone opens them. |
| The sender deletes their account a minute later | The report stays and no longer names them. | See [Deleting an account](delete-account.md#what-deletion-keeps). |
| In the app, the dialog is closed with Escape halfway through a report | The text, the type and the images are kept. The dialog shows them when it opens again. | Closing by accident loses nothing. |
| In the app, the page is reloaded with a report half written | The report is gone. | It is kept in the memory of the open browser tab only. |
| In the app, a sixth image is dropped on the dialog | It is not attached. The dialog says "{name} was not attached: a report takes up to 5 images." | The dialog checks before the API would refuse the whole report. |
| In the app, a text is pasted while the dialog is open | It goes into the field that has the cursor. Nothing is attached. | Only a clipboard with an image and no text attaches. |
| In the app, a file is dropped beside the dialog, on the dimmed page | It is attached to the report, or left out with a message. It is not uploaded to the open folder. | While the dialog is open, every dropped file is for the report. |
| In the app, the dialog is opened on a file's page | "Page" reads `/w/$workspaceID/files/$fileID`. The file's ID and name are not sent. | Pages are named by their pattern. |
| In the app, someone signs out and another person signs in in the same tab | The half-written report and the latest actions of the first person are gone. | Neither outlives the account they belong to. |
| In the app, the report is refused with `429` | The dialog stays open with the report and says when more can be sent. | Nothing written is lost to the limit. |

## Errors

| Code | HTTP | Meaning here | What to do |
| --- | --- | --- | --- |
| `UNAUTHENTICATED` | 401 | "Authentication required". No live session. | Sign in. |
| `FORBIDDEN` | 403 | Reason `SESSION_REQUIRED`: a credential tried to send feedback. | A person sends it in a browser. |
| `FORBIDDEN` | 403 | "Forbidden". The `Origin` header is not the app's origin. | Send the request from the app. |
| `PAYLOAD_TOO_LARGE` | 413 | An image is over 5 MiB (`details.limitBytes` 5242880), or the whole body is over its limit (`details.limitBytes` 35018076). | Send a smaller image, or fewer. |
| `UNSUPPORTED_MEDIA_TYPE` | 415 | "attachments must be PNG, JPEG, WebP or GIF images": an image's bytes are another type. Or the body was not sent as `application/json`. | Attach a PNG, JPEG, WebP or GIF. |
| `VALIDATION_FAILED` | 422 | `details.field` `message`: "message must be 1 to 5000 characters". | Shorten the message, or write one. |
| `VALIDATION_FAILED` | 422 | `details.field` `context`, `context.route`, `context.appVersion`, `context.userAgent`, `context.language` or `context.recentActions`: a value is too long, holds a control character, there are more than 20 actions, or the context is over 16 KiB. | Send less context. |
| `VALIDATION_FAILED` | 422 | `details.field` `attachments`: more than 5 images, or one that is not base64. | Attach at most 5 images, as base64. |
| `VALIDATION_FAILED` | 422 | No `details.field`: `kind` is not `bug`, `idea` or `other`, the context holds an unknown field, or the body is not the expected JSON. | Correct the request. |
| `RATE_LIMITED` | 429 | "Too many attempts; try again later". More than 10 reports in an hour. `details.retryAfterSeconds` and `Retry-After` give the wait. | Wait that long. |
| `TIMEOUT` | 503 | The request took more than 30 seconds. Nothing was saved. | Send smaller or fewer images. |
| `INTERNAL` | 500 | Something failed on Talewright's side, such as storing an image. Nothing was saved. | Try again later. |

See [Errors](../reference/errors.md) for the shape of every error.

## Limits

| What | Limit |
| --- | --- |
| Message | 1 to 5,000 characters after trimming; line breaks allowed |
| Kinds | `bug`, `idea`, `other` |
| Context, as JSON | Up to 16 KiB |
| `route`, `userAgent` | Up to 500 characters each |
| `appVersion` | Up to 100 characters |
| `language` | Up to 35 characters |
| Recent actions | Up to 20; each name 1 to 200 characters |
| Images on one report | Up to 5 |
| Size of one image | Up to 5 MiB, which is 5,242,880 bytes |
| Image types | PNG, JPEG, WebP, GIF |
| Body of a report | Up to 35,018,076 bytes |
| Reports sent by one person | 10 in 1 hour, refused ones included |

- The hour starts at the first report. Reports refused during it do not make
  it longer.

See also [Limits](../reference/limits.md#feedback).

## Questions and answers

**Who reads my feedback?**
The people who run Talewright. Nobody in your organization sees it, not even
owners and admins.

**Will I get an answer?**
No. A report is saved and read. Nothing answers it, and no email is sent.

**Can I see or edit what I sent?**
No. A report cannot be read back, changed or withdrawn.

**Where do I give feedback?**
Choose "Give feedback" in the sidebar, under "Search", or run "Give feedback"
from the command palette.

**What technical information goes along with my report?**
What the browser adds as context: the page you were on, the app's version,
your browser and device, your language, the size of the window, and the names
of the last pages you opened and commands you ran, up to 20. The app also
names the workspace and organization you had open. In the dialog, "See what
is sent" lists every value.

**Does the report say which file I was looking at?**
No. The app names a page by its pattern, such as
`/w/$workspaceID/files/$fileID`, without the IDs in the address.

**I closed the dialog by accident. Is my text gone?**
No. Open "Give feedback" again and it is there, with the images. It is gone
after a reload, after signing out, or once it is sent.

**Does feedback include the content of my files?**
No. The context holds names of pages and commands only. A file's content is
part of a report only when you attach an image of it yourself.

**Can I attach a screenshot?**
Yes, up to 5 images of at most 5 MiB each: PNG, JPEG, WebP or GIF. In the
app, choose "Attach images", drop the files on the window or paste a
screenshot.

**Can I attach a PDF or a video?**
No. Only PNG, JPEG, WebP and GIF images.

**Do I need a verified email to send feedback?**
No.

**Can an agent send feedback for me?**
No. Sending feedback refuses API keys and connected apps and is not an MCP
tool.

**How much feedback can I send?**
10 reports in one hour. After that the dialog says when you can send more,
and keeps what you wrote.

**What happens to my feedback when I delete my account?**
It stays, but it no longer names you.

## Related pages

- [Deleting an account](delete-account.md)
- [Sign-in and sessions](sign-in-and-sessions.md)
- [The REST API](../agents/rest-api.md)
- [Roles and permissions](../reference/permissions.md#your-own-account)
- [Errors](../reference/errors.md)
- [Limits](../reference/limits.md#feedback)

