The IndexNow API: what a request looks like

One address: a GET request

A single changed address goes in the query string of an ordinary GET request:

https://api.indexnow.org/indexnow?url=https://www.example.com/page&key=your-key

Two parameters, both required. url is the address that changed; the protocol asks for it to be URL-escaped and encoded, following the RFC 3986 rules for addresses. key is the site's key, the same string that is published in the key file on the hostname.

This form is convenient for a single correction, a test, or a request typed into a terminal. It is not a way to send many addresses: one request carries one address.

A list of addresses: a POST request with JSON

A list goes in the body of a POST request, as JSON:

POST /indexnow HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: api.indexnow.org

{
  "host": "www.example.com",
  "key": "your-key",
  "urlList": [
    "https://www.example.com/url1",
    "https://www.example.com/folder/url2"
  ]
}

The fields are few. host is the hostname the addresses belong to. key is the site's key. urlList is the list of addresses. keyLocation is optional and is covered below.

One request can carry up to 10,000 addresses, and the protocol allows http and https addresses to be mixed in the same list. Every address in the list has to belong to the host the request names: an address on another host is the reason for one of the refusals described under response codes.

The key and where it is found

The key is how an engine attributes a request to whoever controls the hostname. By default the engine looks for it at /<key>.txt in the root of that hostname and checks that the file contains the key.

The keyLocation field, or parameter in a GET request, names a different place for the file on the same host. The protocol strongly recommends the root, and with reason: the location of the key file determines which addresses the key can be used for. A file placed in a folder covers only the addresses under that folder. Bing's guide for the protocol describes keyLocation as something to always specify; the protocol's own documentation needs it only when the file is not in the root.

The rules for the key itself, and the ways a key file quietly stops working, are set out under the key file.

Which endpoint to send it to

A request can go to the shared endpoint, api.indexnow.org, or to the endpoint of any participating engine. Either way it is shared: the protocol states that submitted addresses are automatically passed to all the other participating engines, so the same list does not need to be sent once per engine. What the shared endpoint is, and why sending to it reaches no engine outside the protocol, is set out under the IndexNow aggregator.

What the answer tells you

The answer to a request is a status code, nothing more. A 200 means the engine received the address; the protocol is explicit that it means only that. A 202 means it was received and the key is still being checked. A 400, 403, 422 or 429 is a refusal, each with its own cause on the sender's side or in volume. What each code means and what to do about it is set out under IndexNow response codes.

No answer ever reports what the engine did afterwards. Whether it fetched the address, kept the page or shows it for a query is not something the protocol carries back. The protocol's own documentation adds that submitting an address does not guarantee immediate indexing.

What to send, and how often

The protocol is meant for addresses that were added, updated or deleted recently. Deleted pages belong in it too: the protocol's guidance is to submit addresses that now redirect and pages that answer with a 404 or a 410, so engines learn that something is gone rather than waiting to find out.

For frequently updated pages, the guidance is to wait at least five minutes between submissions of the same address. Sending an unchanged address again claims a change that did not happen, and every submitted address counts towards the site's crawl quota with the engine, so a repeated claim spends attention on nothing.

The protocol does not publish exact rate limits. Each engine sets its own daily thresholds per site, and a 429 is the sign that one has been reached. A complete inventory of a site is a sitemap's job, not a submission's; how the two divide the work is set out under IndexNow vs sitemaps.

Sending it yourself or having it sent

Everything above can be done by hand, from a terminal or a script, and that route is set out under submitting by hand. The request is the same whichever route sends it; what differs is who notices the change and remembers to send it. A content system plugin sends it on a publishing event, as set out under IndexNow from a content system, and a deploy step sends it on each release, as set out under sending from your publish process. On Bridge CDN the edge sends it after detecting a change, and serves the key file itself, as set out under IndexNow at the edge. Automatic submission covers discovered and changed URLs only, enabling it imports no history, and full-site submission is manual.

FAQ