Skip to main content
POST
Mark a suggestion pulled

Authorizations

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]+$

Path Parameters

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

Body

application/json

No fields: send no body, or {}.

Response

The pulled suggestion

id
string
required
Pattern: ^sug_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
decision_id
string
required

A name you choose for this decision, such as refund-exception: a lowercase letter, then up to 127 of a-z 0-9 _ . -. Unique in your organization and shared by its test and production keys. The first registration or evaluation under a new one creates the decision.

Pattern: ^[a-z][a-z0-9_.-]{0,127}$
kind
enum<string>
required

question_rewrite: new wording for one question (its question text and criteria). new_question: one new question, added as an input of the aggregation that feeds the result's bands or rules.

Available options:
question_rewrite,
new_question
target
enum<string>
required
Available options:
structure
summary
string
required
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; decisions and their versions belong to the whole organization.

Available options:
production,
test
base
object
required
candidate
object
required
requires
string[]
required
Pattern: ^sug_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
candidate_structure
object
required

Everything that defines a decision: questions, attribute declarations, aggregations and the result. Names are unique across all three maps.

diff
object[]
required
evidence
object
required
preview_id
string
required

The preview that is this suggestion's evidence: prv_, or run_ for one stored before prv_.

Pattern: ^(prv|run)_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
generator
object
required
status
enum<string>
required
Available options:
proposed,
pulled,
accepted,
rejected,
superseded
created_at
string<date-time>
required
objective
object | null

The stored objective revision its preview was scored with, or null when none was set (balanced losses). Absent on suggestions made before previews were judged, when none was set.

status_at
string<date-time>
rejection_reason
string
accepted_evaluation_id
string
Pattern: ^evl_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
accepted_at
string<date-time>
stale
object

Present when feedback on cases this suggestion was evaluated on changed after its evidence was read: an answer it read was changed, withdrawn or corrected, or the owner, a reviewer or an imported example judged one of its cases since, or any feedback since marked one's input as broken. Its evidence is as it was then; preview it again before relying on it.