Open Entity Data Protocol

1. Overview

The Open Entity Data Protocol provides a standard way for AI systems — LLM operators, AI application developers, retrieval-augmented generation (RAG) pipelines, and AI agents — to access verified, authoritative business data.

AITWIRE already serves this data at api.aitwire.com. This specification formalizes the endpoints, schemas, and discovery mechanisms so that any AI system can consume this data programmatically.

All endpoints are public, require no authentication, and are rate-limited at 120 requests per minute per IP address.

2. Discovery

AI systems discover entity authority data using the standard well-known endpoint:

GET /.well-known/entity.json?tenant={tenant_id}

# On a tenant's own domain (if Cloudflare edge is connected):
GET https://example.com/.well-known/entity.json

# Via AITWIRE's API:
GET https://api.aitwire.com/.well-known/entity.json?tenant={tenant_id}

The discovery flow for AI systems:

1. Check /.well-known/entity.json on the business's domain
2. If not found, use the Lookup API to resolve by domain or name
3. Parse the entity.json schema (aitwire.authority.graph.v1)
4. Follow feed URLs for structured product/service/article data
5. Respect purpose policies before using the data

3. The entity.json Document

The entity.json document is the canonical authority declaration for a business entity. Schema version: aitwire.authority.graph.v1.

{
  "schema_version": "aitwire.authority.graph.v1",
  "publisher": { "tenant": "<tenant_id>" },
  "subject": {
    "tenant": "<tenant_id>",
    "canonical_domains": ["example.com"]
  },
  "issued_at": <unix_timestamp>,
  "validity_window": {
    "not_before": <unix_timestamp>,
    "not_after": <unix_timestamp>
  },
  "endpoints": {
    "authority": "/.well-known/entity.json?tenant=...",
    "proofs": "/.well-known/authority.proofs.json?tenant=...",
    "governance": "/.well-known/ai-entity.json?tenant=..."
  },
  "surfaces": [ ... ],
  "proofs_index": [ ... ],
  "authority_rules": [ ... ],
  "claim_types": [ ... ],
  "feeds": [
    { "rel": "products", "href": "/feeds/products.json?tenant=..." },
    { "rel": "services", "href": "/feeds/services.json?tenant=..." },
    { "rel": "articles", "href": "/feeds/articles.json?tenant=..." },
    { "rel": "locations", "href": "/feeds/locations.json?tenant=..." },
    { "rel": "policies", "href": "/feeds/policies.json?tenant=..." }
  ]
}

Key Fields

• surfaces — digital properties the business controls (website, social, marketplace)
• proofs_index — cryptographic/DNS proofs of surface ownership
• authority_rules — which surfaces are authoritative for which claim types
• feeds — URLs for structured data feeds (products, services, articles, etc.)
• validity_window — when the document should be considered fresh; re-fetch after not_after

4. Lookup API

When an AI system doesn't know a business's tenant ID, use the Lookup API to resolve by domain or name:

# Lookup by domain
GET https://api.aitwire.com/v1/entity/lookup?domain=example.com

# Lookup by business name
GET https://api.aitwire.com/v1/entity/lookup?name=AITWIRE

The response includes the full entity authority data, feed URLs, and endpoint map:

{
  "ok": true,
  "tenant_id": "abc123",
  "business_name": "AITWIRE",
  "website": "https://aitwire.com",
  "entity_json_url": "https://api.aitwire.com/.well-known/entity.json?tenant=abc123",
  "feeds": {
    "products": "https://api.aitwire.com/feeds/products.json?tenant=abc123",
    "services": "https://api.aitwire.com/feeds/services.json?tenant=abc123",
    ...
  },
  "feed_summary": { "product": 42, "article": 15, "service": 8 },
  "authority": { ... },
  "_protocol": "aitwire.open-entity-data.v1"
}

5. Feed Endpoints

