Documentation

EntityRoot V1 API - Verified business facts for AI systems

Quick Start

  1. 1

    Create an Account

    Sign up at entity-root.com/register

  2. 2

    Verify Your Domain

    Add a DNS TXT record to prove domain ownership

  3. 3

    Enter Business Facts

    Add your business name, address, phone, hours, and service areas

  4. 4

    Publish

    Your facts are cryptographically signed and made available via API

Public API Endpoints

GET/ai/entity/{id}

Returns cryptographically signed business facts for an entity.

Example Response
{
  "entity_id": "uuid",
  "facts": {
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "Example Business",
    "telephone": "+61 2 1234 5678",
    "address": {...}
  },
  "signature": "ed25519-sig-v1:...",
  "key_id": "prod-key-001",
  "issued_at": "2026-03-08T12:00:00Z"
}
GET/ai/trust-score/{id}

Returns the EntityRoot V1 Identity Trust Score (0-100).

Example Response
{
  "entity_id": "uuid",
  "score": 85,
  "label": "EntityRoot V1 Identity Trust Score",
  "factors": {
    "identity_completeness": 25,
    "signing_status": 25,
    "schema_compliance": 20,
    "verification_depth": 15
  }
}
GET/ai/verify/{id}

Returns verification data with masked PII for public display.

GET/.well-known/entityroot.json

Discovery endpoint for AI systems to find EntityRoot APIs.

GET/llms.txt

Machine-readable entity summary for LLM consumption.

GET/health

Health check endpoint for monitoring.

Rate Limiting

API endpoints are rate-limited to ensure fair usage:

EndpointRateBurst
/ai/*10 req/sec100 requests
/facts/*10 req/sec100 requests
/api/v1/*~1.7 req/sec100 requests

429 Too Many Requests: If rate limited, wait and retry. The Retry-After header indicates when to retry.

Human Verification Page

Each published entity has a public verification page at:

https://www.entity-root.com/verify/{entityId}

This page displays:

  • Business name and trading name
  • Masked contact info (privacy-safe)
  • City/State/Country location
  • Verification status and trust score
  • Cryptographic signature validation

Signature Verification

All fact bundles are signed using Ed25519 cryptographic signatures. To verify:

  1. Fetch the public key from /api/v1/keys/public
  2. Extract the signature from the signature field
  3. Verify the signature against the canonical JSON of the facts

Signature Format: ed25519-sig-v1:{base64-signature}

Cloudflare Edge Integration

EntityRoot can deploy a Cloudflare Worker to your domain that automatically:

  • Detects 30+ AI bots (GPTBot, ClaudeBot, Googlebot, etc.)
  • Injects JSON-LD structured data for bot requests
  • Adds X-Entity-Trace headers for debugging
  • Fails open - never breaks your site

X-Entity-Trace Header

The Cloudflare Worker adds this header to all responses:

X-Entity-Trace: INJECTED;12;OK;v1
StatusMeaning
INJECTEDJSON-LD injected for bot request
SKIPPEDHuman traffic, no injection
FAIL_OPENError occurred, original site served