How to collect feedback for API and developer tools

Developer feedback is mostly about errors and docs

Developers rarely write long feedback about a product. They hit an error, copy the message, and move on. When they do write, the message is often about the documentation: a missing parameter, an example that does not run or a sentence that describes the old behavior. Feedback for an API or a developer tool therefore comes from three places: the docs, the error output and the commands people run.

Collect each stream where it happens. A small form on the docs site catches the confusing paragraph. A link near an error message catches the failure. A command in your CLI catches the problem a developer could not describe in a browser.

Put the widget on the docs pages

The docs site is the main entry point, so load the widget there. Set the allowed origins in product settings to the docs domain, add the script to the page template and let readers report a problem where they found it. The page URL saved with each item tells you which section needs work.

<script src="https://escutaproduto.com/widget.js" data-key="pk_your_product_key" defer></script>

Add an explicit button next to a reference section that often confuses people, such as authentication or pagination:

<button type="button" data-escuta-open="bug">This section is unclear</button>

Use the "idea" type for requests and the "bug" type for errors in the docs. A third choice, "other", works for general notes. The widget reference lists the options for placement and color.

Send a request id with the report

When an error reaches a user in your product, include the request id that your logs use. Developers often copy that id from an error message, and it lets you find the exact request in your own system. Send it as metadata with the report.

await fetch("https://escutaproduto.com/api/v1/feedback", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    key: "pk_your_product_key",
    kind: "bug",
    message: "Checkout failed with card_declined",
    pageUrl: "https://docs.example.dev/payments",
    metadata: {
      requestId: "req_7c21f0a9",
      sdkVersion: "1.4.0",
      endpoint: "/v2/payments",
    },
  }),
});

Keep the metadata short and specific. A request id, the client version and the endpoint name answer the first three questions a maintainer asks. Metadata is a JSON object of up to 4 KB, so there is room, but more is not better. Never include API keys, bearer tokens, card numbers or the full body of a request that contains customer data.

Escuta Produto has no tags, so keep your categories in metadata or in internal notes, and use the text search on the inbox to find related reports.

Send feedback from a CLI or SDK

A command-line tool is a good place for feedback because the developer is already in the flow. Add a feedback command that asks for a message and sends it. The request runs from the developer's machine, so the rate limit counts that person's IP address, which is what you want.

export async function sendCliFeedback(message, { toolVersion, command }) {
  const response = await fetch("https://escutaproduto.com/api/v1/feedback", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      key: "pk_your_product_key",
      kind: "other",
      message,
      metadata: { toolVersion, command },
    }),
  });
  return response.status === 201;
}

Ask for consent before you attach anything. The developer should know what the command sends, and the output should say so in one line. If a user runs the command in a CI job, the request comes from the CI runner's IP address, so keep the command manual.

If you publish an SDK, you do not need a native package. Wrap the same request in a small function, and document the one call a developer makes. Escuta Produto does not ship SDKs, so a thin wrapper that you maintain is the usual approach.

Plan for the rate limit behind a relay

The rate limit is 10 submissions per minute from the same IP address to the same product. For a CLI, that is generous, because each developer's request comes from their own machine. For a backend that forwards reports from every user, it is tight, because all of them leave from one server address.

If you run a relay, you have three reasonable choices. You can send from the client instead. You can keep a queue on your server and send at a steady pace, which means accepting that a report may arrive a minute late. Or you can send the most important reports immediately and hold the rest. When the API returns 429, do not retry at once. Wait a minute and try again. The REST API reference lists the other status codes.

Keep sensitive data out of feedback

Developer tools handle keys, tokens and private data, so take care with what goes into a report. Strip authorization headers from any log you attach. Do not send environment variables, full stack traces that include file contents or request bodies with customer records. A request id and a version are almost always enough for a first reply.

Tell developers what the form stores. A line such as "Your message, the tool version and the command name are sent to the maintainers" builds trust, and it helps the privacy notice match what the code does.

Set up Escuta Produto for your developer tool

Create a product for the API or tool, copy the public key and add your docs domain to the allowed origins. Add the widget to the docs template and a feedback command to the CLI. Send a test report from each path and check that the metadata and page URL appear on the item.

Connect a Slack or Discord webhook so the team sees reports while they are fresh. The notifications guide explains the setup. For open-source tools, the article on collecting feedback for an open-source project covers the public issue tracker side, and feedback form spam protection explains how the form protects itself from bots.