API Reference

Build, manage, and push sitemaps to search engines programmatically. RESTful, JSON-native, and built for scale.

v1.4.0 99.99% Uptime Rate Limited

Authentication

All API requests require authentication via API Key. Include your key in the Authorization header using Bearer scheme.

HTTP

Authorization: Bearer sk_live_7x9f2k4m1p8q3r5t6y0
Content-Type: application/json

Generate and rotate keys in your Dashboard → API Keys. Keys are scoped to projects and support granular permissions.

Sitemap Endpoints

Manage sitemap generation, updates, and downloads.

POST /v1/sitemaps/generate ▼

Triggers a full or incremental sitemap generation for a specified project.

Request Body

Parameter	Type	Description
`project_id`Required	string	Unique project identifier
`type`Optional	string	Format: `xml`, `html`, or `json`. Default: `xml`
`max_urls`Optional	integer	Max URLs per file (50k recommended). Default: `50000`
`async`Optional	boolean	Run generation in background. Default: `false`

Example Request

JSON

{
  "project_id": "proj_8x2m4k9p1q",
  "type": "xml",
  "async": true
}

Response

JSON 200 OK

{
  "id": "smap_9f3k2m1p",
  "status": "completed",
  "url": "https://cdn.sitemap.xml/v1/smap_9f3k2m1p.xml",
  "urls_indexed": 12450,
  "size_bytes": 892304,
  "created_at": "2025-01-15T08:32:11Z"
}

GET /v1/sitemaps/:id ▼

Retrieve metadata and download links for a specific sitemap.

Parameter	Type	Description
`:id`Required	string	Sitemap identifier
`include`Optional	string	Comma-separated: `urls`, `stats`

Indexing Endpoints

Push URLs directly to search engine crawlers with priority routing.

POST /v1/indexing/push ▼

Submits URLs for immediate crawling via Google Indexing API and Bing Webmaster Tools.

Request Body

Parameter	Type	Description
`urls`Required	string[]	Array of absolute URLs (max 100 per call)
`priority`Optional	string	`standard`, `high`, or `urgent`. Default: `standard`
`notify`Optional	boolean	Send webhook on completion. Default: `false`

Response

JSON 202 Accepted

{
  "batch_id": "batch_3x7k9m2p",
  "submitted": 45,
  "estimated_crawl_time": "15-45 minutes",
  "status": "processing"
}

Analytics Endpoints

Monitor crawl health, indexing status, and performance metrics.

GET /v1/analytics/crawls ▼

Returns crawl activity and search engine indexing status over time.

Parameter	Type	Description
`start_date`Required	string	ISO 8601 date format
`end_date`Required	string	ISO 8601 date format
`engine`Optional	string	`google`, `bing`, `all`. Default: `all`

Error Codes

The API uses standard HTTP status codes and returns detailed error objects.

200OK — Request succeeded

202Accepted — Async task queued

400Bad Request — Invalid parameters

401Unauthorized — Missing/invalid API key

429Too Many Requests — Rate limit exceeded

500Internal Server Error — Contact support

JSON 401

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key. Ensure sk_live_... matches your active key.",
    "docs_url": "https://docs.sitemap.xml/errors/401"
  }
}

Rate Limits

API requests are limited per project to ensure fair usage and system stability.

Plan	Requests / min	Concurrent Jobs	Burst Allowance
Starter	60	2	10
Professional	600	20	100
Enterprise	6000+	Unlimited	Custom

Rate limit headers are included in every response:
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

SDKs & Libraries

Official client libraries for rapid integration.

🟨 Node.js / TypeScript

Type-safe, promise-based client with full coverage

npm i @sitemap/xml-sdk

🐍 Python

Asyncio support, request retries, and webhooks

pip install sitemap-xml

🦀 Rust

Zero-cost abstractions, tokio runtime ready

cargo add sitemap-xml

🐘 PHP

Laravel/WordPress compatible, PSR-18

composer require sitemap/xml