Skip to content
flintDocs

Feedback reports

A feedback report sends the Flint team a bug, papercut, feature request, or praise about Flint's API, CLI, SDKs, or docs, from your code or an AI agent.

A report can cover any Flint product, from the MCP server to the Dashboard and checkout. Each one has a feedback_report_id beginning with fbr_ and can't be changed or deleted after it's created.

Creating a report requires developer.feedback_reports.write, and listing or getting reports requires developer.feedback_reports.read. A key with only the write scope can submit reports but not read them back, which suits an agent that should report problems without seeing other reports. Both scopes work with live and test keys. Partner app tokens can't call these routes; use a key from the merchant's own account.

A report doesn't get a reply or open a support conversation. To ask a person for help with a specific problem, open a thread on Flint Help, as Getting help describes.

Choose a kind#

kind decides which fields a report needs. Send one report per root cause: two unrelated problems found in one session are two reports.

kindUse it whenRequires
bugFlint does something wrong or contradicts its documented contract.summary
papercutA workflow works, but avoidable friction or unclear behavior makes it harder than it should be.summary
feature_requestYou need something Flint doesn't do.summary
praiseSomething worked well and you want to say what.summary
ratingA quick positive, negative, or neutral score, such as a thumbs up or down.sentiment
otherNone of the above fits.summary

Every report also needs surface, the product the feedback is about. sentiment is optional on every kind except rating, and summary is optional on a rating.

surface and reporting_client answer different questions. surface is what the feedback is about; reporting_client is the tool that sent it. An agent built on your own framework that hits a confusing API error sends surface: "api" and its own name in reporting_client.name.

What to include#

Every field other than kind, surface, and the one your kind requires is optional. Add what you have:

To describeSend
What happenedsummary, then description, expected_behavior, actual_behavior, and reproduction_steps in order
Where it happenedcomponent for the feature, surface_route for an API route, canonical_command for a CLI command, code_location for your own code
The request or records involvedrelated_request_id and related_resource_ids
Who is reportingreporter_kind (human or ai_agent) and reporting_client

The format rules below go beyond each field's type and length:

  • surface_route is a public API route template exactly as the reference writes it, such as /v1/products/{product_id}. A host, a query string, or a real ID in place of {product_id} returns 400 INVALID_REQUEST with param surface_route. Leave it out when the feedback isn't about one API route.
  • canonical_command is a CLI command name in lowercase, dotted or hyphenated, such as payment-intents.create.
  • code_location points into your own code: a repository-relative file with an optional :line or :line:column, such as src/sync/products.ts:42. Absolute paths and .. segments are refused.
  • related_request_id is the req_ ID from the failing response's X-Request-Id header or error.request_id. It lets the Flint team find the exact request in its log.
  • related_resource_ids takes up to 20 unique Flint IDs of any public resource type, such as prod_ or ord_ IDs. The stored report lists them in sorted order.
  • reproduction_steps takes up to 20 steps in the order you ran them. Each step must be different from the others.

Omit a field you have no value for. Sending null or a blank string returns 400 INVALID_REQUEST naming the field, and so does any field the schema doesn't list. Flint trims leading and trailing whitespace from text fields and converts line endings to \n.

Warning: Leave out secrets and personal data

Before storing a report, Flint replaces text that looks like a secret with a marker such as [REDACTED_FLINT_API_KEY]. That covers Flint API keys, Stripe secret and restricted keys, webhook signing secrets, Authorization headers, private keys, and password= or api_key= style assignments. The response shows the text as stored. Flint doesn't detect personal data, so don't paste buyer names, emails, addresses, or card details into a report.

Control characters other than newline and tab, and Unicode bidirectional formatting characters, return 400 INVALID_REQUEST. So does text that a redaction marker pushes past the field's length limit; remove the secret and send again. The Idempotency-Key header can't contain an email address, a secret, or control characters either.

Submit a report#

This request asks for a capability, from an agent that runs a catalog sync:

cURL
curl -X POST https://api.withflintpay.com/v1/feedback-reports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalog-sync-feedback-2026-10-28" \
  -d '{
    "kind": "feature_request",
    "surface": "api",
    "summary": "Retire many products in one request",
    "description": "Our nightly catalog sync retires about 400 seasonal products, one DELETE request each.",
    "expected_behavior": "One request retires a list of products.",
    "surface_route": "/v1/products/{product_id}",
    "related_resource_ids": ["prod_01KWP7H3E5M2B8Q4T6V9X0Z1RS", "prod_01KWP7J9C4D6F8G0H2K3M5N7PQ"],
    "reporter_kind": "ai_agent",
    "reporting_client": { "name": "catalog-sync", "version": "2.3.0", "platform": "linux" }
  }'
