Outcomes & Scores

Track decision outcomes, measure accuracy scores, view calibration data, and manage decision chains.

15 min read
Share

Decision Intelligence is AskVerdict's system for closing the feedback loop on your AI-powered verdicts. After a verdict runs, you can record what actually happened, and the system calculates a Brier score to measure how well-calibrated your AI-assisted decisions are over time.

All endpoints in this section require authentication via Authorization: Bearer <token>.

Outcomes

Outcomes connect a completed debate back to real-world results. Every completed debate automatically gets a pending outcome record — it waits until you report what happened.

Submit Outcome

POST/api/debates/:id/outcome

Record the real-world result of a debate verdict.

Path Parameters

NameTypeRequiredDescription
idstringRequiredThe debate UUID to record an outcome for.

Request Body

NameTypeRequiredDescription
outcomeStatusstringRequiredResult of the decision. One of: 'correct', 'partially_correct', 'wrong', 'too_early'.
outcomeNotesstringOptionalFree-text description of what actually happened. Max 500 characters.
satisfactionScoreintegerOptionalHow satisfied you are with the outcome on a scale of 1–5.

Outcome Status Values

ValueMeaning
correctThe verdict's recommended course of action led to the expected positive result
partially_correctThe verdict was roughly right but missed important nuance
wrongThe verdict's recommendation did not play out as expected
too_earlyNot enough time has passed to evaluate the outcome yet

Example Request

bash
curl -X POST https://api.askverdict.ai/api/debates/dbt_abc123/outcome \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "outcomeStatus": "correct",
    "outcomeNotes": "We shipped the refactor in Q1 and cut P95 latency by 40%.",
    "satisfactionScore": 5
  }'

Response

After the response is returned, your decision score is recalculated asynchronously — the updated Brier score will be available within seconds at GET /api/scores/me.

Error Responses

CodeErrorDescription
400VALIDATION_ERRORInvalid outcomeStatus or field constraint violated
404NOT_FOUNDNo outcome record exists for this debate

Skip Outcome

POST/api/debates/:id/outcome/skip

Mark a pending outcome as skipped — it will not affect your decision score.

Use this when a debate was exploratory and you do not want to record a real-world result.

Path Parameters

NameTypeRequiredDescription
idstringRequiredThe debate UUID to skip.

Example Request

bash
curl -X POST https://api.askverdict.ai/api/debates/dbt_abc123/outcome/skip \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Set Outcome Reminder

PATCH/api/debates/:id/outcome/reminder

Set or update the date when you want to be reminded to record an outcome.

Path Parameters

NameTypeRequiredDescription
idstringRequiredThe debate UUID.

Request Body

NameTypeRequiredDescription
reminderAtstring (ISO 8601)RequiredThe datetime to send the reminder. Must be a valid ISO 8601 datetime string.

Example Request

bash
curl -X PATCH https://api.askverdict.ai/api/debates/dbt_abc123/outcome/reminder \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "reminderAt": "2026-06-01T09:00:00Z" }'

Response

Error Responses

CodeErrorDescription
400VALIDATION_ERRORreminderAt is not a valid ISO 8601 datetime
404NOT_FOUNDNo outcome record for this debate

Get Outcome for a Debate

GET/api/debates/:id/outcome

Fetch the outcome record for a specific debate.

Path Parameters

NameTypeRequiredDescription
idstringRequiredThe debate UUID.

Example Request

bash
curl https://api.askverdict.ai/api/debates/dbt_abc123/outcome \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Error Responses

CodeErrorDescription
404NOT_FOUNDNo outcome record for this debate or debate does not belong to you

List Pending Outcomes

GET/api/outcomes/pending

List all debates that have a pending outcome waiting to be recorded.

Returns debates where you have not yet submitted an outcome, are not skipped, and are not marked too_early. Useful for building reminder UIs or periodic review workflows.

Example Request

bash
curl https://api.askverdict.ai/api/outcomes/pending \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Outcome History

GET/api/outcomes/history

Paginated list of all resolved outcome records.

Query Parameters

NameTypeRequiredDescription
limitintegerOptionalNumber of records to return. Default: 20.
offsetintegerOptionalRecords to skip for pagination. Default: 0.
domainstringOptionalFilter by domain category. One of: 'business', 'technology', 'health', 'legal', 'personal', 'finance', 'education', 'other'.

Example Request

bash
curl "https://api.askverdict.ai/api/outcomes/history?limit=10&offset=0&domain=technology" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Decision Scores

