indexnow-key 1.0.0

IndexNow Key Check v1.0.0

Validates a discoverable IndexNow ownership key file when the site advertises its location.

IndexNow is a URL-change notification protocol. It lets a site notify participating search engines that URLs were created, updated, or deleted. The key file proves that the submitter controls the host or host path being submitted.

Input Contract

[email protected]

Requires the scan origin, homepage HTML, homepage headers, and parsed homepage document. The check may independently fetch /robots.txt to look for scanner-supported key-location hints.

Output Contract

[email protected]

Emits a stepped report check result with key-location discovery and key-file validation evidence.

Official Protocol Model

IndexNow has two moving parts:

The key file is a UTF-8 text file. Its filename is {key}.txt, and its body contains the same key value.

Key Format

Examples:

52e163cb29f13843a5b58d2854fe46c9
CanAgentUse-IndexNow-2026

Key Location

The simplest official placement is:

https://example.com/{key}.txt

A key file can also be placed elsewhere on the host, but the submitted IndexNow request must include keyLocation when the key file is not at the root.

Scope matters:

This check validates same-origin advertised key files. It does not submit URLs to IndexNow endpoints.

URL Submission API

Official submission supports both single URL and batch URL submission.

Single URL style:

https://api.indexnow.org/indexnow?url=https://example.com/page&key=KEY

Batch style uses a JSON POST body with host, key, optional keyLocation, and urlList.

Protocol limits and behavior:

Submission Response Codes

This check does not call submission endpoints, so these codes are documented for implementation guidance but are not emitted by v1.0.0.

Discovery Surfaces

The official protocol does not define a universal public discovery document for IndexNow key locations. A scanner cannot guess a private key value. Therefore this check only verifies IndexNow key files when the site advertises a key location through supported hints.

Supported v1.0.0 discovery hints:

These hints are not part of the official IndexNow protocol. They make the key file discoverable to CanAgentUse and similar scanners without submitting a URL to an IndexNow endpoint.

Pass Criteria

• A supported discovery hint advertises a same-origin key file URL.
• The key file responds with a successful HTTP status.
• The key file is served as text-compatible content, such as text/plain.
• The key file path ends in {key}.txt.
• The decoded key-file body matches {key} after removing a UTF-8 BOM and surrounding whitespace/newline.
• The key is 8 to 128 characters and contains only letters, digits, and hyphen.

Informational Criteria

• No supported key-location hint is advertised.

IndexNow is optional. Absence of a discoverable key is informational unless the site explicitly advertises a key location that cannot be validated.

Failure Criteria

• The site advertises an IndexNow key location, but the key file cannot be

fetched.

• The advertised key file is cross-origin.
• The key file body does not match the filename key.
• The key value contains unsupported characters or has an invalid length.
• The key file is advertised but served as a non-text response such as JSON or HTML.

Failures are low severity because IndexNow is a low-impact discovery signal in this assessment suite.

Scoring Steps

Current v1.0.0 Coverage

This version checks:

• robots.txt IndexNow-Key hints.
• HTML link rel="indexnow-key" hints.
• HTTP Link header rel="indexnow-key" hints.
• HTML meta name="indexnow-key-location" hints.
• Same-origin key-file URLs.
• Text-compatible key-file responses.
• Key filename and body match.
• Official key character and length constraints.

External Submission Signals Not Emitted By This Check

This package validates the public ownership key discovery and key file. It does not emit live IndexNow submission behavior because the scan input does not include submission logs, outgoing API requests, or search-engine endpoint responses.

Submission telemetry belongs in a separate check or integration that can observe actual IndexNow API calls. That integration can validate:

• Whether the site submits changed URLs to IndexNow.
• Whether keyLocation is used correctly in live API submissions.
• Whether submission endpoints return 200, 202, 400, 403, 422, or

429.

• Whether batch submissions stay within the 10,000 URL limit.
• Whether submitted URLs are fresh changes rather than full-site recrawl spam.

References

• www.indexnow.org/documentation
• yandex.com/support/webmaster/en/indexnow/key
• example.com/%7Bkey%7D.txt
• example.com/
• example.com/blog/%7Bkey%7D.txt
• example.com/blog
• api.indexnow.org/indexnow
• example.com/key.txt

indexnow-key v1.0.0 Changelog

Initial versioned package for indexnow-key.

• Documents official IndexNow key format, key file placement, submission API, response codes, and URL batch limits.
• Documents scanner-supported nonstandard key-location hints separately from the official protocol.
• Declares package scoring steps for key-location discovery and key-file validation.
• Validates that advertised key files use a text-compatible content type when one is supplied.
• Documents the implemented BOM/whitespace tolerance used when reading key-file bodies.