IndexNow

IndexNow is an open protocol for notifying search engines that a URL changed. One submission from RankParse goes to api.indexnow.org, which shares it with every participating engine (Bing, Yandex, Seznam, Naver and others). RankParse submits to IndexNow only; it does not submit to any other search engine.

Two routes make up the flow: a free one that gives you a key for a host, and a 1 credit one that submits URLs.

How it works

POST /v1/indexnow/key

Returns the IndexNow key for a host, creating it on first use. The key is unique to your workspace and host, and it is never rotated, so a key file you have already published stays valid.

Parameters

example.com and www.example.com are different hosts and get different keys. Provision the key for the exact host that appears in the URLs you will submit.

Example

curl -X POST "https://api.rankparse.com/v1/indexnow/key?domain=example.com" \
  -H "X-API-Key: rp_your_key"

import requests

res = requests.post(
    "https://api.rankparse.com/v1/indexnow/key",
    headers={"X-API-Key": "rp_your_key"},
    params={"domain": "example.com"},
)
info = res.json()
print(res.status_code, info["key_location"])

const res = await fetch("https://api.rankparse.com/v1/indexnow/key?domain=example.com", {
  method: "POST",
  headers: { "X-API-Key": "rp_your_key" },
});
const info = await res.json();
console.log(res.status, info.key_location);

Response

201 Created the first time, 200 OK on every later call for the same host. The body is a plain object, not wrapped in the usual data envelope.

{
  "host": "example.com",
  "key": "3f9a1c7e2b8d4e6f9a0b1c2d3e4f5a6b",
  "key_location": "https://example.com/3f9a1c7e2b8d4e6f9a0b1c2d3e4f5a6b.txt",
  "verified": false,
  "instructions": "Host a UTF-8 text file containing exactly the key at https://example.com/3f9a1c7e2b8d4e6f9a0b1c2d3e4f5a6b.txt, then submit URLs with POST /v1/indexnow."
}

Response fields

The key file contents are the key and nothing else. Leading and trailing whitespace, such as a final newline, is ignored when RankParse checks it.

POST /v1/indexnow

Submits a batch of URLs from one host to IndexNow.

Body parameters

Send JSON with Content-Type: application/json.

Rules for urls:

• Every URL must be a valid public http(s) URL. Private or reserved addresses, URLs with credentials (user:pass@), URLs with a #fragment, and URLs with leading or trailing whitespace are rejected.
• Every URL must use the default port. https://example.com:8443/a is rejected because IndexNow keys are verified at the default port.
• Every URL must have exactly the same hostname. https://example.com/a and https://www.example.com/b in one call fail with indexnow_host_mismatch. Make one call per host.
• URLs are normalized (for example the host is lowercased) before they are sent.
• Submit URLs that are new, changed or deleted. IndexNow is a change signal, not a way to re-submit unchanged pages.

Example

curl -X POST "https://api.rankparse.com/v1/indexnow" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/blog/new-post",
      "https://example.com/pricing"
    ]
  }'

import requests

res = requests.post(
    "https://api.rankparse.com/v1/indexnow",
    headers={"X-API-Key": "rp_your_key"},
    json={
        "urls": [
            "https://example.com/blog/new-post",
            "https://example.com/pricing",
        ]
    },
)
print(res.status_code, res.json())

const res = await fetch("https://api.rankparse.com/v1/indexnow", {
  method: "POST",
  headers: {
    "X-API-Key": "rp_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: [
      "https://example.com/blog/new-post",
      "https://example.com/pricing",
    ],
  }),
});
console.log(res.status, await res.json());

Response

{
  "data": {
    "host": "example.com",
    "url_count": 2,
    "key_location": "https://example.com/3f9a1c7e2b8d4e6f9a0b1c2d3e4f5a6b.txt",
    "status": "accepted"
  },
  "credits_used": 1,
  "credits_remaining": 998
}

Response fields

Behavior and limits

• Cost: 1 credit per call, whatever the number of URLs (up to 1000). Any failed call is refunded automatically, including validation errors and upstream failures. See Credits.
• Order of checks: body and URL validation, then website ownership, then key lookup, then key file verification, then the upstream submission.
• Key file verification: RankParse requests https://<host>/<key>.txt with a 30 second timeout and requires an HTTP 200 whose body (trimmed) equals the key. The file must be small; anything over 4 KB is treated as not a key file. A successful check is cached for 24 hours, so steady-state submissions skip it. If IndexNow later rejects the key (indexnow_key_rejected), the cache is cleared and the next submission checks the file again.
• Subdomains: a host that is a subdomain of one of your websites is accepted (blog.example.com for a website example.com). Generate the key for the subdomain host itself.
• Rate limit: the shared 60 requests per minute per key. IndexNow applies its own limits upstream and can answer with indexnow_rate_limited; submit changes in batches instead of one URL per call.

Approval inbox for agents

If your workspace uses the approval inbox, a call made by an AI agent does not submit immediately. A call is agent-origin when it uses an API key and carries the header X-RankParse-Client: mcp, which is what the RankParse API-key MCP server sends for submit_indexnow_urls. Calls from your own code without that header, and RapidAPI calls, are never held for approval.

For an agent-origin call in such a workspace:

{
  "data": {
    "host": "example.com",
    "url_count": 2,
    "status": "awaiting_approval",
    "proposal_id": "prop_abc123",
    "review_url": "https://rankparse.com/dashboard/sites/site_abc123/today?proposal=prop_abc123"
  },
  "credits_used": 0,
  "credits_remaining": 998,
  "message": "Waiting for the user's approval in RankParse: ..."
}

Show the review_url to the person who must approve. Track the outcome with proposals. Agents that should always go through the inbox can call propose_indexnow_submit (below) instead.

Errors

All errors use the standard shape { "error", "code", "message" }. See Error codes. Failed submissions are refunded.

MCP tools

provision_indexnow_key and submit_indexnow_urls are not available on the secure OAuth connector, which can only propose. See MCP Server.

Related