POST v1/site/map

This endpoint creates a new site mapping request and returns the result.

Create a new sitemap request

post

This endpoint processes a website's sitemap and returns all URLs found within it.

Authorizations

X-API-KeystringRequired

Body

urlstringOptional

The url you want our sitemap reader to process on your behalf

asyncbooleanOptional

Whether the request should be processed asynchronously. When true the request returns immediately with state 'pending'; poll GET /v1/site/map/{id} to retrieve the result once it completes.

Default: false

includestring[] · nullableOptional

Regex patterns to include only matching URLs. If specified, only URLs matching at least one pattern will be returned.

excludestring[] · nullableOptional

Regex patterns to exclude matching URLs. URLs matching any pattern will be removed from results.

search_querystring · nullableOptional

Optional search query to rank URLs by semantic similarity using AI embeddings. Providing a search query turns ranking on. For very large sitemaps only the first links (ordered alphabetically) up to your account's searchable-links limit (default 50,000) are ranked.

limitinteger · int32 · nullableOptional

Maximum number of links to return. Defaults to your account's maximum. When a search_query is provided, ranked results are capped at 50 and requesting more is an error.

embedding_modelstring · nullableOptional

Embedding model to use for ranking. Default is 'text-embedding-3-small'.

max_cache_ageinteger · int32 · nullableOptional

Maximum age in seconds for a cached sitemap to be considered fresh. Defaults to 6 hours and is capped by the server-side cache retention window (6 hours by default), so larger values are clamped. Use 0 to always rebuild.

resolvedMaxCacheAgeinteger · int32Optional

Responses

200

The sitemap request response detailing the URLs found

application/json

408

The sitemap request timed out

application/json

503

The requested site is unavailable

application/json

post/v1/site/map

POST /v1/site/map HTTP/1.1
Host: api.gaffa.dev
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 200

"{\"url\":\"https://example.com\",\"async\":false,\"include\":null,\"exclude\":null,\"search_query\":null,\"limit\":null,\"embedding_model\":null,\"max_cache_age\":null,\"resolvedMaxCacheAge\":21600}"

{"data":{"id":"smr_1234567890abcdef","url":"https://example.com","state":"completed","credit_usage":1,"error":null,"error_reason":null,"from_cache":false,"sitemap_built_at":null,"filters_applied":false,"started_at":"2024-01-01T12:00:00+00:00","completed_at":"2024-01-01T12:00:30+00:00","running_time":"00:00:30","links":[{"url":"https://example.com/"},{"url":"https://example.com/about"},{"url":"https://example.com/products"},{"url":"https://example.com/contact"}],"link_count":4,"truncated":false,"total_link_count":0,"partial_failure":false},"error":null}