Open in ChatGPT Claude Perplexity

The .well-known file

Content owners register their domain with OpenAttribution by placing a small JSON file at a well-known URL. This is the first step before any telemetry integration.

What it does

The file at /.well-known/openattribution declares two things: which telemetry endpoint receives events for this domain, and a verification token that proves the domain owner placed it there.

It follows the same pattern as /.well-known/security.txt or Google Search Console's domain verification. Static file, cacheable, changes only if you switch telemetry endpoint.

File format

Place this file at https://yourdomain.com/.well-known/openattribution:

.well-known/openattribution

{
  "openattribution": {
    "version": "0.1",
    "telemetry_endpoint": "https://api.openattribution.org/api/v1/telemetry",
    "verification": "oa-verify=<your-token>"
  }
}

Field	Value	Required
`version`	Schema version. Currently `"0.1"`	Yes
`telemetry_endpoint`	The OA telemetry server URL that receives events for this domain	Yes
`verification`	Token issued when you register your domain with OA. Format: `oa-verify=<uuid>`	Yes

Setup

1. Register your domain

Sign up at openattribution.org/onboarding and add your domain. OA issues a verification token - a UUID that proves you control the domain.

2. Publish the file

Create the JSON file with your verification token and serve it at the well-known path. How you do this depends on your stack:

Platform	Where to place the file
Static site / CDN	`public/.well-known/openattribution` or equivalent static directory
WordPress	The OA plugin handles this automatically
Vercel	`public/.well-known/openattribution`
Netlify	`static/.well-known/openattribution` (or `public/`)
Custom server	Serve the JSON from a route handler or static file at `/.well-known/openattribution`

Content-Type

Serve the file with Content-Type: application/json. Since the file has no extension, you may need to set this explicitly in your server or CDN config.

3. Verify

Once published, OA fetches the file and confirms the verification token matches. Your domain appears as verified in your dashboard. From there, any telemetry events referencing URLs on your domain are attributed to your account.

You can also check any domain's file directly:

bash

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

How integrations use it

CDN integrations and the WordPress plugin read the file to find the telemetry endpoint. When you set up a Cloudflare Worker or Fastly log stream, they send events to the endpoint declared in your well-known file. One file, all integrations point to the same place.

flow

.well-known/openattribution
    │
    ├── telemetry_endpoint: https://api.openattribution.org/...
    │
    ├── CDN Worker reads endpoint, sends events there
    ├── WordPress plugin reads endpoint, sends events there
    └── Agent reads endpoint, sends events there (future)

For networks and partners

If you operate an affiliate network or content marketplace, you can drive adoption of the well-known file across your publisher and brand base. The registration is API-driven - if you've already verified domain ownership through your own onboarding, that verification can close the loop without content owners needing a separate signup.

One endpoint per domain

The well-known file points to one telemetry endpoint. Content owners on multiple networks don't need multiple files - OA is the central aggregation point. Networks access data via delegated read access, not separate endpoints.

Next steps

Once your domain is registered and verified, set up a server-side integration to start reporting content_retrieved events.