Submit feedback on an evaluation or item

Say what the right answer was. The sources that count toward an evaluation’s consensus, which previews and suggestions learn from, are owner (through this route), reviewers answering through the review routes (the Review app), and seed examples; app_native and app_resolution provide supporting feedback only. Use source: "owner" for your own judgment as the decision’s owner: its outcome, target or verdict claim decides the consensus; feature claims alone decide nothing. All owner feedback through this route is the decision owner’s single voice, whoever sent it (the latest owner submission with an outcome, target or verdict claim decides, replacing earlier ones); agreement between people is only kept for reviewers on the review routes. Use app_native or app_resolution for your app’s own feedback (a user approved or reverted the outcome, an appeal settled it): they never decide a consensus, but the first feedback on an item’s group, from any source, fixes its split for good (native feedback sent before your review keeps that item out of the holdout), their reasons can reach the suggestion generator, and their input_broken claims set the evaluation aside. See source. Records claims (target, outcome, verdict, feature, input_broken, action) about an evaluation in the key’s environment, or about an item’s latest primary evaluation. Claims are checked against that evaluation (400 with param): at most one outcome, target and verdict claim and one claim per feature, an outcome and target that agree, and verdicts only on primary evaluations that decided an outcome (shown, and not abstained). supersedes must name a submission by the same actor on the same evaluation that nothing has superseded yet (409). owner feedback cannot name an actor (403). Owner feedback, and superseding an owner submission, need the decisions:develop scope (403 INSUFFICIENT_SCOPE); integration sources need decisions:feedback. Read a submission back with GET /v1/feedback/{feedback_id}. A replay with the same Idempotency-Key returns the first result with the Idempotent-Replayed header.

POST /v1/feedback

cURL

owner_outcome

curl --request POST \
  --url https://api.moonbounce.ai/v1/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "about": {
    "evaluation_id": "evl_01900000-0000-7000-8000-000000000000"
  },
  "source": "owner",
  "claims": [
    {
      "kind": "outcome",
      "value": "review"
    }
  ],
  "reason": "The seller is verified, so this needs a person, not a rejection."
}
'

201

{
  "environment": "production",
  "id": "<string>",
  "evaluation_id": "<string>",
  "item_id": "<string>",
  "claims": 2,
  "resolved_from_item": true
}

Authorizations

bearerAuthbearerAuth

Authorization · string · header · required

An API key, sent as Authorization: Bearer <key>. Each operation lists the scope its key needs: decisions:evaluate (evaluate and read evaluations), decisions:feedback (your app's feedback) or decisions:develop (everything else, including owner feedback and the review queue). An operation listing no scope takes any scoped key. A key with no scope, or without the operation's, gets 403 INSUFFICIENT_SCOPE.

Headers

idempotency-key · string

Makes a retry safe. For 24 hours, the same key with the same request returns the first stored result (with Idempotent-Replayed: true); the same key with a different request is a 422 IDEMPOTENCY_KEY_REUSED. Keys are scoped to the organization and environment across every operation, so use a fresh key per request. A request that failed before its result was stored runs again when retried with its key.

Required string length: 1 - 255

Pattern: ^[\x20-\x7e]+$

Body

application/json

about · object · required

What the feedback is about. {evaluation_id} is preferred: it names exactly the answer you are judging. {decision_id, item_id} means the item's latest primary evaluation in the key's environment, resolved when the feedback arrives; the response says which one. Verdict claims need evaluation_id.

Option 1

Option 2

Show child attributes

claims · object[] · required

What you are saying about the evaluation, 1 to 65 claims. At most one outcome, one target and one verdict claim, and one claim per feature; an outcome and a target must not contradict each other.

Required array length: 1 - 65 elements

Whether the target statement is true. Only for specs that declare a target.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Show child attributes

source · enum<string> · required

Who is speaking. Three sources count toward an evaluation's consensus answer, which is what previews and suggestions learn from (on primary and seed evaluations whose content is stored): owner through this route, reviewers answering through the review routes (the Review app), and seed examples. The owner outranks reviewers, and reviewers outrank seeds. app_native and app_resolution provide supporting feedback only. owner: the decision owner's judgment. An outcome, target or verdict claim decides the consensus; feature claims refine a case that has a consensus and on their own decide nothing. owner folds every person into one: all owner feedback through this route is the decision owner's single voice, whoever sent it, and the latest owner submission with an outcome, target or verdict claim decides, replacing earlier ones. Agreement between people is only kept for reviewers on the review routes, who each get one vote. Use owner for corrections you stand behind. app_native: your app's own feedback about the outcome it acted on, for example a user approved or reverted it. app_resolution: how your own process finally settled the case, for example an appeal. The two weak sources never decide a consensus, but they are not inert. The first feedback a group of near-identical items gets in an environment, from any source, fixes the group's split for good: an owner's or reviewer's first feedback holds out 30% of groups to test suggestions, while a native or resolution first touch puts the group in training, so a native verdict sent before your own review means that item can never be held out. A native or resolution submission's reason is shown to the suggestion generator alongside a case that other feedback decided. An input_broken claim from any source sets the evaluation aside.

Available options: app_native, app_resolution, owner

actor · string

Who in your system this comes from, for example a user or agent id. It is namespaced under your key. Not allowed with source owner: the owner is you.

Required string length: 1 - 256

reason · string

Why, in your words. Optional.

Maximum string length: 4000

unsure · boolean

True when the judge is not confident in these claims.

supersedes · string

The id of your own earlier submission on the same evaluation that this one replaces. Only the latest submission in a chain counts; the earlier one stays readable and shows superseded_by.

Pattern: ^fbk_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response

201

application/json

Recorded

environment · enum<string> · required

The environment of the key that made the call: production or test. Evaluations, feedback, reviews and suggestions are separate per environment; registered structures are shared.

Available options: production, test

id · string · required

Pattern: ^fbk_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

evaluation_id · string · required

Pattern: ^evl_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

item_id · string · required

claims · integer · required

Required range: x >= 1

resolved_from_item · boolean · required