Ivorleaf Developers

Quickstart

Get your first determination using an Ivorleaf API key. Request a key if you need one; keep it in a trusted server environment.

1. Set your API key and request identity

export IVORLEAF_API_BASE_URL="https://api.ivorleaf.io"
export IVORLEAF_API_KEY="ivl_..."
export IVORLEAF_IDEMPOTENCY_KEY="validation-$(uuidgen)"

Save the key with this request. Generate a new idempotency key only for new logical work.

2. Submit information and evidence

curl --silent --show-error --fail-with-body --include \
  "$IVORLEAF_API_BASE_URL/v1/validation" \
  --header "X-API-Key: $IVORLEAF_API_KEY" \
  --header "X-Ivorleaf-Client: api" \
  --header "Idempotency-Key: $IVORLEAF_IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: respond-async" \
  --data '{"information":{"text":"H2O is the chemical formula for water."},"evidence":[{"text":"The chemical formula for water is H2O."}]}'

This inline example needs no source retrieval. The expected completed result is determination: "supported" with a supports relationship. Read the returned result rather than assuming success.

3. Handle 200 or 202

  • 200: execution completed. Read determination and relationships.
  • 202: accepted and still in_progress. Save the returned validation_id; there is no completed determination yet.

A 202 body has this shape (the ID below is illustrative):

{"validation_id":"VAL-EXAMPLE","status":"in_progress"}

4. Retrieve an accepted validation

Set the ID from your response, then make one GET request:

export IVORLEAF_VALIDATION_ID="VAL-EXAMPLE"
curl --silent --show-error --fail-with-body \
  "$IVORLEAF_API_BASE_URL/v1/validation/$IVORLEAF_VALIDATION_ID" \
  --header "X-API-Key: $IVORLEAF_API_KEY" \
  --header "X-Ivorleaf-Client: api"

GET returns HTTP 200 with status equal to in_progress, completed, or failed. Inspect the body. If still active, respect Retry-After before a later retrieval. GET performs no new inference or Source Inspection and adds zero VUs.

5. Read your first determination

determination describes overall evidence support. relationships connects each material information unit to each independent evidence item. signals summarizes the graph; provenance records its lineage.

All four determinations—supported, unsupported, conflicting, and uncertain—are completed outcomes. See Your First Validation.

Continue

A transport failure can leave the outcome unknown. Preserve the request and original key; use retrieval when you have the ID, or deliberate same-key replay. See Errors.