API Endpoints

Complete reference for the Sitemap.xml REST API. All requests must be made over HTTPS.

Base URL

https://api.sitemap.xml/v1

All API paths are relative to the base URL above. The current version is v1. Deprecated versions will remain accessible for 12 months after sunset.

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer sm_live_sk_4f8a2c9d...e1b0

Security Note: Never expose your secret key in client-side code or public repositories. Use environment variables or a secure secrets manager.

Rate Limits

Rate limits are applied per API key and vary by plan. Headers included in every response:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests left in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Exceeding limits returns 429 Too Many Requests with a Retry-After header.

GET /sitemaps

Retrieve a paginated list of all sitemaps associated with your account.

Query Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Number of results (1-100). Default: 20
`cursor`	string	Optional	Pagination cursor from previous response

Response (200 OK)

{
  "data": [
    {
      "id": "sm_7x9k2p",
      "domain": "docs.sitemap.xml",
      "url": "https://cdn.sitemap.xml/sm_7x9k2p.xml",
      "urls_count": 142,
      "last_generated": "2025-01-14T09:22:00Z",
      "status": "active"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6InNtXzdyMjEiLCJ0cyI6MTcwMjQ4NTM2MH0=",
    "has_more": true
  }
}

POST /sitemaps/generate

Initiate a new sitemap generation job for a specified domain. The process runs asynchronously.

Request Body

Name	Type	Required	Description
`domain`	string	Required	Fully qualified domain to crawl
`max_depth`	integer	Optional	Crawl depth limit (1-10). Default: 5
`exclude_paths`	string[]	Optional	Regex patterns to ignore during crawling

Response (202 Accepted)

{
  "id": "job_8m3n5q",
  "status": "queued",
  "domain": "docs.sitemap.xml",
  "estimated_completion": "2025-01-14T09:27:00Z",
  "webhook_url": null
}

DELETE /sitemaps/{id}

Permanently delete a sitemap and all associated crawl data. This action is irreversible.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	Sitemap identifier (prefixed with `sm_`)

Response (204 No Content)

Empty body. Returns immediately upon successful deletion.

POST /indexing/push

Submit URLs directly to search engine indexing APIs. Returns a batch ID for tracking.

Request Body

Name	Type	Required	Description
`urls`	string[]	Required	Array of absolute URLs (max 500 per request)
`search_engines`	string[]	Optional	Target engines: `["google", "bing", "yandex"]`

Response (200 OK)

{
  "batch_id": "idx_92k4m1",
  "submitted": 124,
  "rejected": 3,
  "errors": [
    { "url": "https://example.com/broken", "reason": "404_NOT_FOUND" }
  ]
}

GET /indexing/status/{batch_id}

Poll the indexing status of a previously submitted URL batch.

Response (200 OK)

{
  "batch_id": "idx_92k4m1",
  "status": "completed",
  "total": 127,
  "indexed": 118,
  "failed": 9,
  "last_updated": "2025-01-14T09:35:12Z"
}

GET /analytics/coverage

Retrieve crawl coverage statistics and indexing health metrics.

Query Parameters

Name	Type	Required	Description
`domain`	string	Required	Target domain
`period`	string	Optional	`7d`, `30d`, `90d`

Response (200 OK)

{
  "domain": "docs.sitemap.xml",
  "discovered": 342,
  "submitted": 340,
  "indexed": 315,
  "errors": {
    "404": 12,
    "5xx": 3,
    "redirect_loops": 2
  }
}

GET /analytics/performance

Get search performance data aggregated from Search Console APIs.

Response (200 OK)

{
  "clicks": 14820,
  "impressions": 89400,
  "ctr": 0.165,
  "avg_position": 4.2,
  "queries": [
    { "query": "sitemap generator", "clicks": 4200, "impressions": 28100, "position": 3.1 }
  ]
}

Error Codes

The API uses standard HTTP status codes. Error responses include a structured JSON body:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid domain format",
    "details": { "field": "domain", "value": "example.com" }
  }
}

Code	Status	Description
`VALIDATION_ERROR`	400	Malformed request or missing required parameters
`UNAUTHORIZED`	401	Invalid or expired API key
`FORBIDDEN`	403	Insufficient permissions for requested action
`NOT_FOUND`	404	Requested resource does not exist
`RATE_LIMITED`	429	Too many requests. Check `Retry-After` header
`INTERNAL_ERROR`	500	Unexpected server failure. Contact support if persistent

Pagination

Collection endpoints use cursor-based pagination. Requests accept limit and cursor parameters. Responses include a pagination object with next_cursor and has_more fields.

Tip: When has_more is false, you've reached the end of the collection. Cursors expire after 1 hour.