Why Expose JSON-LD via API
Embedding JSON-LD in HTML pages is the standard approach for structured data, but it has limitations: the data is only accessible to crawlers that fetch the full page, it cannot be queried programmatically, and it is mixed with presentation markup that makes extraction fragile. Exposing JSON-LD through a dedicated API endpoint solves all three problems.
An API endpoint that returns pure JSON-LD can be consumed by AI agents, partner applications, CRM enrichment tools, and verification services without any HTML parsing. It also makes your structured data independently auditable — a third party can verify your Organization schema without loading your website.
The Standard Endpoint Pattern
The conventional pattern is to expose a /api/identity or /.well-known/identity.json endpoint that returns the Organization schema for the root domain. The response should set Content-Type: application/ld+json and include the full schema.org Organization object with all available fields populated.
Required Fields for AI System Compatibility
For AI systems to use your identity data reliably, the JSON-LD response must include: @context (schema.org), @type (Organization), name, url, description, foundingDate, address (PostalAddress), contactPoint, and sameAs (array of authoritative external URLs). The sameAs array is particularly important — it links your API response to Wikidata, Companies House, LinkedIn, and other sources that AI systems use to cross-reference identity claims.
Caching and Versioning
Identity data changes infrequently but must be accurate when it does change. Set a Cache-Control: max-age=86400 header (24 hours) and include a lastModified field in the response body. This allows consumers to cache the response efficiently while knowing when to re-fetch. For versioning, include a schemaVersion field so consumers can detect breaking changes.
Linking to the AI Verified Registry
If your business has an AI Verified passport, include the passport hash and verification URL in your API response under a custom aiVerified property. This links your self-hosted identity endpoint to the independent third-party verification record, giving consumers a way to confirm your identity claims without trusting your API alone.