The .well-known manifest

Content owners, agents, and platforms publish a small JSON file at a well-known URL declaring their identity, the role they play, and where telemetry events should be sent.

What it does

The file at /.well-known/openattribution.json is the OpenAttribution identity manifest. It declares who operates the domain, which roles they play (content_owner, agent, platform), and a telemetry endpoint that sends or receives events for that participant.

Same pattern as /.well-known/security.txt - a static, cacheable file at a predictable path. Trust derives from TLS plus DNS control of the domain. There is no central registry to register with and no consumer-side state to synchronise.

File format

A content-owner manifest at https://yourdomain.com/.well-known/openattribution.json:

{
  "schema_version": "0.1",
  "id": "https://yourdomain.com/.well-known/openattribution.json",
  "roles": ["content_owner"],
  "operator": { "name": "Your Organisation" },
  "telemetry": {
    "endpoint": "https://telemetry.openattribution.org/events"
  },
  "domains": ["yourdomain.com", "*.yourdomain.com"]
}

Flat top level - no wrapper object. The fields:

Setup

1. Write the file

Save the JSON above as openattribution.json with your organisation name and domain. If you want OA's hosted endpoint to receive your events, use https://telemetry.openattribution.org/events. If you self-host the telemetry server, point at your own URL instead.

2. Publish it

Serve the file at the well-known path. How depends on your stack:

3. Check it

Fetch your own manifest and confirm it parses:

curl -s https://yourdomain.com/.well-known/openattribution.json | jq .

Trust derives from TLS plus the well-known location. Once the file is reachable over HTTPS at the canonical path, agents and consumers will resolve it.

Domain claims

The optional domains array tells consumers which hostnames the manifest covers. In v0.1 every entry must be self-validating - either the manifest's own host or a subdomain of it (literal news.example.com or wildcard *.example.com). Control of the apex over TLS implies DNS control of subdomains, so no further validation is needed.

Cross-apex claims - one operator unifying several unrelated apex domains in a single manifest - are deferred to a later version. For now, each apex publishes its own manifest.

Multiple roles on one domain

An organisation that both publishes content and operates an agent publishes two manifests on the same domain - one at the root for the content-owner role, one under a path prefix for the agent. Each lives at its own well-known URL with its own telemetry endpoint.

{
  "schema_version": "0.1",
  "id": "https://publisher.com/.well-known/openattribution.json",
  "roles": ["content_owner"],
  "operator": { "name": "Publisher Co" },
  "telemetry": {
    "endpoint": "https://telemetry.openattribution.org/events"
  },
  "domains": ["publisher.com"]
}

{
  "schema_version": "0.1",
  "id": "https://publisher.com/agents/assistant/.well-known/openattribution.json",
  "roles": ["agent"],
  "operator": { "name": "Publisher Co" },
  "keys": [
    { "id": "key-1", "type": "Ed25519", "publicKey": "z6Mk..." }
  ],
  "telemetry": {
    "endpoint": "https://telemetry.openattribution.org/events",
    "conformance_level": "grounding"
  }
}

The content-owner manifest's domains and telemetry apply to publisher.com's content. The agent manifest's keys and telemetry apply to events emitted by the assistant.

How integrations use it

Edge and origin integrations resolve the manifest to find the telemetry endpoint. When you deploy the Cloudflare Worker, it sends events to whatever endpoint your manifest declares. One file, all integrations point at the same place.

/.well-known/openattribution.json
    │
    ├── telemetry.endpoint: https://telemetry.openattribution.org/events
    │
    ├── CDN Worker resolves manifest, sends events to endpoint
    ├── WordPress plugin resolves manifest, sends events to endpoint
    └── Agent resolves manifest, sends events to endpoint

Self-hosting and escape hatch

Pointing the manifest at telemetry.openattribution.org is the easy path. The reference telemetry server is open source and can run anywhere - if you'd rather receive events on your own infrastructure, point telemetry.endpoint at your URL. Consumers follow whatever endpoint the manifest declares.

Next steps

Once your manifest is published, set up a server-side integration to start reporting content_retrieved events. Section 8 of the Telemetry specification is the normative reference for the manifest schema.