API documentation

Quick start

1. 1. Get a key. Request API access in your account; your key is shown once when it is approved.
2. 2. Check it works. Call GET /balance. A 200 with your credits means you are set.
3. 3. Submit URLs. POST /batches with a list of URLs. One credit per URL.

curl https://indexingurl.com/api/v1/balance \
  -H "Authorization: Bearer YOUR_KEY"

{
  "credit_balance": 1500
}

Submit a batch

Send the URLs you want indexed. Credits are reserved when the batch is accepted and the batch is handed over straight away, so the response already tells you how delivery went.

curl -X POST https://indexingurl.com/api/v1/batches \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-10-22-001" \
  -d '{"urls": ["https://example.com/a", "https://example.com/b"]}'

{
  "batch_number": "IDX-20261022-000042",
  "status": "upstream_accepted",
  "entries_count": 2,
  "created_at": "2026-10-22T14:03:11+00:00"
}

Other outcomes you should handle

{
  "batch_number": "IDX-20261022-000043",
  "status": "pending_reconciliation",
  "entries_count": 2,
  "created_at": "2026-10-22T14:05:40+00:00"
}

{
  "error": "delivery_failed",
  "message": "The batch could not be delivered. Your credits were returned; you can submit it again.",
  "batch_number": "IDX-20261022-000044",
  "status": "failed",
  "entries_count": 2,
  "created_at": "2026-10-22T14:07:02+00:00"
}

{
  "error": "invalid_urls",
  "message": "One or more entries are not valid http(s) URLs.",
  "invalid": ["example.com/no-scheme", "ftp://example.com/file"]
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits: available 1, requested 2.",
  "available": 1,
  "requested": 2
}

Retrying safely with Idempotency-Key

If a request times out you cannot know whether it arrived. Send the same Idempotency-Key (up to 150 characters) again: you get the original batch back and nothing is charged twice. The same key with a different URL list is rejected with 409.

# First attempt: times out. Run it again with the same key and the same URLs.
curl -X POST https://indexingurl.com/api/v1/batches \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Idempotency-Key: order-2026-10-22-001" \
  -d '{"urls": ["https://example.com/a", "https://example.com/b"]}'

{
  "batch_number": "IDX-20261022-000042",
  "status": "upstream_accepted",
  "entries_count": 2,
  "created_at": "2026-10-22T14:03:11+00:00"
}

{
  "error": "idempotency_conflict",
  "message": "This idempotency key was already used with a different payload."
}

Check a batch and its results

curl https://indexingurl.com/api/v1/batches/IDX-20261022-000042 \
  -H "Authorization: Bearer YOUR_KEY"

{
  "batch_number": "IDX-20261022-000042",
  "status": "completed",
  "entries_count": 2,
  "created_at": "2026-10-22T14:03:11+00:00"
}

curl https://indexingurl.com/api/v1/batches/IDX-20261022-000042/results \
  -H "Authorization: Bearer YOUR_KEY"

{
  "data": [
    { "url": "https://example.com/a", "status": "indexed", "result_message": null },
    { "url": "https://example.com/b", "status": "pending", "result_message": null }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 2 }
}

curl "https://indexingurl.com/api/v1/batches?page=1" \
  -H "Authorization: Bearer YOUR_KEY"

Poll no more than about once a minute; most batches settle within minutes.

Errors

{
  "success": false,
  "message": "Invalid API key."
}

Errors are JSON with a message, and an error code on batch endpoints (for example insufficient_credits). A 5xx other than 502 is on our side: retry with the same Idempotency-Key.

Compatible with the previous IndexingURL API

Tools written for the old site keep working: POST /submit takes {"urls": [...]}, ignores invalid entries and repeats, and returns how many credits remain. It uses the same key and the same credits as everything above. You only need a new key.

curl -X POST https://indexingurl.com/api/v1/submit \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/page-1", "https://example.com/page-2"]}'

{
  "success": true,
  "message": "URLs submitted successfully",
  "submitted": 2,
  "urlsProcessed": 2,
  "requestId": "IDX-20261022-000045",
  "apiLimit": 1500,
  "apiUsed": 2,
  "remaining": 1498
}

remaining is your credit balance. Not enough credits gives 429 with success: false and the same fields. Delivery follows the same rules as /batches: 202 when not confirmed yet (do not resubmit), 502 when it failed and the credits came back.