The IndexNow API request reference is a technical protocol that allows website owners to notify search engines like Yandex instantly about new, updated, or deleted content. By sending a simple HTTP request containing the page URL and a unique key, you ensure that search crawlers prioritize your most recent changes without waiting for a standard crawl cycle. This method reduces server load and speeds up the discovery of fresh information across the web.
What is the IndexNow API and why does it matter?
Traditional crawling relies on search engines discovering links or checking sitemaps at their own pace. This often leads to a gap between publishing and indexing. IndexNow changes this by giving the control back to the website owner. You tell the search engine that a page is ready, and it responds by scheduling a visit.
The protocol is especially useful for sites that publish many pages every day. For example, a news portal or a large retail site needs its newest data to show up in search results as soon as possible. Without this API, a new article might wait hours or days to be discovered by a standard crawler.
How to structure a valid IndexNow API request?
A standard request requires three main elements: the host, the URL list, and the key. The host is the domain name where the changes occurred. The URL list can contain up to 10,000 links per request, though single updates are common. The key is a string that proves you own the domain. Note that the key must be hosted on your server to be verified.
- The API endpoint, such as yandex.com/indexnow.
- The content-type header must be set to application/json.
- A JSON body containing the host, key, and a list of URLs.
- The keyLocation, which specifies the path to your verification file.
The request can be sent as a POST or a GET. The POST method is preferred for batching multiple URLs. When using POST, the body of the request contains the data in a structured format. The GET method is simpler but only supports one URL at a time. Most developers choose POST for its efficiency.
We find that many developers forget to match the key exactly between the API body and the text file. A single character difference or an extra space will cause the verification to fail immediately.
Alien Road SEO team
What are the key components for validation?
Security is handled through a text file placed in the root directory. This file contains the same key string used in the API call. Search engines verify the request by fetching this file from your server. If the key in the request matches the key in the file on your server, the request is authenticated.
The key itself should be at least 8 characters long, but using a 32-character alphanumeric string is a more reliable standard. You should name the text file after the key. For instance, if your key is ‘abc123’, your file should be ‘abc123.txt’. This allows the search engine to find it without guesswork.
How to handle common API response errors?
Like RSS feed errors mentioned in technical documentation, IndexNow requests fail if the syntax is wrong. A 400 Bad Request usually means the JSON format is invalid or a mandatory field is missing. A 403 Forbidden suggests the key is incorrect or the key file cannot be reached by the crawler. Observe that technical hygiene is vital for success.
- 400: Invalid syntax. Check for missing quotes or commas in your JSON.
- 403: Key verification failed. Verify that the file is in the root directory.
- 422: The URL does not belong to the host specified in the request.
- 429: Too many requests. Reduce the frequency of your API calls.
If you see a 403 error, check if your server is blocking the search engine’s user agent. Sometimes firewalls prevent the crawler from fetching the key file. You must allow access to the specific verification URL to maintain a smooth connection between your site and the search engine.
How Alien Road applies indexnow api request reference
At Alien Road, we integrate the IndexNow API into the CMS workflow for our clients. For a typical e-commerce site with thousands of products, manual indexing is impossible. We set up an automated trigger that fires every time a product price changes or a new item is added. This ensures that the search engine has the most current data without delay.
In a typical engagement, we first generate a unique key and place it at the root of the client server. We then configure their backend to batch URLs and send them to the Yandex endpoint every hour. This prevents the server from being overwhelmed while ensuring that price drops or stock updates appear in search results within minutes. For a Shopify store selling home goods, this process keeps their inventory data accurate for potential customers.
Using IndexNow for large-scale migrations is a strong strategy. Instead of waiting weeks for a site move to be recognized, we push the new URLs directly, which helps maintain traffic stability during the transition.
Alien Road SEO team
Technical specifications and limits
While the API is powerful, it has boundaries that you must respect. You cannot submit more than 10,000 URLs in a single POST request. Additionally, the URLs must all belong to the same host. If you manage multiple subdomains, each requires its own key and its own API call to be processed correctly.
The formatting of the JSON payload is strict. Much like the requirements for news feeds, URLs in IndexNow must be absolute and fully qualified. They must use the correct protocol, either HTTP or HTTPS. Special characters must be properly escaped using UTF-8 encoding. An extra quotation mark or an improperly closed attribute will stop the entire batch from being indexed.
Comparing IndexNow with XML Sitemaps
XML sitemaps are passive files that search engines check occasionally. IndexNow is an active notification system. While you should still maintain a sitemap for complete site structure visibility, the API is the better choice for time-sensitive updates. Using both methods together provides a complete indexing strategy.
Sitemaps can sometimes grow very large, causing slow processing times. IndexNow avoids this by focusing only on what changed recently. This targeted approach is more efficient for both your server and the search engine’s resources. It reduces the need for the crawler to visit unchanged pages repeatedly.
Where to start this week
Begin by checking if your CMS has a native IndexNow plugin. If it does not, generate a 32-character key and upload it to your server root as a .txt file. Test a single URL using a simple command line tool to verify that you receive a 200 OK response. Once you have verified the connection, automate the process for all new content updates to keep your search presence fresh.
Monitor your server logs for the search engine’s visit after you send a request. This confirms that the system is working. If you notice errors, refer back to the error code list and check your JSON syntax for common mistakes like unescaped characters or missing braces.