Documentation

Grounding API

Verify factual claims about entities against AITWIRE's verified authority data. Designed for search-based AI systems like Perplexity, Google, and RAG pipelines.

Endpoint

POST https://api.aitwire.com/api/grounding/verify
Content-Type: application/json

{
  "entity": "example.com",
  "claim": "They offer free shipping on orders over $50"
}

Response

{
  "ok": true,
  "status": "verified",          // verified | contradicted | unknown | no_entity
  "confidence": 0.85,            // 0.0 - 1.0
  "entity": "example.com",
  "entity_name": "Example Store",
  "claim": "They offer free shipping on orders over $50",
  "authoritative_fact": "policies: Free shipping on all orders over $50",
  "authority_facts_checked": 12,
  "source": {
    "tenant_id": "example-store",
    "entity_json_url": "https://api.aitwire.com/.well-known/entity.json?tenant=example-store",
    "protocol": "aitwire.open-entity-data.v1"
  }
}

Status Values

verified

The claim matches AITWIRE authority data with high confidence. The authoritative_fact field shows the matching data.

contradicted

The claim conflicts with authority data. The authoritative_fact shows what AITWIRE has on record.

unknown

The entity exists in AITWIRE but the claim cannot be verified or contradicted from available data.

no_entity

No AITWIRE entity authority found for this entity. The claim cannot be checked.

How It Works

  1. The entity is resolved via the Entity Lookup API
  2. Authority data is gathered from entity feeds (products, services, locations, policies)
  3. The claim is checked against the gathered facts using keyword matching
  4. A confidence score and status are returned

Future versions will use semantic similarity via embeddings for more accurate claim verification.

Use Cases

  • Search AI — Perplexity, Google AI can verify answers against authority data before presenting them
  • RAG pipelines — validate retrieved facts against the canonical source
  • Chatbots — fact-check responses about businesses in real-time
  • Content moderation — verify business claims in user-generated content

Self-Describing Schema

The Grounding API is self-describing:

GET https://api.aitwire.com/api/grounding/info

Returns the full schema, status definitions, and documentation links.

AI Systems PortalMCP ServerProtocol Spec