API Reference

Welcome to the Sitemap.xml API. This guide provides detailed information about our RESTful endpoints, authentication methods, request formats, and response schemas.

Base URL: https://api.sitemap.xml/v1

All requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authentication

The Sitemap.xml API uses Bearer token authentication. You can generate API keys from your Dashboard → API Keys settings.

Include your secret key in the Authorization header:

Authorization: Bearer sk_live_your_api_key_here

⚠️ Security Notice: Keep your API keys secret. Never expose them in client-side code, public repositories, or browser-accessible locations.

Rate Limits

API requests are rate-limited based on your plan tier. Limits are applied per API key.

Plan	Requests/minute	Requests/day
Starter	60	1,000
Professional	300	25,000
Enterprise	1,000	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: UTC timestamp when the limit resets

List Sitemaps

GET /sitemaps

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

Query Parameters

Parameter	Type	Description
limitinteger	Optional	Number of results (1-100). Default: 20
cursorstring	Optional	Pagination cursor from previous response
statusstring	Optional	Filter by: `active`, `archived`

Example Response 200 OK

{
  "sitemaps": [
    {
      "id": "smt_8f3k29x0",
      "name": "Production Site",
      "url": "https://example.com",
      "status": "active",
      "urls_count": 1245,
      "last_updated": "2025-01-15T14:32:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTI0NX0",
    "has_more": true
  }
}

Create Sitemap

POST /sitemaps

Creates a new sitemap configuration. The system will automatically begin crawling your domain.

Request Body

Parameter	Type	Required	Description
namestring	String	Required	Human-readable name
domainstring	String	Required	Root domain to crawl
robot_txt_checkboolean	Boolean	Optional	Respect robots.txt rules (default: true)

Success Response 201 Created

{
  "id": "smt_9a7b2c1d",
  "name": "Marketing Blog",
  "domain": "blog.example.com",
  "status": "crawling",
  "created_at": "2025-01-15T10:00:00Z",
  "xml_url": "https://cdn.sitemap.xml/smt_9a7b2c1d.xml"
}

Add URL to Sitemap

POST /sitemaps/:id/urls

Adds a specific URL to an existing sitemap. Automatically calculates priority and schedules indexing.

Path Parameters

Parameter	Type	Description
idstring	String	Sitemap identifier (e.g., `smt_8f3k29x0`)

Request Body

Parameter	Type	Description
urlstring	String	Full absolute URL
priorityfloat	Float	0.0 to 1.0 (default: 0.5)
changenfreqstring	String	Always, daily, weekly, monthly, yearly, never

Success Response 200 OK

{
  "url_id": "url_4x8m2p",
  "status": "queued",
  "message": "URL added and scheduled for indexing"
}

Submit for Indexing

POST /sitemaps/:id/submit

Immediately pushes your sitemap to Google, Bing, Yandex, and other supported search engines.

Success Response 202 Accepted

{
  "request_id": "req_7f3a9c2b",
  "targets": [
    { "engine": "google", "status": "submitted" },
    { "engine": "bing", "status": "submitted" }
  ],
  "estimated_crawl_time": "5-15 minutes"
}

Error Handling

The Sitemap.xml API uses conventional HTTP response codes to indicate success or failure:

2xx: Success
4xx: Client Error (bad request, unauthorized, etc.)
5xx: Server Error (our fault, try again later)

Code	Meaning	Common Causes
400	Bad Request	Invalid JSON, missing required parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for this resource
404	Not Found	Invalid endpoint or missing sitemap ID
429	Too Many Requests	Rate limit exceeded. Retry after `X-RateLimit-Reset`
500	Internal Error	Unexpected server failure

All error responses include a structured JSON body:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "type": "authentication_error",
    "request_id": "req_8f3a2c9x"
  }
}