# Verdict

> Verdict answers the questions an AI agent asks in the middle of its work (is this firm in my ICP, does this event matter now, who should I write to, what does this reply mean) as a calibrated probability with a reason code and cited evidence. One API key. Priced per decision. Misses, errors and refused calls are never billed.

- Base URL: `https://api.askverdict.io/v1`. JSON only. API version `2026-11-01` (pin it with `X-Verdict-Version`).
- Auth: `Authorization: Bearer vd_live_...` (test keys start `vd_test_`). Get a key with `POST /v1/signup`, then `POST /v1/signup/verify`. Starter credit: $5, no card.
- Send `Idempotency-Key: <uuid>` on every POST. A repeat within 24 hours returns the stored response and bills nothing.
- Cap spend per call with `X-Max-Cost-USD`. A call that would cost more is refused with 402 before any spend.
- Errors are RFC 9457 problem details. Branch on `type`. Every error has a `request_id`.
- Every decision returns `p` (calibrated), `answer` (branch on this), `reason_code`, `evidence`, `cost` and `balance_usd`. Report what happened next with `POST /v1/outcomes` (free).
- Everything at once: https://askverdict.io/llms-full.txt. OpenAPI 3.1: https://docs.askverdict.io/openapi.json.

## Start here

- [Verdict docs](https://docs.askverdict.io/index.md): Decisions for AI agents, as calibrated probabilities. One key, priced per decision, misses free.
- [Quickstart](https://docs.askverdict.io/quickstart.md): Sign up, get a key, create an ICP and make a first qualify_firm call in under fifteen minutes. Curl first, then the SDK.
- [Concepts](https://docs.askverdict.io/concepts.md): The nine nouns of the Verdict API (org, project, key, ICP, firm, event, decision, outcome, watch) and how they connect.

## Decisions

- [Decisions](https://docs.askverdict.io/decisions.md): The six priced calls, when to call each one, what each costs and what the common envelope returns.
- [qualify_firm](https://docs.askverdict.io/decisions/qualify_firm.md): Is this firm in my ICP? Returns fit as a calibrated probability, the resolved firm and cited evidence. $0.005 per answer.
- [score_signal](https://docs.askverdict.io/decisions/score_signal.md): Does this event matter for my offer, and is now the time? Returns relevant and act_now as calibrated probabilities. $0.005 per answer.
- [pick_person](https://docs.askverdict.io/decisions/pick_person.md): Who at this firm should I write to? Ranks a roster of up to 50 people, each with a probability. $0.005 per call.
- [triage_reply](https://docs.askverdict.io/decisions/triage_reply.md): What does this reply mean? Classifies a thread into one of thirteen states with a next action. $0.003 per answer.
- [right_person](https://docs.askverdict.io/decisions/right_person.md): Is this contact the right one for my ICP? Returns a calibrated probability and a reason code. $0.003 per answer.
- [should_send](https://docs.askverdict.io/decisions/should_send.md): Should this prepared message go out now? Checks the message, the decisions behind it and your inbox health. $0.003 per answer.

## Guides

- [Outcomes and the feedback loop](https://docs.askverdict.io/outcomes.md): Report what happened after a decision. Outcomes are free and unlimited, and they calibrate p and tune your thresholds.
- [Closing the loop](https://docs.askverdict.io/closing-the-loop.md): Tag every send with the decision behind it, so outcomes find their way back to Verdict. The decision id, the X-Verdict-Decision header, the verdict_decision_id custom field and POST /v1/outcomes.
- [Watches and webhooks](https://docs.askverdict.io/watches.md): Have scored events for an ICP pushed to your HTTPS endpoint as they land. Signed deliveries, retried for 24 hours, one score_signal per delivered event.
- [Errors](https://docs.askverdict.io/errors.md): Every error type with its HTTP status, what it means, whether to retry and what to do. Errors are never billed.
- [Versioning](https://docs.askverdict.io/versioning.md): How API versions work (dated, pinned per key, twelve months of overlap) and how question-set versions are recorded on every decision.
- [Use Verdict as tools in an agent](https://docs.askverdict.io/agent-tools.md): Add the six decisions, ICP calls and outcome reporting to a Vercel AI SDK, Anthropic or OpenAI agent in a few lines with @verdict/sdk/tools. Auth, idempotency, retries and 503 handling are done for you.

## Account and trust

- [Pricing](https://docs.askverdict.io/pricing.md): List prices per decision, what is free, starter credit, packs and the rules that keep misses free.
- [Security overview](https://docs.askverdict.io/security.md): How Verdict protects keys, data and tenants. Written for the security review of a customer evaluating the API.
- [Data sources and licences](https://docs.askverdict.io/sources.md): Every source in Verdict's index, its licence, attribution, refresh cadence and rate limit, and the GET /v1/sources response.

## API: Decisions

- [POST /v1/decisions/qualify_firm](https://docs.askverdict.io/reference/qualify-firm.md): Is this firm in my ICP? Price: $0.005 per call, billed only when an answer is returned. Scope: `decisions:write`.
- [POST /v1/decisions/score_signal](https://docs.askverdict.io/reference/score-signal.md): Does this event matter, and is now the time? Price: $0.005 per call, billed only when an answer is returned. Scope: `decisions:write`.
- [POST /v1/decisions/pick_person](https://docs.askverdict.io/reference/pick-person.md): Who at this firm should I write to? Price: $0.005 per call, billed only when an answer is returned. Scope: `decisions:write`.
- [POST /v1/decisions/triage_reply](https://docs.askverdict.io/reference/triage-reply.md): What does this reply mean? Price: $0.003 per call, billed only when an answer is returned. Scope: `decisions:write`.
- [POST /v1/decisions/right_person](https://docs.askverdict.io/reference/right-person.md): Is this the right person to contact? Price: $0.003 per call, billed only when an answer is returned. Scope: `decisions:write`.
- [POST /v1/decisions/should_send](https://docs.askverdict.io/reference/should-send.md): Should this message go out now? Price: $0.003 per call, billed only when an answer is returned. Scope: `decisions:write`.
- [GET /v1/decisions/{id}](https://docs.askverdict.io/reference/get-decision.md): Get a decision Price: free. Scope: `decisions:write`.

## API: Index

- [GET /v1/firms/resolve](https://docs.askverdict.io/reference/resolve-firm.md): Resolve a firm reference Price: free. Scope: `index:read`.
- [GET /v1/firms/{id}](https://docs.askverdict.io/reference/get-firm.md): Get a firm Price: free. Scope: `index:read`.
- [GET /v1/events](https://docs.askverdict.io/reference/list-events.md): List events Price: free unscored; with `icp_id` each scored event bills one `score_signal` ($0.005). Scope: `index:read`.
- [GET /v1/sources](https://docs.askverdict.io/reference/list-sources.md): List index sources Price: free. Scope: `index:read`.

## API: Watches

- [GET /v1/watches](https://docs.askverdict.io/reference/list-watches.md): List watches Price: free. Scope: `watches:manage`.
- [POST /v1/watches](https://docs.askverdict.io/reference/create-watch.md): Create a watch Price: free to create; each delivered event bills one `score_signal` ($0.005). Scope: `watches:manage`.
- [GET /v1/watches/{id}](https://docs.askverdict.io/reference/get-watch.md): Get a watch Price: free. Scope: `watches:manage`.
- [DELETE /v1/watches/{id}](https://docs.askverdict.io/reference/delete-watch.md): Delete a watch Price: free. Scope: `watches:manage`.
- [GET /v1/watches/{id}/deliveries](https://docs.askverdict.io/reference/list-watch-deliveries.md): List a watch's deliveries Price: free. Scope: `watches:manage`.
- [POST <your webhook_url> (scoredEvent)](https://docs.askverdict.io/reference/scored-event-webhook.md): A scored event for a watch Price: bills one `score_signal` ($0.005) when delivered, never per retry. Scope: none (Verdict calls you; verify `Verdict-Signature`).
- [POST <your webhook_url> (watchChallenge)](https://docs.askverdict.io/reference/watch-challenge-webhook.md): Verify a new webhook URL Price: free. Scope: none (Verdict calls you; verify `Verdict-Signature`).

## API: Outcomes

- [POST /v1/outcomes](https://docs.askverdict.io/reference/create-outcome.md): Report an outcome Price: free. Scope: `outcomes:write`.

## API: Inbound webhooks

- [POST /v1/webhooks/instantly/{receiver_token}](https://docs.askverdict.io/reference/receive-instantly-webhook.md): Receive Instantly webhooks Price: free. Scope: none (public endpoint).
- [POST /v1/webhooks/smartlead/{receiver_token}](https://docs.askverdict.io/reference/receive-smartlead-webhook.md): Receive Smartlead webhooks Price: free. Scope: none (public endpoint).
- [POST /v1/webhooks/calcom/{receiver_token}](https://docs.askverdict.io/reference/receive-calcom-webhook.md): Receive Cal.com webhooks Price: free. Scope: none (public endpoint).
- [POST /v1/webhooks/calendly/{receiver_token}](https://docs.askverdict.io/reference/receive-calendly-webhook.md): Receive Calendly webhooks Price: free. Scope: none (public endpoint).
- [POST /v1/webhooks/stripe](https://docs.askverdict.io/reference/receive-stripe-webhook.md): Receive Stripe webhooks Price: free. Scope: none (public endpoint).

## API: ICP profiles

- [GET /v1/icps](https://docs.askverdict.io/reference/list-icps.md): List ICP profiles Price: free. Scope: `decisions:write`.
- [POST /v1/icps](https://docs.askverdict.io/reference/create-icp.md): Create an ICP profile Price: free. Scope: `decisions:write`.
- [GET /v1/icps/{id}](https://docs.askverdict.io/reference/get-icp.md): Get an ICP profile Price: free. Scope: `decisions:write`.
- [PATCH /v1/icps/{id}](https://docs.askverdict.io/reference/update-icp.md): Update an ICP profile Price: free. Scope: `decisions:write`.
- [PATCH /v1/icps/{id}/thresholds](https://docs.askverdict.io/reference/update-icp-thresholds.md): Set decision thresholds Price: free. Scope: `account:manage`.

## API: Account

- [POST /v1/signup](https://docs.askverdict.io/reference/signup.md): Sign up Price: free. Scope: none (public endpoint).
- [POST /v1/signup/verify](https://docs.askverdict.io/reference/verify-signup.md): Verify sign-up and get a key Price: free. Scope: none (public endpoint).
- [GET /v1/me](https://docs.askverdict.io/reference/get-me.md): Who am I Price: free. Scope: any valid API key.
- [GET /v1/keys](https://docs.askverdict.io/reference/list-keys.md): List API keys Price: free. Scope: `keys:manage`.
- [POST /v1/keys](https://docs.askverdict.io/reference/create-key.md): Create an API key Price: free. Scope: `keys:manage`.
- [PATCH /v1/keys/{id}](https://docs.askverdict.io/reference/update-key.md): Change an API key Price: free. Scope: `keys:manage`.
- [DELETE /v1/keys/{id}](https://docs.askverdict.io/reference/revoke-key.md): Revoke an API key Price: free. Scope: `keys:manage`.
- [POST /v1/keys/{id}/rotate](https://docs.askverdict.io/reference/rotate-key.md): Rotate an API key Price: free. Scope: `keys:manage`.
- [GET /v1/limits](https://docs.askverdict.io/reference/get-limits.md): Get limits Price: free. Scope: `account:read`.
- [GET /v1/audit](https://docs.askverdict.io/reference/list-audit.md): List audit log entries Price: free. Scope: `account:read`.

## API: Billing

- [GET /v1/balance](https://docs.askverdict.io/reference/get-balance.md): Get the balance Price: free. Scope: `account:read`.
- [POST /v1/topup](https://docs.askverdict.io/reference/create-topup.md): Buy a credit pack Price: free. Scope: `account:manage`.
- [GET /v1/usage](https://docs.askverdict.io/reference/get-usage.md): Get usage Price: free. Scope: `account:read`.
- [GET /v1/ledger](https://docs.askverdict.io/reference/list-ledger.md): List ledger entries Price: free. Scope: `account:read`.

## API: Console

- [POST /v1/console/magic-link](https://docs.askverdict.io/reference/request-magic-link.md): Email a console sign-in link Price: free. Scope: none (public endpoint).
- [POST /v1/console/magic-link/consume](https://docs.askverdict.io/reference/consume-magic-link.md): Sign in with a magic link Price: free. Scope: none (public endpoint).
- [POST /v1/console/oauth/github/start](https://docs.askverdict.io/reference/start-github-oauth.md): Start GitHub sign-in Price: free. Scope: none (public endpoint).
- [POST /v1/console/oauth/github/callback](https://docs.askverdict.io/reference/github-oauth-callback.md): Finish GitHub sign-in Price: free. Scope: none (public endpoint).
- [GET /v1/console/session](https://docs.askverdict.io/reference/get-console-session.md): Get the console session Price: free. Scope: console session cookie (not an API key).
- [DELETE /v1/console/session](https://docs.askverdict.io/reference/sign-out.md): Sign out Price: free. Scope: console session cookie (not an API key).
- [POST /v1/console/totp/enrol](https://docs.askverdict.io/reference/enrol-totp.md): Start TOTP enrolment Price: free. Scope: console session cookie (not an API key).
- [POST /v1/console/totp/verify](https://docs.askverdict.io/reference/verify-totp.md): Verify a TOTP code Price: free. Scope: console session cookie (not an API key).
- [POST /v1/console/totp/disable](https://docs.askverdict.io/reference/disable-totp.md): Turn TOTP off Price: free. Scope: console session cookie (not an API key).
- [GET /v1/console/orgs](https://docs.askverdict.io/reference/list-console-orgs.md): List my organizations Price: free. Scope: console session cookie (not an API key).
- [GET /v1/console/orgs/{org_id}/members](https://docs.askverdict.io/reference/list-members.md): List members Price: free. Scope: console session cookie (not an API key).
- [POST /v1/console/orgs/{org_id}/invites](https://docs.askverdict.io/reference/create-invite.md): Invite a member Price: free. Scope: console session cookie (not an API key).
- [PATCH /v1/console/orgs/{org_id}/members/{user_id}](https://docs.askverdict.io/reference/update-member.md): Change a member's role Price: free. Scope: console session cookie (not an API key).
- [DELETE /v1/console/orgs/{org_id}/members/{user_id}](https://docs.askverdict.io/reference/remove-member.md): Remove a member Price: free. Scope: console session cookie (not an API key).
- [GET /v1/console/orgs/{org_id}/audit](https://docs.askverdict.io/reference/list-console-audit.md): List audit log entries (console) Price: free. Scope: console session cookie (not an API key).

## Optional

- [Changelog](https://docs.askverdict.io/changelog.md): Changes to the Verdict API and docs, newest first. Breaking changes get a new dated API version.
- [Status](https://docs.askverdict.io/status.md): Where to check the live health of the Verdict API, decisions, MCP server, index freshness and console.
- [Eval results](https://docs.askverdict.io/evals.md): Precision, recall and F1 per decision and question-set version, with where each labeled set comes from.
- [Terms of service](https://docs.askverdict.io/legal/terms.md): Terms of service for Verdict. Draft, not yet reviewed by counsel.
- [Privacy policy](https://docs.askverdict.io/legal/privacy.md): Privacy policy for Verdict. Draft, not yet reviewed by counsel.
- [Data processing addendum](https://docs.askverdict.io/legal/dpa.md): Data processing addendum for Verdict. Draft, not yet reviewed by counsel.
- [Acceptable use policy](https://docs.askverdict.io/legal/acceptable-use.md): Acceptable use policy for Verdict. Draft, not yet reviewed by counsel.
- [Subprocessors](https://docs.askverdict.io/legal/subprocessors.md): Subprocessors for Verdict. Draft, not yet reviewed by counsel.