Generate Sitemap

Creates a new XML sitemap for the specified domain. The endpoint automatically crawls, validates, and structures your URLs according to W3C sitemap protocols.

POST /v1/sitemaps/generate

Note: Generated sitemaps are cached for 24 hours unless force_refresh: true is passed. Automatic submissions to Google & Bing are triggered upon successful generation.

Request Body

Parameter	Type	Description
domain required	string	The root domain to generate the sitemap for. Must not include protocol or trailing slash.
format	enum	Output format. Options: `xml` (default), `html`, `json`.
max_urls	integer	Maximum number of URLs to include. Defaults to 50,000. Exceeds require index sitemaps.
include_assets	boolean	Whether to include image, video, and news extensions. Defaults to `true`.
force_refresh	boolean	Bypass cache and perform a fresh crawl. Useful for staging environments.

Example Request

const response = await fetch('https://api.sitemap.xml/v1/sitemaps/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_KEY}`
  },
  body: JSON.stringify({
    domain: 'example.com',
    format: 'xml',
    max_urls: 10000,
    include_assets: true,
    force_refresh: false
  })
});
            

Response

On success, the API returns a 201 Created status with the sitemap metadata and direct download URL.

{
  id: "sm_8x92kq4m1p7n",
  status: "completed",
  domain: "example.com",
  url_count: 482,
  size_kb: 18.7,
  generated_at: "2025-01-15T14:32:08Z",
  expires_at: "2025-01-16T14:32:08Z",
  download_url: "https://cdn.sitemap.xml/v1/sm_8x92kq4m1p7n.xml",
  search_console: {
    google_submitted: true,
    bing_submitted: true,
    yandex_submitted: false
  }
}
            

Response Fields

Field	Type	Description
id	string	Unique identifier for the generated sitemap.
status	enum	Processing state: `pending`, `completed`, `failed`.
download_url	string	Temporary signed URL for downloading the raw sitemap file.
search_console	object	Submission status to major search engine webmaster tools.

Error Handling

The API uses standard HTTP status codes and returns structured error objects for debugging.

{
  error: {
    code: "INVALID_DOMAIN",
    message: "Domain must not contain protocol or path segments",
    details: "Received: 'https://example.com/blog/'",
    request_id: "req_7h3k9m2x"
  }
}
            

Tip: Always log the request_id when reporting issues. Our support team can trace it across our distributed crawl infrastructure.

Last updated: January 15, 2025 • API Version: 1.2.4 • Report documentation issue