Ancestor
Ancestor
DocumentationPricingDashboardReference Lens
API v1.0 STABLE

API Documentation

Enterprise-grade verification infrastructure for AI systems

WHAT_THIS_API_IS:

Ancestor is a deterministic verification engine for AI systems. It evaluates whether a given source supports, contradicts, or fails to justify a claim, producing an auditable trust score with a full reasoning breakdown.

WHAT_THIS_API_IS_NOT:

  • Not a fact-checking service
  • Not a search engine
  • Not a truth oracle
  • Ancestor judges citation behavior, not belief
SYSTEM_ARCHITECTURE

Core Concept

INPUT_PARAMETERS

Ancestor accepts three inputs:

C

Claim

A natural-language assertion (e.g. "revenue grew 5%")

S

Source

A URL or raw document text

M

Metadata (Optional)

Publication date, domain authority

SIGNAL_PROCESSING

Ancestor computes four weighted signals:

40
ENTAILMENT

Does the source logically support the claim?

30
PROVENANCE

Is the publisher authoritative?

20
RECENCY

Is the information current?

10
INTEGRITY

Is the content structurally credible?

TRUST_ALGORITHM

Trust Score Model

(THE GLASS BOX)

We do not use black box AI scoring. The formula is deterministic:

SCORE_CALCULATION:
Score = (entailment × 0.40) + (provenance × 0.30) + (recency × 0.20) + (integrity × 0.10)

KILL_SWITCH (Hard Invariant)

If Contradiction > 0.5, the Final Score is forced to 0, regardless of how prestigious the source is.

A HIGH-AUTHORITY LIE IS STILL A LIE

SECURITY_PROTOCOL

Authentication

(MACHINE IDENTITY ONLY)

AUTH_FORMAT

FORMAT:Bearer Token
PREFIX:anc_live_...
HEADER:
Authorization: Bearer anc_live_55a...

SECURITY_RULES

Keys authenticate machines, not humans
Keys must be used server-side only
Keys are shown once at creation and never emailed
REQUEST_PROTOCOL

Making a Verification Request

(ASYNCHRONOUS)

Because deep NLI verification is computationally intensive, the API uses an asynchronous Job pattern.

1

STEP_1: Submit Job

POST /api/v1/verify
{ "claim": "Vaccines are effective at preventing measles", "source_url": "https://www.who.int/news-room/fact-sheets/detail/measles" }

Response (Immediate):

HTTP 202 Accepted
{ "job_id": "job_8f7a1b...", "status": "PROCESSING", "poll_url": "/api/v1/jobs/job_8f7a1b..." }
2

STEP_2: Poll for Results

GET /api/v1/jobs/job_8f7a1b...
curl -H "Authorization: Bearer anc_live_your_key" \\
     https://api.ancestor.cloud/v1/jobs/job_8f7a1b...
RESPONSE_SCHEMA

Response Structure

(THE RESULT)

Once status: "COMPLETED", the response contains:

{ "id": "job_8f7a1b...", "status": "COMPLETED", "result": { "trust_score": 92, "label": "SUPPORTED", "breakdown": { "entailment": 0.94, "provenance": 100, "recency": 90, "integrity": 95 }, "ancestry_id": "anc_log_9f31a2..." // Link to immutable audit log } }

RESULT_LABELS:

SUPPORTED
Score > 70
UNCERTAIN
Score 30-70
CONTRADICTION
Score < 30 or Kill Switch
UNVERIFIABLE
Source unavailable/404
ERROR_HANDLING

Error Semantics & Limits

HTTP_STATUS_CODES

400Bad Request: Malformed JSON or missing fields
401Unauthorized: Invalid/Revoked Key
402Payment Required: Billing Past Due or Quota Exceeded
413Payload Too Large: Content exceeds 5MB or 20k chars
429Too Many Requests: Rate limit hit

IMPORTANT_NOTE

A Trust Score of 0 is NOT an error.
It is a successful detection of a contradiction.

CODE_EXAMPLES

Code Examples

CURL_REQUEST

curl -X POST https://api.ancestor.cloud/v1/verify \ -H "Authorization: Bearer anc_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "claim": "COVID vaccines are safe and effective", "source_url": "https://www.cdc.gov/coronavirus/2019-ncov/vaccines/" }'

JAVASCRIPT_FETCH

const response = await fetch('https://api.ancestor.cloud/v1/verify', { method: 'POST', headers: { 'Authorization': 'Bearer anc_live_your_key_here', 'Content-Type': 'application/json' }, body: JSON.stringify({ claim: "Renewable energy costs have decreased", source_url: "https://example.com/renewable-energy-report" }) }); const job = await response.json(); console.log('Job ID:', job.job_id);

PYTHON_REQUESTS

import requests response = requests.post( 'https://api.ancestor.cloud/v1/verify', headers={ 'Authorization': 'Bearer anc_live_your_key_here', 'Content-Type': 'application/json' }, json={ 'claim': 'Electric vehicles have lower emissions', 'source_url': 'https://example.com/ev-emissions-study' } ) job = response.json() print(f"Job ID: {job['job_id']}")
BEST_PRACTICES

Best Practices

Don't block your UI

Use the async job_id to show a "Verifying..." state.

Check the Amber Zone

Treat scores between 30–70 as "Human Review Required."

Rotate Keys

Use the dashboard to rotate keys monthly.

Fail Safe

If the API returns 500 or 429, fall back to "Verification Unavailable," not "False."

SYSTEM_LIMITATIONS

What Ancestor Will Never Do

Decide absolute truth
Rewrite your claims
Fetch arbitrary web data (we only fetch the specific source_url provided)
Provide moral or political judgments

ANCESTOR PROVIDES SIGNAL, NOT BELIEF

Quick Links

API Dashboard
Reference Lens
Ancestor
Ancestor
DocumentationReference LensContact

Ancestor Lab - Deterministic verification for the AI age.