Response Feedback

This guide shows how to collect end-user feedback on AI-generated responses from your own interface and store it in Briink.

Base URL: https://api.platform.briink.com
Auth: x-api-key: <BRIINK_API_KEY> on every request. See API Keys.

What you get

• One thumbs up / thumbs down rating per response, with an optional free-text comment.
• Feedback is returned alongside the response itself, so your UI can show the current state after a reload.
• Ratings can be changed or retracted at any time.

Step 1 — Read the current feedback for a response

Feedback is attached to a screening execution response — one per question in a screening. The response object carries its own feedback, so you can read the current state one response at a time:

GET /workspaces/{workspace_id}/screenings/{screening_id}/responses/{response_id}

curl "https://api.platform.briink.com/workspaces/$WORKSPACE_ID/screenings/$SCREENING_ID/responses/$RESPONSE_ID" \
  -H "x-api-key: $BRIINK_API_KEY"

The id is what you will send as object_id. The feedback field holds the currently active feedback for that response, or null if there is none:

{
  "id": "0f0f4a8e-1f5b-4c3a-9f2d-6b1c9a7d2e11",
  "question": { "text": "Describe your climate-related risks." },
  "response_text": "Our climate-related risks are ...",
  "feedback": {
    "id": "8c2b1f4d-7a91-4e0b-9c33-25e6f0a1b7c4",
    "workspace_id": "3a7d1c05-9e42-4b8f-a1d6-0c5b2e7f9a33",
    "object_id": "0f0f4a8e-1f5b-4c3a-9f2d-6b1c9a7d2e11",
    "object_type": "SCREENING_EXECUTION_RESPONSE",
    "rating": "THUMBS_DOWN",
    "categories": [],
    "text": "The relevant info is in our Annual Report, page 124.",
    "creator_id": "b6e3f1a2-4c78-4d90-8e15-72af0d3c6b41",
    "created_at": "2026-08-10T09:12:33Z",
    "archived": false,
    "updated_at": null,
    "editor_id": null
  }
}

Use feedback to render the initial state of the thumbs icons, and feedback.id to retract it later. No separate feedback lookup is needed.

Feedback object fields

The same object shape is returned by the POST in Step 2.

creator_id is the identity behind the API key, not the end user in your interface. If you integrate with a single shared API key, all feedback will be attributed to that same identity. To tell your users apart, prefix their name or entity to the comment, wrapped in double square brackets so it stays machine-readable and can be stripped from the comment later:

"text": "[[Jane Doe | Acme Ltd]] The relevant info is in our Annual Report, page 124."

Keep the marker at the very start of the string and the comment itself after it.

Step 2 — Submit feedback

POST /workspaces/{workspace_id}/feedback

curl -X POST "https://api.platform.briink.com/workspaces/$WORKSPACE_ID/feedback" \
  -H "x-api-key: $BRIINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "object_type": "SCREENING_EXECUTION_RESPONSE",
        "object_id": "0f0f4a8e-1f5b-4c3a-9f2d-6b1c9a7d2e11",
        "rating": "THUMBS_DOWN",
        "text": "The relevant info is in our Annual Report, page 124."
      }'

Request body

Returns 200 with the created Feedback object, including its id — the same shape shown in Step 1.

If you store responses on your side, write that object straight into your record. There is no need to re-fetch the response afterwards just to pick up the feedback.

Comment on thumbs down: the API accepts feedback without a comment, so if you want the comment to be mandatory on THUMBS_DOWN, enforce it in your UI before sending the request.

This also works for questions where no evidence was found — the response object still exists and still has an id, so users can flag a wrong "no evidence" result the same way.

Step 3 — Change or retract feedback

Change: just POST again for the same object_id. Briink keeps one active feedback per response and automatically supersedes the previous one — no need to delete first.

Retract: delete it with the id of the active feedback.

DELETE /workspaces/{workspace_id}/feedback/{feedback_id}

Returns 204 No Content. This archives the feedback; the response's feedback field becomes null again.

Optional — Feedback categories

If you later want structured reasons alongside the comment, fetch the list (label + description per category) and send the selected values in categories:

GET /workspaces/{workspace_id}/feedback/categories

Error handling

object_id is not checked against existing responses on create, so a wrong id will be accepted with a 200. Always take the id straight from the response object in Step 1.

Keeping your own copy in sync

If you cache responses in your own database, note that webhooks do not carry the response object. screening.response.status_changed contains identifiers and the status transition only — event_type, workspace_id, timestamp, screening_id, execution_id, response_id, question_id, status, previous_status — so the response content always comes from a GET.

Two ways to keep your stored copy current:

• Use the POST result. POST /feedback returns the full Feedback object, so you can update your record from that response alone — no extra call.
• Re-fetch the response. Call GET /workspaces/{workspace_id}/screenings/{screening_id}/responses/{response_id} and overwrite your stored object. It returns the same model as the list endpoint, with feedback alongside the suggestion, evidence and everything else — useful when you want to be certain you are in sync rather than just applying a local update.

Recommended UI flow

1. Render 👍 / 👎 per response, pre-filled from response.feedback.
2. 👍 → POST immediately with rating: "THUMBS_UP".
3. 👎 → open a comment box, require input, then POST with rating: "THUMBS_DOWN" and text.
4. Clicking the active icon again → DELETE using response.feedback.id.