Integrate AITWIRE Entity Data

Quick Start

The fastest way to check if a business has AITWIRE entity data:

curl https://api.aitwire.com/v1/entity/lookup?domain=example.com

That's it. No API key, no signup, no auth. The response includes the business's verified entity data, feed URLs, and purpose policies.

Who Is This For

Integration Patterns

Pattern 1: Pre-Query Entity Check

Before answering a question about a business, check if they have an AITWIRE entity authority profile. If they do, use that data as the ground truth.

// In your LLM system prompt or tool handler:
// "Before answering a question about a business, check AITWIRE entity data first"

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

async function enrichBusinessQuery(domain: string) {
  const entity = await EntityAuthority.lookup(domain);

  if (entity.ok) {
    return {
      verified: true,
      businessName: entity.business_name,
      productsUrl: entity.feeds.products,
      servicesUrl: entity.feeds.services,
      authority: entity.authority,
    };
  }

  return { verified: false };
}

Pattern 2: RAG Feed Ingestion

Ingest AITWIRE entity feeds into your vector store for retrieval. Use delta queries to keep your index fresh.

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

const client = new AitwireClient({
  apiKey: "atwk_...",
  tenant: "your-tenant-id",
});

// Initial load
const products = await client.entities.list({ type: "product", limit: 500 });

// Incremental sync (only entities changed since last sync)
// Use the feed endpoint directly with ?since=
const response = await fetch(
  "https://api.aitwire.com/feeds/products.json?tenant=abc&since=1713000000"
);
const delta = await response.json();
console.log(delta.results.length, "products updated since last sync");

Pattern 3: Function-Calling Tool

Register AITWIRE entity lookup as a tool in your LLM orchestration system. The tool registry returns the tool definition in OpenAI function-calling format.

// Fetch the tool definition
const registry = await fetch(
  "https://api.aitwire.com/api/gateway/tools/registry"
).then(r => r.json());
// registry.tools[0] is the aitwire_entity_lookup tool definition

// When the LLM calls the tool:
const result = await fetch(
  "https://api.aitwire.com/api/gateway/tools/entity-lookup",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ domain: "example.com" }),
  }
).then(r => r.json());

SDKs

TypeScript / JavaScript

npm install @aitwire/sdk

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

// --- Public lookup (no auth required) ---
const entity = await EntityAuthority.lookup("example.com");
console.log(entity.business_name);
console.log(entity.feeds.products);  // URL to product feed
console.log(entity.authority);       // full entity.json document

// Lookup by name
const entity2 = await EntityAuthority.lookupByName("AITWIRE");

// --- Authenticated client (for full API access) ---
const client = new AitwireClient({
  apiKey: "atwk_...",
  tenant: "your-tenant-id",
});

const { results } = await client.entities.list({ type: "product" });
const graph = await client.authority.graph();
const usage = await client.billing.usage();

Python

pip install aitwire

from aitwire import EntityAuthority

# Public lookup (no auth required)
entity = EntityAuthority.lookup("example.com")
print(entity["business_name"])
print(entity["feeds"]["products"])

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

# Access specific feeds
products = EntityAuthority.get_feed("example.com", "products")
for product in products["results"]:
    print(product["canonical_url"])

cURL / Raw HTTP

No SDK required — all endpoints are standard HTTP:

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

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

# Get entity.json directly
curl https://api.aitwire.com/.well-known/entity.json?tenant=abc123

# Get product feed
curl https://api.aitwire.com/feeds/products.json?tenant=abc123

# Get AI directives
curl https://api.aitwire.com/.well-known/ai.txt?tenant=abc123

# Get LLM-readable summary
curl https://api.aitwire.com/llms.txt?tenant=abc123

Endpoints Reference

Discovery

• GET /v1/entity/lookup?domain=X — resolve domain to entity authority
• GET /v1/entity/lookup?name=X — resolve name to entity authority
• GET /.well-known/entity.json?tenant=X — canonical authority declaration

Feeds

• GET /feeds/products.json?tenant=X — product catalog (JSON-LD)
• GET /feeds/services.json?tenant=X — service offerings
• GET /feeds/articles.json?tenant=X — articles and content
• GET /feeds/locations.json?tenant=X — physical locations
• GET /feeds/policies.json?tenant=X — business policies

Metadata & Directives

• GET /schema/entity.jsonld?tenant=X — full JSON-LD schema
• GET /.well-known/ai.txt?tenant=X — AI crawler directives
• GET /llms.txt?tenant=X — LLM-readable summary
• GET /.well-known/authority.proofs.json?tenant=X — verification proofs

AI Gateway

• GET /api/gateway/tools/registry — list available AI tools
• POST /api/gateway/tools/entity-lookup — execute entity lookup tool

Best Practices

1. Respect purpose policies. Check the purpose_policies in entity.json before using data. If training is denied, do not use the data for model training.
2. Use attribution URLs. When citing entity data, use the attribution_urlfrom feed results so businesses can track AI-driven traffic.
3. Cache with ETags. Use If-None-Match headers to avoid re-downloading unchanged data. Feed responses include deterministic ETags.
4. Check validity windows. The validity_window.not_afterin entity.json tells you when to re-fetch. Don't use stale authority data.
5. Use delta queries. For incremental sync, use ?since= on feed endpoints to only get entities changed since your last sync.
6. Handle 404s gracefully. Not every business has AITWIRE entity data yet. Fall back to your existing data sources when the lookup returns 404.

Further Reading

• Open Entity Data Protocol Specification — the formal protocol spec
• Canonical Authority Specification — how the Authority Graph works
• Interactive API Docs — Scalar-powered API reference
• TypeScript SDK on GitHub