The scoring system tracks how well-calibrated your AI-assisted decisions are over time using the Brier score — a standard probabilistic accuracy metric. Lower Brier scores indicate better calibration.

Get Your Score

GET/api/scores/me

Retrieve your current decision score and per-domain breakdown.

Example Request

bash
curl https://api.askverdict.ai/api/scores/me \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Score Field Reference

FieldTypeDescription
brierScorenumberProbabilistic accuracy: 0.0 (perfect) to 1.0 (worst). Default 0.5 until resolved outcomes exist.
totalTrackedintegerTotal number of debates with outcome records.
totalResolvedintegerDebates with a correct, partially_correct, or wrong outcome.
domainScoresobjectPer-domain Brier scores keyed by domain category name.
accuracyPercentagenumberHuman-readable score derived from Brier score (0–100).
streakintegerCount of consecutive correct outcomes ending at the most recent resolved decision.

Get Accuracy Trend

GET/api/scores/me/trend

Time-series accuracy data for charting your decision quality over time.

Query Parameters

NameTypeRequiredDescription
daysintegerOptionalNumber of days to look back. Default: 90.

Example Request

bash
curl "https://api.askverdict.ai/api/scores/me/trend?days=90" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

An empty array is returned if no resolved outcomes exist yet. Each data point represents:

FieldDescription
dateISO timestamp of this data point
brierScoreBrier score at this point in time
rollingAccuracyAccuracy percentage (0–100)
sampleSizeNumber of resolved outcomes used in this calculation

Get Calibration Buckets

GET/api/scores/me/calibration

Calibration curve data comparing predicted probabilities to actual outcome rates.

Calibration data shows whether you trust the right verdicts. A well-calibrated user whose verdicts predict 80% confidence should see roughly 80% correct outcomes in that probability bucket.

Example Request

bash
curl https://api.askverdict.ai/api/scores/me/calibration \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Calibration Bucket Fields

FieldTypeDescription
predictedRange[number, number]The probability range this bucket covers, e.g. [0.7, 0.8] means 70–80% predicted confidence
actualRatenumberFraction of outcomes in this bucket that were actually correct (0.0–1.0)
countintegerNumber of resolved decisions that fell into this bucket

An empty array is returned if there are fewer resolved outcomes than needed to form reliable buckets.

Get Domain Accuracies

GET/api/scores/me/domains

Per-domain Brier score breakdown showing where your decision-making is strongest and weakest.

Example Request

bash
curl https://api.askverdict.ai/api/scores/me/domains \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Domain Field Reference

FieldTypeDescription
domainstringOne of: business, technology, health, legal, personal, finance, education, other
brierScorenumberBrier score for this domain (lower = better)
sampleSizeintegerNumber of resolved decisions in this domain
trendstringDirection of recent change: improving, stable, or declining

Streaks

Streaks measure how consistently you are using AskVerdict. A streak counts consecutive calendar days (UTC) on which you created at least one debate.

Get Streaks

GET/api/streaks

Retrieve current streak, all-time longest streak, total debate count, and milestone progress.

Example Request

bash
curl https://api.askverdict.ai/api/streaks \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Response Fields

FieldTypeDescription
currentStreakintegerConsecutive days ending today (or yesterday if no debate yet today)
longestStreakintegerAll-time longest consecutive-day run
totalDebatesintegerTotal non-deleted debates ever created
milestonesarrayProgress toward milestone thresholds: 10, 25, 50, 100, 250, 500 debates
milestones[].countintegerThe milestone total debate count
milestones[].reachedbooleanWhether this milestone has been reached
milestones[].reachedAtstring?ISO timestamp of the debate that crossed this threshold

Error Responses

CodeErrorDescription
500STREAKS_ERRORInternal error computing streak data

Decision Chains

Decision chains let you group related debates into a connected narrative — tracking how one decision leads to follow-up questions, reversals, or refinements over time.

Create a Chain

POST/api/chains

Create a new decision chain starting from a root debate.

Request Body

NameTypeRequiredDescription
namestringRequiredDescriptive name for this chain. 1–200 characters.
rootDebateIdstring (UUID)RequiredThe UUID of the first debate in the chain.

Example Request

bash
curl -X POST https://api.askverdict.ai/api/chains \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Infrastructure Decisions",
    "rootDebateId": "dbt_abc123"
  }'

Response

Error Responses

CodeErrorDescription
400VALIDATION_ERRORInvalid name or rootDebateId is not a valid UUID
404NOT_FOUNDrootDebateId does not exist or does not belong to you

