Feedback API

The Feedback API is the feedback widget without the widget. Build your own feedback form, NPS survey or in-app prompt, then submit from your backend or from your frontend. Submissions land in your ProductOS feedback list with source = API, are linked to the right account, and you can read them back to show your users what happened to what they sent.

Keys

The API takes two kinds of workspace key. Pick by where your code runs.

Admins and owners issue keys in Settings → Widget & API. The full key is shown once. Publishable keys are the same keys the widget uses, so one key can serve both.

Keys belong to the workspace, not to the person who created them, so an integration keeps working when that person leaves. To rotate, issue a new key, deploy it, then revoke the old one. A revoked key gets 401 on its next request.

Why the difference in what each key can do: a publishable key is public, so anyone can send a request with it and claim to be anyone. Only your server knows who your signed-in user really is, so only secret-key submissions are trusted enough to link to an account or to show back to that user.

Submit feedback

curl https://productos.ca/api/v1/public/feedback \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a90-4b1e-4d6e-9d0a-3c7e5b2f8a14" \
  -d '{
    "mode": "feedback",
    "description": "Exporting a report times out on workspaces with more than 10k rows",
    "category": "bug",
    "tags": ["export", "performance"],
    "identify": {
      "externalId": "usr_8842",
      "email": "jane@acme.com",
      "name": "Jane Doe",
      "company": "Acme"
    },
    "client": { "url": "https://app.acme.com/reports/42", "locale": "en-US" },
    "metadata": { "plan": "enterprise", "app_version": "4.2.0" }
  }'

{
  "data": {
    "id": "0f6c1c5e-8b1a-4e7b-9f5e-1d2c3b4a5968",
    "reference": "FDBK-000705",
    "mode": "feedback",
    "status": "new",
    "title": "Exporting a report times out on workspaces with more than 10k rows",
    "description": "Exporting a report times out on workspaces with more than 10k rows",
    "category": "bug",
    "score": null,
    "comment": null,
    "created_at": "2026-09-16T23:56:08.379Z"
  }
}

Store id or reference if you want to read the submission back later. reference is the ID your team sees in ProductOS.

Submit an NPS score

Send mode: "nps" with a whole-number score from 0 to 10 and an optional comment.

curl https://productos.ca/api/v1/public/feedback \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "nps",
    "score": 9,
    "comment": "The new triage view saves me an hour a week",
    "identify": { "externalId": "usr_8842", "email": "jane@acme.com" }
  }'

Without a title, NPS submissions are titled like NPS 9/10, The new triage view saves me an hour a week.

Request fields

Unknown top-level fields are ignored. Everything else is validated, and a bad field is rejected with 422 naming it in details.field, rather than silently trimmed.

The body can be up to 64 KB.

Identify the person

identify takes externalId (your ID for the user, up to 256 chars; userId works as an alias), email, name and company. All are optional. Emails are stored lowercased. Your team sees these on the submission, so they can follow up. Leave identify out for anonymous feedback.

Send externalId if you want to list the person's submissions later, and email or company if you want the submission linked to their account.

Don't send anything you wouldn't want a teammate with access to the workspace to see.

Linked accounts

When a secret-key submission identifies its sender, ProductOS links it to the matching account in your workspace, so the feedback counts toward that account (and its ARR) in prioritization. The first rule that matches exactly one account wins:

• A rule that matches more than one account is skipped, never guessed. Two accounts named Acme, or two sharing @acme.com, won't link by that rule.
• Personal email providers (gmail.com, outlook.com, icloud.com and similar) never match by domain.
• ProductOS never creates accounts. Nothing matches, nothing is linked.
• Publishable-key and widget submissions are never linked automatically, because their identity can't be verified. Your team links those by hand.

The submission shows the account and the rule that matched it, and your team can unlink it like any other link.

Retry safely with Idempotency-Key

Networks fail after a request is sent. To retry without creating a duplicate, send an Idempotency-Key header: any string of 1 to 255 visible ASCII characters that is unique per submission, such as a UUID you generate when the user presses Submit.

