Feedback REST API

Endpoint

POST https://escutaproduto.com/api/v1/feedback
Content-Type: application/json

No API secret is needed: the product key identifies where the feedback goes and can only be used to send feedback, never to read it. The machine-readable spec lives at /openapi.json.

Example

curl -X POST https://escutaproduto.com/api/v1/feedback \
  -H "content-type: application/json" \
  -d '{
    "key": "pk_your_product_key",
    "kind": "idea",
    "message": "Let me export invoices as PDF",
    "rating": 4,
    "email": "customer@example.com",
    "metadata": { "plan": "pro", "appVersion": "2.3.1" }
  }'

{ "ok": true, "id": "3f0c6a8e-7d1b-4c55-9a43-1f2e8b7c9d10" }

Request body

Field	Type	Required	Notes
key	string	yes	The product's public key (pk_…).
message	string	yes	At least 2 characters. Text beyond 5,000 characters is cut off.
kind	string	no	bug, idea, praise or other. Defaults to other.
rating	integer	no	1 to 5.
name	string	no	Up to 120 characters (longer values are cut off).
email	string	no	A valid email address, up to 254 characters.
pageUrl	string	no	An http(s) URL, up to 2,048 characters. Other values are ignored.
metadata	object	no	Any JSON object up to 4 KB, such as user id, plan or app version.

Responses

Status	Meaning
201	Saved. Body: { "ok": true, "id": "…" }.
400	Invalid JSON or a field failed validation. Body: { "error": "…" }.
403	The request came from a browser origin that isn't in the product's allowed origins.
404	Unknown product key.
413	Body larger than 16 KB.
429	More than 10 submissions per minute from the same IP to the same product.

Calling it from a browser

Browsers may call the endpoint directly. It answers CORS preflights, and the widget sends text/plain to skip the preflight entirely. If the product has Allowed origins configured, the Origin header must match one of them. Server-side requests (no Origin header) are always accepted.

Calling it from a backend

await fetch("https://escutaproduto.com/api/v1/feedback", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    key: process.env.ESCUTA_PRODUTO_KEY,
    kind: "bug",
    message: "Checkout failed with card_declined",
    metadata: { orderId: "ord_123" },
  }),
});