Response
{
  "data": {
    "feedback_report_id": "fbr_01KWQ3V8T2N6R9D4H7J5M0XZ8C",
    "kind": "feature_request",
    "surface": "api",
    "summary": "Retire many products in one request",
    "description": "Our nightly catalog sync retires about 400 seasonal products, one DELETE request each.",
    "expected_behavior": "One request retires a list of products.",
    "reporter_kind": "ai_agent",
    "related_resource_ids": ["prod_01KWP7H3E5M2B8Q4T6V9X0Z1RS", "prod_01KWP7J9C4D6F8G0H2K3M5N7PQ"],
    "surface_route": "/v1/products/{product_id}",
    "reporting_client": { "name": "catalog-sync", "version": "2.3.0", "platform": "linux" },
    "created_at": "2026-10-28T15:04:05Z"
  },
  "request_id": "req_01KWQ3V8T5B7D9F1H3K5M7P9RS"
}

The response leaves out every optional field the report doesn't have.

Retries and limits#

Idempotency-Key is optional. Without one, every request creates a new report. With one, a retry with the same key and body returns the original report with Idempotency-Replayed: true, and the same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED. A replay doesn't count toward the limits below. Idempotency covers keys in general.

Feedback has its own limits, on top of the write class budget:

Counted perPer hourPer day
API key20100
Organization, across all its merchants and keysNone200

Hourly windows reset at the top of each UTC hour and daily windows at midnight UTC. A report over a limit returns 429 RATE_LIMIT_EXCEEDED with Flint-Rate-Limited-Reason: feedback_intake and a Retry-After that runs until the exhausted window resets. Send the same request again after that, with the same Idempotency-Key.

Read reports back#

GET /v1/feedback-reports lists the reports created in the key's environment by any of the merchant's keys, newest first. A report created with a test key or in a sandbox appears only there, and getting its ID from another environment returns 404 RESOURCE_NOT_FOUND. Flint deletes each report one year after it was created, so the list doesn't reach further back than that.

Next steps#

Debug API requestsFind the request ID to send as related_request_id, and read what Flint received.Build with AI agentsConnect an agent to Flint's docs and API, and what to do when it gets stuck.Rate limitsRead the 429 response and its headers, and retry it safely.

The Feedback report object#

Feedback submitted about the developer experience.

Returned by GET /v1/feedback-reports/{feedback_report_id} and carried by the endpoints below.

Attributes

One of these shapes

Feedback submitted about the developer experience.

actual_behaviorstring

Observed outcome, when the report included it. Stored as submitted, trimmed, with line endings normalized and secrets replaced by redaction markers.

canonical_commandstring

Dotted or hyphenated canonical command name, such as payment-intents.create.

code_locationstring

File in the reporter's own repository this feedback is about, optionally followed by `:line` or `:line:column`, such as `src/sync/products.ts:42`. Stored as submitted, trimmed, with line endings normalized and secrets replaced by redaction markers.

componentstring

Feature or subsystem within the product, when the report named one. Stored as submitted, trimmed, with line endings normalized and secrets replaced by redaction markers.

created_atstringRequired

Server-assigned time when Flint stored the report.

descriptionstring

Details about the feedback, when the report included them. Stored as submitted, trimmed, with line endings normalized and secrets replaced by redaction markers.

expected_behaviorstring

Desired outcome, when the report included it. Stored as submitted, trimmed, with line endings normalized and secrets replaced by redaction markers.

feedback_report_idstringRequired

Server-assigned ID of the stored feedback report.

kindenumRequired

Classification of the feedback.

  • rating
related_request_idstring

Flint request ID associated with this feedback.

related_resource_idsarray of string

Flint IDs of the resources this feedback is about, sorted.

reporter_kindenum

Whether the reporter is a human or an AI.

  • human
  • ai_agent
reporting_clientobject

Tool that submitted the feedback, independently of the product being discussed.

reproduction_stepsarray of string

Steps in reproduction order.

sentimentenumRequired

Positive, negative, or neutral assessment. Always present on a rating.

  • positive
  • negative
  • neutral
summarystring

Brief account of the feedback. Present on every report except a rating that sent none. Stored as submitted, trimmed, with line endings normalized and secrets replaced by redaction markers.

surfaceenumRequired

Product the feedback is about, independently of how the report was submitted.

  • api
  • cli
  • mcp
  • sdk
  • docs
  • dashboard
  • checkout
  • payment_links
  • webhooks
  • onboarding
  • mobile
  • other
surface_routestring

The public API route template this feedback is about.

JSON
{
  "created_at": "2026-08-02T16:00:00Z",
  "feedback_report_id": "fbr_01KEZF7C00CFKWW2MH94F39D7B",
  "kind": "feature_request",
  "reporter_kind": "human",
  "summary": "Show the remaining credit before a refund",
  "surface": "api"
}

