POST `/v1/validation`

Submit information and evidence to determine what the evidence actually supports. Start with the executable Quickstart.

POST https://api.ivorleaf.io/v1/validation
X-API-Key: ivl_...
X-Ivorleaf-Client: api
Idempotency-Key: validation-example-001
Content-Type: application/json
Prefer: respond-async

Idempotency-Key is required: 8–128 letters, numbers, periods, underscores, colons, or hyphens. Prefer: respond-async is optional and recommended when your integration can handle accepted work.

Request

{
  "information": {
    "text": "H2O is the chemical formula for water."
  },
  "evidence": [
    {
      "text": "The chemical formula for water is H2O."
    }
  ]
}

ValidationRequest has exactly information and evidence. information.text and every evidence item's text must be nonblank; evidence must contain at least one item. Undeclared fields are rejected. Each evidence item may have source with optional title and url.

Nonblank evidence.text is evaluated unchanged. Optional source metadata is provenance only and triggers no acquisition. An explicit acquire object requests public-source inspection; text and acquire are mutually exclusive. Inspection failure fails closed without substituting caller text. See Source Inspection.

Responses

HTTP	Body	Action
`200`	`ValidationResponse`, `status: "completed"`	Read the determination and relationships.
`202`	`ValidationInProgress`, `status: "in_progress"`, `validation_id`	Accepted and still active; retrieve with GET.

With async acceptance, fast completion can return 200; work still active at the 20-second sync boundary can return 202. Hybrid execution has a 60-second provider budget and 90-second hard deadline. Without the preference, synchronous qualified compatibility uses a 20-second provider timeout. See Async Execution.

Completed result

A completed response includes validation_id, status, determination, reason_code, reason, information, information_units, evidence, relationships, signals, and provenance.

information preserves the supplied information. Explicit acquisition returns selected source passages as evidence.text; supplied text remains unchanged. Per-item provenance origin is supplied or acquired. Duplicate evidence remains traceable through duplicate_of.

The exact determinations are supported, unsupported, conflicting, and uncertain. Relationships are supports, contradicts, partial, overstated, and unrelated. Read Determinations and Relationships.

Signals

grounding, relevance, conflict, and coverage are categorical summaries derived from the completed canonical graph. See Signals and Provenance.

Provenance

Provenance connects validation, information units, evidence, relationships, unit determinations, determination, and signals through canonical IDs. Public provenance does not promise private inspection proof fields.

Idempotency and usage

Same key plus same canonical request reuses execution according to state. A completed replay returns the stored result with zero inference, zero inspection, and zero additional VUs. Different payload with the same key returns 409. Read Idempotency and Validation Units.

Errors

POST declares 401, 403, 409, 422, 429, 500, 502, 503, and 504. Source Inspection failure is 502. Errors never become an uncertain determination. See Errors and the authoritative production API Reference.

POST /v1/validation