Ivorleaf Developers

Your First Validation

The canonical POST /v1/validation response should be read in this order:

Determination → Relationships → Signals → Provenance

Start with the Quickstart. A completed response describes what the evidence supports. Explicit acquisition returns inspected source passages with acquired provenance. Supplied text remains unchanged and accompanying citations are not independently verified. See Source Inspection.

Determination

A completed validation returns HTTP 200, status: "completed", and one overall determination. POST may first return 202 in_progress; use GET retrieval to obtain its state. The four completed determinations are:

  • supported
  • unsupported
  • conflicting
  • uncertain

All four values are valid completed outcomes. In particular, uncertain means the supplied evidence does not support a more decisive semantic result; it is not an execution or infrastructure failure. See Errors for execution failure mappings and stored failed states.

Use reason_code and reason to explain the canonical basis for the determination. Do not substitute a confidence threshold or derive a different overall result by counting relationship labels.

Relationships

information_units contains the material units derived from the supplied information. evidence contains canonical evidence material and source metadata, including duplicate lineage where applicable. relationships connects every information unit to every independent evidence item with one of:

  • supports
  • contradicts
  • partial
  • overstated
  • unrelated

Relationships explain the pairwise evidence structure; determination remains the authoritative overall completed outcome.

Signals

signals provides deterministic descriptions of the completed evidence structure:

  • grounding: strong, partial, absent, or mixed
  • relevance: high, partial, low, or mixed
  • conflict: none, present, material, or mixed
  • coverage: complete, partial, insufficient, or mixed

Signals are not confidence scores and do not replace the determination.

Provenance

provenance connects the validation ID, information-unit IDs, evidence IDs, relationships, unit determinations, overall determination and reason code, and signals. It is the public lineage for inspecting how the response fits together.

See Determinations and Relationships and Signals and Provenance for field-level interpretation.

Advanced: Technical Session metadata

Technical Sessions and packaged workflows retain additional legacy validation surfaces. These fields apply only to those advanced persistent workflows; they are not the canonical /v1/validation response and must not be used to reinterpret its determination.

Gate technical-session analysis

type Analysis = {
  confidence?: number;
  assumptions?: string[];
  unknowns?: string[];
  risks?: Array<{ severity?: string; description?: string }>;
  sources?: unknown[];
  validation_status?: {
    grounded?: boolean;
    official_documentation_used?: boolean;
    conflicting_sources_detected?: boolean;
    human_review_recommended?: boolean;
    validation_level?: "strong" | "moderate" | "limited";
  };
};

const analyses: Analysis[] = response.technical_analysis?.analyses ?? [];
const reviewRequired = analyses.some((analysis) =>
  analysis.validation_status?.human_review_recommended === true ||
  analysis.validation_status?.conflicting_sources_detected === true ||
  analysis.validation_status?.grounded !== true
);

if (reviewRequired) await routeToReviewer(response);
else await continueWorkflow(response.session_id);

technical_analysis remains an optional untyped object in the Technical Session public model, so validate it at runtime. Its per-analysis confidence is a 0–1 value; do not invent a universal cutoff. Combine it with that workflow's validation level, grounding, conflicts, risks, assumptions, and unknowns according to your review policy.

Show assumptions and unknowns next to generated content. For implementation packages, inspect blocking_unknowns separately. Present session sources with citation_warnings; official_documentation_used does not mean every source is official.

For a validated workflow, check validation_summary.human_review_recommended. For an implementation package, check validation.human_review_required, human_review_reasons, and preparation status. Recommend and Continue can skip continuation when saved workflow risk requires review.

Continue to follow Session Validation Metadata and Human Review. Log identifiers, levels, booleans, risk categories, and warnings rather than API keys, confidential prompts, or sensitive artifact content.