The request
path and userAgent are the only required fields on a hit; a hit missing either is dropped and counted, and the rest of the batch still lands. A server must never reject a whole batch over one bad item, because clients are heterogeneous enough that one always will be.
The key travels in X-Beacon-Key rather than Authorization: it identifies a site, not a user, and it has to survive proxies that strip auth headers.
Fields a server should know about
Clients send raw facts. They do not label a hit as a crawler, name a provider, or claim a verification state.
The response
accepted + skipped always equals hits.length. unrecognized is normal traffic that is not an AI client, and it is usually the largest number.
Status codes
This is the part that bites. Clients branch on the status, and getting one wrong silences a site.Timestamps
occurredAt lets a client buffer and send later, which every client does.
A server must ignore a timestamp more than 24 hours from its own clock and substitute the receive time. A skewed client clock would otherwise land hits in the wrong day bucket permanently, and there is no way to notice after the fact.
Verification states
A valid signature outranks the address verdict. A signature that fails falls through to the address verdict rather than condemning the hit: the signature base is rebuilt from a forwarded payload, so a gap in your reconstruction must never be recorded as somebody else’s forgery.