Keys are scoped to the API key that sent them, so two integrations can't collide.

export async function sendFeedback(submissionId: string, body: object) {
  for (let attempt = 1; attempt <= 3; attempt++) {
    const res = await fetch("https://productos.ca/api/v1/public/feedback", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.PRODUCTOS_FEEDBACK_KEY}`,
        "Content-Type": "application/json",
        // Same key on every attempt, so a retry can't create a second row.
        "Idempotency-Key": submissionId,
      },
      body: JSON.stringify(body),
    });
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get("Retry-After") ?? attempt);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const json = await res.json();
    if (!res.ok) throw new Error(`${json.error.code}: ${json.error.message}`);
    return json.data;
  }
  throw new Error("ProductOS is unavailable, try again later");
}

Read a submission back

Pass the id or the reference. Secret keys only.

curl https://productos.ca/api/v1/public/feedback/FDBK-000705 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

The response is the same object the submit call returned, with the current status:

title, description, comment, category and score are always what was submitted. Inside ProductOS your team may rename, rewrite or annotate the feedback; those edits are never returned, so it's safe to show these fields to the person who sent them.

Only submissions sent through the Feedback API are readable, by any secret key in the workspace, so rotating keys keeps old submissions readable. Feedback your team typed in, imported, synced from an integration or received through the widget returns 404, and so does a submission your team moved to the trash.

List a person's submissions

Use it for a "Your feedback" page: everything one person sent, newest first, with its current status.

curl "https://productos.ca/api/v1/public/feedback?external_id=usr_8842&limit=20" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

{
  "data": [
    {
      "id": "0f6c1c5e-8b1a-4e7b-9f5e-1d2c3b4a5968",
      "reference": "FDBK-000705",
      "mode": "feedback",
      "status": "planned",
      "title": "Exporting a report times out on workspaces with more than 10k rows",
      "description": "Exporting a report times out on workspaces with more than 10k rows",
      "category": "bug",
      "score": null,
      "comment": null,
      "created_at": "2026-09-16T23:56:08.379Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 },
  "links": {
    "self": "https://productos.ca/api/v1/public/feedback?external_id=usr_8842&limit=20&offset=0",
    "next": null,
    "prev": null
  }
}

Pass external_id, email or both (both must match). A request with neither is refused, so a key can't page through everyone's feedback. Only submissions sent with a secret key are listed: a browser submission could claim to be anyone, and listing it would let a stranger put text in your user's list. Submissions in the trash aren't listed.

From the browser

Use a publishable key and add your domains to its allowlist. The browser sends Origin for you.

async function submitScore(score, comment, user) {
  const res = await fetch("https://productos.ca/api/v1/public/feedback", {
    method: "POST",
    headers: {
      Authorization: "Bearer pk_live_xxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      mode: "nps",
      score,
      comment,
      identify: { externalId: user.id, email: user.email, name: user.name },
      client: {
        url: location.href,
        userAgent: navigator.userAgent,
        viewport: [window.innerWidth, window.innerHeight],
        locale: navigator.language,
      },
    }),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json.error.message);
  return json.data.reference;
}

CORS preflight is handled for you, error responses included, so your code can read error.message when a request is refused. Browser submissions aren't linked to accounts or listed back. If you need either, submit from your backend with a secret key.

Errors

Errors use the standard error envelope.

Rate limits

Need more? Contact support with your expected volume.

What your team sees

Each submission becomes a feedback row with source = API and status = new, with your tags applied and, for secret-key submissions, its account linked. The row's Submission section shows the person, their user ID and company, the linked account and how it matched, the NPS score and category, the page and locale, and your metadata keys. For browser submissions ProductOS also stores the caller's IP for abuse review; it's never shown in the app. From there your team triages it like any other feedback: themes, linked features, and the rest of the Golden Thread.

Next

• Public feedback widget: the drop-in version, same publishable keys.
• Feedback widget & API settings: issuing, revoking and rotating keys.
• Authentication: API tokens for reading and writing everything else.