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.

SettingWhat it does
Recipient agentWhich of your agents gets the notes. Defaults to the agent that made the project, or your default agent.
PauseRefuses new feedback with project_paused until you resume.
New keyRetires the old key at once and issues a new one.
Allowed originsWebsites 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

FieldWhat it is
message requiredThe feedback, in the sender's words. Up to 8,000 bytes.
kindbug, idea, question, praise, or other (default).
subjectOne line, up to 200 bytes. Without it, tell.dev uses the kind and the first line of the message.
from.nameWho sent it, as they say. Up to 80 bytes.
from.contactHow to reach them, usually an email. Up to 200 bytes.
from.typeperson or agent.
from.agentThe agent that sent it, such as Claude Code. Implies type agent.
context.urlWhere it happened. The button sends the page address without its query string.
context.app_versionYour version string.
context.platformBrowser, OS, or device.
context.toolFor agent-facing products: the tool or command involved.
context.errorAn error message or stack trace. Up to 4,000 bytes.
context.metadataUp to 20 string pairs of your own, such as a plan or a build id.
reply_keyA 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.

CallWhat it does
GET /api/v1/feedback/threadsThe 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}/readMarks the answers in that thread read. Returns unread for the rest.
DELETE /api/v1/feedback/reply-keyRevokes 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
  }
}

Button

For a website. Paste before </body>:

<script src="https://tell.dev/embed.js" data-key="tell_pk_..." defer></script>

In Next.js, load it once in the root layout: <Script src="https://tell.dev/embed.js" data-key="tell_pk_..." strategy="afterInteractive" />. The hosted link cannot be shown inside a frame; open it in the browser or an in-app browser (SFSafariViewController, Custom Tabs).

It adds a Feedback button in the corner. It renders in a shadow root, so your CSS and its CSS never meet, and it loads nothing else.

AttributeWhat it does
data-keyYour publishable key. Required.
data-button="false"No floating button; open it from your own menu.
data-labelThe button's text. Default Feedback.
data-position="left"Bottom left instead of bottom right.
data-app-versionSent as context.app_version with every note.
data-titleThe panel's title. Default Send feedback.
data-done-textWhat the panel says after a note is sent.
data-contact="false"No email field.
data-kindsWhich kinds to offer, in order, such as question,bug. Default bug,idea,question,praise,other.
data-branding="false"No tell.dev link in the panel.
data-contextJSON sent as context with every note, such as '{"metadata":{"plan":"pro"}}'.
data-keep-paramsQuery parameters kept in context.url, such as loan,tab. Every other parameter is still removed.
data-badge-only="true"The floating button shows only the count, and only when there is one. Or hide it and draw your own with tellFeedback.onCount.

After the first note, the browser keeps its reply key and the panel gains a Your feedback view: the notes sent from this browser, the answers, and a reply box for each thread. The button shows how many answers are new. It checks when the page loads, when the window gets focus, and every 60 seconds while the page is visible, and slows down if it is rate limited. “Forget this browser” removes the key here and revokes it.

tellFeedback.setContext({ metadata: { loan: "L-1042" } })   // merged into every note, from the button too
tellFeedback.setUser({ name: "Ana Ruiz", contact: "ana@example.com" })   // the from block; shown to you as unverified
tellFeedback.open({ kind: "bug", subject: "Checkout", context: { platform: "Android app" } })   // opens the panel
tellFeedback.hideButton()   // single-page apps: per route, where the button would cover controls
tellFeedback.showButton()
tellFeedback.close()
tellFeedback.send({ message: "Saved filter vanished", kind: "bug" })   // Promise, no panel
tellFeedback.onCount(function (c) { /* c.total, c.waiting, c.unread, c.answers, c.linked */ })
tellFeedback.showNotes()   // a linked browser's Notes for you

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.

  1. You (the project's owner), once. Ask your agent to add the site to the project. It calls tell_projects with project and allowed_origins, for example ["http://intranet:5001", "http://intranet:5000"]: scheme, host and port, exactly.
  2. The other person's agent, whenever it gives them a link to that site. It calls tell_dashboard with url set 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.
  3. 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.

ToAgent call
List the browsers linked to my notestell_dashboard with browsers: true
Unlink one of themtell_dashboard with revoke_browser (its brw_ id)
List the browsers linked to my projecttell_projects with project and browsers: true
Unlink one of thosetell_projects with revoke_browser
Choose whose notes the linked browsers showtell_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).

CallWhat 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/threadsHeaders 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/tokenForget 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." } }
StatusCodes
400parameter_missing, parameter_invalid, parameter_unknown, parameter_too_long (any field over its limit), invalid_json, possible_secret_detected
401unauthorized: 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
404thread_not_found: on the reply calls, a thread that is not this reporter's
403project_paused, origin_not_allowed
409project_has_no_agent: the owner has no connected agent
429rate_limited, inbox_full
507storage_full

Limits

LimitValue
Per sender address30 notes per 10 minutes, per project
Per project60 an hour, 500 a day
Unread500 unread notes per project; past that, new ones get inbox_full until some are opened or deleted
tell_feedback20 an hour per agent
Reply key60 requests per 10 minutes per key, 300 per address; 20 replies an hour
Projects25 per account
Request body32 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.

CallWhat it does
GET /api/v1/projectsLists your projects with keys, counts, and snippets.
POST /api/v1/projectsCreates 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-keyIssues 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.

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"}}'

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.