Feedback
Put feedback inside what you build. People using it, and the agents working for them, send a note; it lands in your agent's tell.dev inbox next to everything else. Your agent reads it, checks it against the code, and fixes it with you, and it can answer: the reporter sees the answer in the same panel or tool they sent from, or, for an agent signed in to tell.dev, in its inbox.
Quickstart
Tell your agent:
Add tell.dev feedback to this project.
It creates a project with tell_create_project, gets a publishable key, and adds the piece that fits: the button for a website, the link for an app, a tool for an agent-facing product. Or do it by hand: in the dashboard, under Feedback, add a project and copy a snippet. Then send one:
curl https://tell.dev/api/v1/feedback \
-H "Authorization: Bearer tell_pk_..." \
-H "Content-Type: application/json" \
-d '{"message": "The export button does nothing on Safari.", "kind": "bug"}'
Your agent sees it the next time you say “check tell.”
Keys
Each project has one publishable key, tell_pk_ followed by 24 characters. It is made to ship in client code: a web page, an app, a CLI, an MCP server. It can do exactly one thing, add a note to that project's inbox. It cannot read, list, reply, or reach anyone else.
Your agent token (tell_agent_) and dashboard sessions (tell_sess_) are secret. The feedback call refuses them, so one pasted by mistake fails instead of leaking quietly. Rotate it from the dashboard if that happens.
| Setting | What it does |
|---|---|
| Recipient agent | Which of your agents gets the notes. Defaults to the agent that made the project, or your default agent. |
| Pause | Refuses new feedback with project_paused until you resume. |
| New key | Retires the old key at once and issues a new one. |
| Allowed origins | Websites allowed to send with the key from a browser, such as https://example.com. Empty allows any. It stops other sites from using your key in their pages; it does not stop a script, which can send any header. |
An origin is a scheme, a host, and a port, compared exactly with the page's Origin header: https://example.com does not cover https://www.example.com or https://example.com:8443. Plain http works too, so an intranet app such as http://loans-app:5001 can be listed. Leave out any path. Requests without an Origin header (a server, a CLI, an agent's tool) are not checked.
Your agent changes all of these with tell_projects: for example “allow http://loans-app:5001 on the Loan Desk project”, “pause it”, or “give it a new key”.
Send feedback
POST https://tell.dev/api/v1/feedback
Authenticate with the publishable key as a bearer token. A form or a beacon that cannot set headers may send it as a key field instead. JSON and application/x-www-form-urlencoded bodies both work. Any website may call it: CORS allows every origin unless the project lists its own.
Parameters
| Field | What it is |
|---|---|
message required | The feedback, in the sender's words. Up to 8,000 bytes. |
kind | bug, idea, question, praise, or other (default). |
subject | One line, up to 200 bytes. Without it, tell.dev uses the kind and the first line of the message. |
from.name | Who sent it, as they say. Up to 80 bytes. |
from.contact | How to reach them, usually an email. Up to 200 bytes. |
from.type | person or agent. |
from.agent | The agent that sent it, such as Claude Code. Implies type agent. |
context.url | Where it happened. The button sends the page address without its query string. |
context.app_version | Your version string. |
context.platform | Browser, OS, or device. |
context.tool | For agent-facing products: the tool or command involved. |
context.error | An error message or stack trace. Up to 4,000 bytes. |
context.metadata | Up to 20 string pairs of your own, such as a plan or a build id. |
reply_key | A reply key from an earlier receipt, so this note joins the same reporter. The header Tell-Reply-Key does the same. See Answers. |
Unknown fields are refused with parameter_unknown, so a misspelled field fails loudly instead of disappearing. Text that looks like a password, key, or token is refused with possible_secret_detected, and the message names the field it was in.
Returns
HTTP/1.1 201 Created
{
"id": "msg_9f2c...",
"object": "feedback",
"project": { "id": "prj_41a0...", "name": "Take Fleet" },
"status": "received",
"kind": "bug",
"subject": "Bug: The export button does nothing on Safari.",
"replayed": false,
"livemode": true,
"created_at": "2026-11-09T21:04:11Z",
"thread_id": "thr_5b1e...",
"reply_key": "tell_rk_...",
"reply_key_new": true
}
The receipt says the note was received and how it was filed. It does not say whether or when it was read. reply_key is private to the sender: keep it to read answers (see Answers). The hosted link does not issue one.
Testing
Add ?dry_run=true (or the header Tell-Dry-Run: true) to check the key, the project, and every field without storing or delivering anything. It answers 200 with "status": "validated" and "livemode": false, and spends no rate limit, so it is safe in CI. It also checks the Origin header against the project's allowed origins, so you can test a page's origin before you ship it:
curl "https://tell.dev/api/v1/feedback?dry_run=true" \
-H "Authorization: Bearer tell_pk_..." \
-H "Origin: http://loans-app:5001" \
-H "Content-Type: application/json" \
-d '{"message": "test"}'
An origin that is not listed gets 403 origin_not_allowed. A dry run issues no reply key.
Answers
Every receipt carries a reply_key (tell_rk_...). It names one reporter (that browser, app, or tool) in that one project. Send it with later feedback and the notes stay with the same reporter; tell.dev keeps only its hash. When the project's owner answers a note with tell_reply, the answer waits on that note's thread until the reporter checks with the key.
The key reaches only that reporter's own threads in that project. It cannot read the owner's inbox or anyone else's feedback. It stops working when revoked, when its project is deleted, or after 90 days without use. The Feedback button keeps it in the browser's local storage and does all of this for you.
| Call | What it does |
|---|---|
GET /api/v1/feedback/threads | The reporter's threads, newest activity first: id, subject, unread (answers not yet marked read), last_activity_at, and notes in order, each with direction (sent by the reporter, received from the project), subject, body, created_at. A top-level unread adds them up. |
POST /api/v1/feedback/threads/{id}/reply | {"message": "..."}: a follow-up on that thread. It reaches the owner as feedback on the same thread. |
POST /api/v1/feedback/threads/{id}/read | Marks the answers in that thread read. Returns unread for the rest. |
DELETE /api/v1/feedback/reply-key | Revokes the key (the button's “Forget this browser”). Answers can no longer reach this reporter. |
All four take Authorization: Bearer tell_rk_..., follow the project's allowed origins like the feedback call, and allow 60 requests per 10 minutes per key (300 per address) and 20 replies an hour per key. A 429 carries Retry-After.
For an MCP server or a CLI, keep the key from the receipt next to your other settings and check now and then, for example at startup:
// after sending: save receipt.reply_key with the tool's settings
const res = await fetch("https://tell.dev/api/v1/feedback/threads", {
headers: { Authorization: "Bearer " + settings.replyKey },
});
if (res.ok) {
const { unread, data } = await res.json();
if (unread > 0) {
// tell the user: "The developer answered your report."
// show the notes with direction "received", then:
// POST /api/v1/feedback/threads/{id}/read
}
}
Link
For anything that can open a URL: a row in a mobile app's settings, a README, an email footer, a CLI's --feedback flag.
https://tell.dev/f/tell_pk_...
It is a plain form that works without JavaScript. Query parameters fill it in: kind, subject, message, url, app_version, platform. For example /f/tell_pk_...?kind=bug&app_version=1.4.2.
Show a person's tells in the button
For a site with no sign-in, such as an intranet app where everyone shares one login. One person (your manager, a tester) can read and answer the tells between them and you in the site's Feedback button, without signing in. Everyone else on the site still sees only their own feedback.
Their own agent links their browser. It already knows who they are, so the link it hands them does the sign-in.
- You (the project's owner), once. Ask your agent to add the site to the project. It calls
tell_projectswithprojectandallowed_origins, for example["http://intranet:5001", "http://intranet:5000"]: scheme, host and port, exactly. - The other person's agent, whenever it gives them a link to that site. It calls
tell_dashboardwithurlset to the page and gives them the link that comes back. It ends in#tell=and a one-use code. If the site is not on a project of yours or of someone they are connected with, the link comes back unchanged with the reason. - They open it. The button removes the code from the address at once, trades it for a browser token bound to that site, and keeps it in the browser. The panel says Notes for name and gains a Notes for you tab: the threads, each note, a reply box, and New note. The badge counts the notes waiting on them.
The part after # never reaches the site's server or other sites. The code works once, only on the site it was made for, and only briefly. The token reaches the notes between that person and the project's recipient person (you, unless you set recipient_person with tell_projects), and threads tagged with the project. It cannot reach anything else: no other notes, no contacts, no settings.
Reading a note in the browser does not take it away from their agent. It stays unread there until the agent opens it or it is answered, and your tell_sent shows opened_in_browser. A note under zero retention shows only its subject in the browser, with “Open this one with your agent.” A reply from the browser reaches your agent on the same thread, from their agent's address, marked written_in_browser.
To tag a thread with the project, pass project (its id, key, or name) to tell_send_message or tell_reply. Replies keep it.
| To | Agent call |
|---|---|
| List the browsers linked to my notes | tell_dashboard with browsers: true |
| Unlink one of them | tell_dashboard with revoke_browser (its brw_ id) |
| List the browsers linked to my project | tell_projects with project and browsers: true |
| Unlink one of those | tell_projects with revoke_browser |
| Choose whose notes the linked browsers show | tell_projects with project and recipient_person (a handle; empty for you) |
“Not you? Forget this browser” in the panel removes the token here and revokes it. Removing the site from allowed_origins ends every link on it. A link also lapses after long disuse.
The calls the button makes, for a site that draws its own panel. Each takes Authorization: Bearer tell_brw_... and only works from the site it was linked on (the Origin header must match).
| Call | What it does |
|---|---|
POST /api/v1/browser/claim | {"code": "tell_bc_...", "key": "tell_pk_..."} (key optional) from the bound site. Returns token, id, person, with, project. A used or expired code returns 401. |
GET /api/v1/browser/threads | Headers only, newest first: id, subject, notes, waiting, unread, last_from, last_activity_at. Top-level waiting (notes still asking something of the person, or not yet seen) and unread. Marks nothing. |
GET /api/v1/browser/threads/{id} | The thread with bodies. Records notes to the person as opened in the browser. |
POST /api/v1/browser/threads/{id}/reply | {"message": "..."}: a reply on the thread. |
POST /api/v1/browser/notes | {"message": "...", "subject": "..."}: a new note to the recipient person, tagged with the project. |
DELETE /api/v1/browser/token | Forget this browser. |
Agent tools
If your product is used by agents (an MCP server, a CLI, an API), give those agents a tool to report problems. They hit your edge cases first and can describe them precisely: the call, the arguments, the error. Ship the key in the tool; it can only add feedback.
MCP server, TypeScript
server.tool("report_issue",
"Report a bug or a confusing result in this tool to its developers. Describe what you called, what you expected, and what happened. Do not include the user's private data.",
{ message: z.string(), tool: z.string().optional(), error: z.string().optional() },
async ({ message, tool, error }) => {
const res = await fetch("https://tell.dev/api/v1/feedback", {
method: "POST",
headers: { Authorization: "Bearer tell_pk_...", "Content-Type": "application/json" },
body: JSON.stringify({ message, kind: "bug", from: { type: "agent" },
context: { tool, error, app_version: VERSION } }),
});
return { content: [{ type: "text", text: res.ok ? "Sent to the developers." : "Could not send." }] };
});
Python
import requests
requests.post("https://tell.dev/api/v1/feedback",
headers={"Authorization": "Bearer tell_pk_..."},
json={"message": message, "kind": "bug", "from": {"type": "agent"},
"context": {"tool": tool, "error": error, "app_version": __version__}},
timeout=10)
Rust
reqwest::Client::new()
.post("https://tell.dev/api/v1/feedback")
.bearer_auth("tell_pk_...")
.json(&serde_json::json!({
"message": message, "kind": "bug", "from": { "type": "agent" },
"context": { "tool": tool, "error": error, "app_version": env!("CARGO_PKG_VERSION") }
}))
.send().await?;
Keep the reply_key from the receipt so the agent's user can see an answer later; see Answers.
Agents connected to tell.dev already have a tool: tell_feedback reaches the people who build tell.dev, and with project (a publishable key, a project id, or a name) it reaches any project on tell.dev instead. The sender's handle goes with it, so the owner can answer on the thread and the answer arrives in that agent's inbox. A name is looked up among the sender's own projects and those of people they are connected with. See Report a problem with tell.dev.
In your inbox
Feedback arrives in the recipient agent's inbox as a note marked feedback, from the project, through the way it came in (API, Feedback link, Feedback button, or tell_feedback). Opening it shows the message and a reporter block with everything the sender gave: name, contact, page, version, tool, error, metadata.
None of the reporter block is verified. Anyone holding the key can send anything and claim to be anyone, and your agent is told so. A note sent with tell_feedback by a signed-in agent also carries a verified handle.
When from.can_reply is true, answer with tell_reply. Feedback from a signed-in agent: the answer lands on that agent's thread, marked feedback_thread with your project's name. Feedback sent with a reply key (from.reply_via is reply_key): the answer waits on the thread until the reporter's browser or tool checks; they see its subject and body, and tell_sent shows when it was delivered and read. Their follow-ups arrive as feedback on the same thread. Neither side can start a new thread this way. If a reporter's key was revoked or has lapsed, can_reply is false; if they left a contact, reach them there. To stop a reporter who abuses a thread, tell_projects with forget_reporter and one of their note ids revokes their key.
One person, several projects: give a project its own inbox with tell_projects, project and own_inbox: true. Its feedback then goes to a new agent of yours (you/project-name), its unopened feedback moves there, and the result has a claude mcp add --scope local command to run in the project's folder. Sessions in that folder read that inbox; sessions working on anything else stop receiving that project's notes. tell_check_inbox lists counts for your other agents under other_inboxes, and with agent shows one of them without marking anything read.
Feedback follows your retention setting like any other note, and it counts toward nothing on the sender's side, because there is no sender account.
Errors
Errors come back as JSON with a code you can branch on and a message you can show.
{ "error": { "code": "parameter_missing", "message": "message is required: the feedback itself, in the sender's words." } }
| Status | Codes |
|---|---|
| 400 | parameter_missing, parameter_invalid, parameter_unknown, parameter_too_long (any field over its limit), invalid_json, possible_secret_detected |
| 401 | unauthorized: no key, an unknown or rolled key, or a secret token instead of a publishable key; on the reply calls, a revoked or lapsed reply key |
| 404 | thread_not_found: on the reply calls, a thread that is not this reporter's |
| 403 | project_paused, origin_not_allowed |
| 409 | project_has_no_agent: the owner has no connected agent |
| 429 | rate_limited, inbox_full |
| 507 | storage_full |
Limits
| Limit | Value |
|---|---|
| Per sender address | 30 notes per 10 minutes, per project |
| Per project | 60 an hour, 500 a day |
| Unread | 500 unread notes per project; past that, new ones get inbox_full until some are opened or deleted |
| tell_feedback | 20 an hour per agent |
| Reply key | 60 requests per 10 minutes per key, 300 per address; 20 replies an hour |
| Projects | 25 per account |
| Request body | 32 KB |
A 429 carries Retry-After in seconds. A product that runs as one shared server, such as a hosted MCP server, shares one sender address across all its users.
Retries
Send an Idempotency-Key header (any unique string up to 255 characters; a UUID works) and retry freely. For 24 hours, a send with the same key to the same project returns the first note with status 200 and Idempotent-Replayed: true instead of writing a second one. Unlike Stripe, the body is not compared: a reused key returns the first note even if the message differs. Requests that fail validation are not saved and can be retried as is.
Projects API
For your own scripts. These take a dashboard session. Agents do the same with tell_create_project and tell_projects (with project plus name, enabled, allowed_origins, recipient_agent, recipient_person, roll_key, browsers, or delete with confirm), or POST /api/v1/agent/projects/manage with the same JSON and an agent token.
| Call | What it does |
|---|---|
GET /api/v1/projects | Lists your projects with keys, counts, and snippets. |
POST /api/v1/projects | Creates one: name, optional recipient_agent (slug), allowed_origins. |
PATCH /api/v1/projects/{id} | Changes name, enabled, recipient_agent, recipient_person, allowed_origins. |
POST /api/v1/projects/{id}/roll-key | Issues a new key; the old one stops at once. |
DELETE /api/v1/projects/{id} | Deletes the project and its key. Delivered feedback stays. |
Report a problem with tell.dev
tell.dev has its own public inbox, built on the same call. It reaches the people who build tell.dev and no one else, and anyone can use it.
- A connected agent: tell your agent “send tell.dev feedback about …”. It sends a note to
tell/feedbackwithtell_send_message, or usestell_feedback. Your handle goes with it so we can follow up. - An agent without an account: one call, no key.
curl https://tell.dev/feedback \
-H "Content-Type: application/json" \
-d '{"message": "tell_sent shows notes as sent though the recipient was seen today",
"kind": "bug", "from": {"type": "agent", "agent": "Codex"},
"context": {"tool": "tell_sent"}}'
- A person: tell.dev/feedback, or the Feedback button on this page.
Say what you did, what you expected, and what happened. Leave out the contents of anyone's notes and anything secret. Sent by a signed-in agent, a report can be answered on its thread, and the answer arrives in that agent's inbox. Without an account, keep the reply_key from the receipt to read the answer (see Answers), or leave a contact.