List Chains

GET/api/chains

List all decision chains belonging to the authenticated user.

Example Request

bash
curl https://api.askverdict.ai/api/chains \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Get Chain Detail

GET/api/chains/:id

Fetch the full chain with all linked debate nodes.

Path Parameters

NameTypeRequiredDescription
idstringRequiredThe chain UUID.

Example Request

bash
curl https://api.askverdict.ai/api/chains/chn_def456 \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Error Responses

CodeErrorDescription
404NOT_FOUNDChain does not exist or does not belong to you

Add Debate to Chain

POST/api/chains/:id/debates

Link an existing debate into a chain, specifying its parent and relationship type.

Path Parameters

NameTypeRequiredDescription
idstringRequiredThe chain UUID.

Request Body

NameTypeRequiredDescription
debateIdstring (UUID)RequiredThe UUID of the debate to add to the chain.
parentDebateIdstring (UUID)RequiredThe UUID of the debate this one follows from.
relationshipstringRequiredHow this debate relates to its parent. One of: 'follow_up', 'reversal', 'refinement'.

Relationship Types

ValueWhen to Use
follow_upThis debate asks the next logical question given the parent verdict
reversalNew information caused you to question or reverse the parent decision
refinementThis debate narrows or sharpens the scope of the parent question

Example Request

bash
curl -X POST https://api.askverdict.ai/api/chains/chn_def456/debates \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "debateId": "dbt_ghi789",
    "parentDebateId": "dbt_abc123",
    "relationship": "follow_up"
  }'

Response

Error Responses

CodeErrorDescription
400VALIDATION_ERRORInvalid UUID or relationship value
404NOT_FOUNDChain or debate does not exist, or does not belong to you

Delete Chain

DELETE/api/chains/:id

Permanently delete a decision chain. Does not delete the linked debates.

Path Parameters

NameTypeRequiredDescription
idstringRequiredThe chain UUID.

Example Request

bash
curl -X DELETE https://api.askverdict.ai/api/chains/chn_def456 \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Returns 204 No Content on success.

Error Responses

CodeErrorDescription
404NOT_FOUNDChain does not exist or does not belong to you

Get Chain Context

GET/api/chains/:id/context

Get a summarized context object from a chain, suitable for injecting into new debates.

When you start a new debate and want it to be aware of prior related decisions, use this endpoint to retrieve a compact summary. Pass the returned context as the context field when creating a new verdict.

Path Parameters

NameTypeRequiredDescription
idstringRequiredThe chain UUID.

Example Request

bash
curl https://api.askverdict.ai/api/chains/chn_def456/context \
  -H "Authorization: Bearer vrd_your_api_key"

Response

Error Responses

CodeErrorDescription
404NOT_FOUNDChain does not exist or does not belong to you

Similar Debates

Find debates that are semantically similar to a query string using vector embeddings.

Find Similar Debates

GET/api/similar

Find past debates semantically similar to a natural-language question.

This endpoint uses vector similarity search (pgvector) to surface debates from your history that are close in meaning to a new question you are considering. If no embedding key is configured, the endpoint returns an empty result set rather than an error.

Query Parameters

NameTypeRequiredDescription
qstringRequiredThe natural-language question to search against. Cannot be empty.
limitintegerOptionalMaximum results to return. Clamped to 1–20. Default: 5.

Example Request

bash
curl "https://api.askverdict.ai/api/similar?q=Should+we+outsource+our+DevOps+team&limit=5" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

When no embedding provider key is available, the response is { "results": [] } with status 200.

Error Responses

CodeErrorDescription
400MISSING_QUERYq parameter was omitted or empty
500SIMILAR_SEARCH_FAILEDUnexpected error during similarity search

Recommendations

GET/api/recommendations

Get personalized debate recommendations based on your history, or trending debates for new users.

For users with at least 3 past debates, recommendations are based on keyword matching against your recent debate topics. For new users, trending public debates from the last 30 days are returned instead.

Query Parameters

NameTypeRequiredDescription
limitintegerOptionalNumber of recommendations to return. Clamped to 1–20. Default: 10.

Example Request

bash
curl "https://api.askverdict.ai/api/recommendations?limit=5" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

The recommendationReason field is either "Based on your interests" (personalized) or "Trending on AskVerdict" (fallback for new users).

Error Responses

CodeErrorDescription
500RECOMMENDATIONS_FAILEDInternal error loading recommendations

Was this page helpful?

PreviousBilling & CreditsNextWorkspaces