List feedback reports#

GET/v1/feedback-reports

Requires scope developer.feedback_reports.read

Rate limit: read

Lists feedback reports in descending creation order for the credential's merchant and environment. Default order: created_at descending, then feedback_report_id descending.

Query parameters

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.

Response · 200

Feedback reports for the authenticated merchant and environment.

dataarray of one ofRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl https://api.withflintpay.com/v1/feedback-reports \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Feedback reports for the authenticated merchant and environment.

JSON
{
  "data": [
    {
      "created_at": "2026-08-02T16:00:00Z",
      "feedback_report_id": "fbr_01KEZF7C00CFKWW2MH94F39D7B",
      "kind": "feature_request",
      "reporter_kind": "human",
      "summary": "Show the remaining credit before a refund",
      "surface": "api"
    }
  ],
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Create a feedback report#

POST/v1/feedback-reportsIdempotent

Requires scope developer.feedback_reports.write

Rate limit: write

Stores one immutable occurrence of Flint feedback. Use one report per root cause and include only the evidence needed to describe Flint's behavior.

Request body

Send exactly one of these

The `rating` variant of `CreateFeedbackReportRequest`.

actual_behaviorstring

Optional observed outcome. Limited to 4000 characters (Unicode code points), counted before whitespace and line-ending normalization.

canonical_commandstring

Dotted or hyphenated canonical command name, such as payment-intents.create. Limited to 200 characters (Unicode code points), counted before whitespace and line-ending normalization.

code_locationstring

One file path relative to your repository root, optionally followed by `:line` or `:line:column`, such as `src/sync/products.ts:42`. Absolute paths, `..` segments, and backslashes are rejected. Limited to 500 characters (Unicode code points), counted before whitespace and line-ending normalization.

componentstring

Optional feature or subsystem within the product. Limited to 128 characters (Unicode code points), counted before whitespace and line-ending normalization.

descriptionstring

Optional details about the feedback. Limited to 8000 characters (Unicode code points), counted before whitespace and line-ending normalization.

expected_behaviorstring

Optional desired outcome. Limited to 4000 characters (Unicode code points), counted before whitespace and line-ending normalization.

kindenumRequired

Classification of the feedback.

  • rating
related_request_idstring

Flint request ID associated with this feedback. Limited to 255 characters (Unicode code points), counted before whitespace and line-ending normalization.

related_resource_idsarray of string

Flint IDs of the resources this feedback is about, at most 20 and all different. Flint checks only that each ID has the format of a Flint resource ID, not that the resource exists or that you can read it.

reporter_kindenum

Whether the reporter is a human or an AI.

  • human
  • ai_agent
reporting_clientobject

Tool submitting the feedback, independently of the product being discussed. Its name is required when present.

reproduction_stepsarray of string

Unique steps in reproduction order, with at most 20 entries.

sentimentenumRequired

Positive, negative, or neutral assessment. Required for rating feedback; optional for narrative feedback.

  • positive
  • negative
  • neutral
summarystring

Brief account of the feedback. Required for every kind except rating; optional for a rating. Limited to 200 characters (Unicode code points), counted before whitespace and line-ending normalization.

surfaceenumRequired

Product being discussed, independently of how the report is submitted.

  • api
  • cli
  • mcp
  • sdk
  • docs
  • dashboard
  • checkout
  • payment_links
  • webhooks
  • onboarding
  • mobile
  • other
surface_routestring

A public API route template exactly as the API reference shows it, such as `/v1/orders/{order_id}`, with no host, query string, or real IDs. Omit it for feedback that isn't about an API route; any other value returns `400 INVALID_REQUEST`. Limited to 500 characters (Unicode code points), counted before whitespace and line-ending normalization.

Response · 201

The stored feedback report.

dataone ofRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/feedback-reports \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "kind": "feature_request",
    "reporter_kind": "human",
    "summary": "Show the remaining credit before a refund",
    "surface": "api"
  }'

Get a feedback report#

GET/v1/feedback-reports/{feedback_report_id}

Requires scope developer.feedback_reports.read

Rate limit: read

Returns one immutable feedback report in the credential's merchant and environment.

Path parameters

feedback_report_idstringRequired

Flint feedback report ID.

Response · 200

The requested feedback report.

Same response as Create a feedback report.

curl https://api.withflintpay.com/v1/feedback-reports/fbr_01KEZF7C00CFKWW2MH94F39D7B \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

The requested feedback report.

JSON
{
  "data": {
    "created_at": "2026-08-02T16:00:00Z",
    "feedback_report_id": "fbr_01KEZF7C00CFKWW2MH94F39D7B",
    "kind": "feature_request",
    "reporter_kind": "human",
    "summary": "Show the remaining credit before a refund",
    "surface": "api"
  },
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Was this helpful?