Feeds serve paginated, versioned entity data in JSON with JSON-LD Schema.org annotations. All feeds support conditional requests via ETag / If-None-Match.

• /feeds/products.json?tenant=X — product catalog
• /feeds/services.json?tenant=X — service offerings
• /feeds/articles.json?tenant=X — articles and content
• /feeds/locations.json?tenant=X — physical locations
• /feeds/policies.json?tenant=X — business policies

Query Parameters

• tenant (required) — tenant identifier
• limit — results per page (default 200, max 500)
• cursor — keyset pagination cursor from next_cursor
• since — unix timestamp for delta queries (entities updated after this time)

Feed Schema

{
  "ok": true,
  "tenant": "abc123",
  "type": "product",
  "results": [
    {
      "entity_id": "ent_abc",
      "type": "product",
      "canonical_url": "https://example.com/product/widget",
      "attribution_url": "https://example.com/product/widget?utm_source=aitwire&utm_medium=ai-citation",
      "updated_at": 1713000000,
      "version": 3,
      "hash": "a1b2c3..."
    }
  ],
  "next_cursor": "1713000000:ent_abc"
}

The attribution_url includes UTM parameters so businesses can track AI-driven citations in their analytics. AI systems should use attribution_url when generating citations.

6. Purpose Policies

Entity authority data includes purpose policies that declare how the data may be used. These are embedded in entity.json and enforced at the API level.

• training — using data to train AI models (often denied)
• inference — using data to ground AI responses (usually allowed)
• summarization — creating summaries of the data
• indexing — including data in search indices
• caching — caching data for later retrieval

If a purpose is denied, the API returns HTTP 451 (Unavailable For Legal Reasons) with a machine-readable explanation. AI systems must respect these policies.

7. Verification

All authority data includes cryptographic verification mechanisms:

• Proofs — DNS TXT, meta tag, JSON-LD, or .well-known file verification
• Signatures — HMAC signatures on the authority graph document
• Content hashes — SHA-256 hashes for entity version integrity
• ETag headers — deterministic ETags for conditional requests

The proofs endpoint at /.well-known/authority.proofs.json?tenant=X provides the full proof chain for all claimed surfaces.

8. Rate Limiting

All public endpoints are rate-limited at 120 requests per minute per IP address. Exceeding this limit returns HTTP 429 with a Retry-After header.

For higher throughput, use API keys (available with AITWIRE Business plans) which provide per-tenant rate limits instead of per-IP limits.

9. AI Crawler Directives

AITWIRE serves crawler directives at standard well-known paths:

• /.well-known/ai.txt?tenant=X — AI-specific crawler directives (like robots.txt for AI)
• /llms.txt?tenant=X — LLM-readable summary with authority document reference
• /schema/entity.jsonld?tenant=X — full JSON-LD schema for the entity

10. SDK & Integration

AITWIRE provides official SDKs for consuming the Open Entity Data Protocol:

TypeScript

import { EntityAuthority } from "@aitwire/sdk";

// Lookup by domain (no auth required)
const entity = await EntityAuthority.lookup("example.com");
console.log(entity.business_name);
console.log(entity.feeds.products);  // feed URL

// Lookup by business name
const entity2 = await EntityAuthority.lookupByName("AITWIRE");
console.log(entity2.authority);  // full entity.json

Python

from aitwire import EntityAuthority

# Lookup by domain
entity = EntityAuthority.lookup("example.com")
print(entity["business_name"])
print(entity["feeds"]["products"])

# Lookup by name
entity = EntityAuthority.lookup_by_name("AITWIRE")
print(entity["authority"])  # full entity.json

AI Gateway Tool

The entity lookup is also registered as a callable tool for AI systems using function-calling:

// Tool registration (OpenAI function-calling format)
GET https://api.aitwire.com/api/gateway/tools/registry

// Execute lookup
POST https://api.aitwire.com/api/gateway/tools/entity-lookup
{ "domain": "example.com" }