---
title: "Find the representative pages of a website from its sitemaps, before generating a persona brief (free tool)"
method: POST
path: "/api/v1/tools/persona-brief/discover"
tags: ["v1", "Free tools"]
---

# Find the representative pages of a website from its sitemaps, before generating a persona brief (free tool)

`POST /api/v1/tools/persona-brief/discover`

## Request

- Base URL: `https://app.serpmantics.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.serpmantics.com/api/v1/tools/persona-brief/discover`
- Auth: one of:
  - none
  - HTTP bearer

Reads the sitemaps of a website (declared in robots.txt, otherwise /sitemap.xml,
/sitemap_index.xml and /wp-sitemap.xml) and returns up to 200 URLs of the same host, editorial
pages first. The first URLs, as many as the URL limit of your tier, are flagged `suggested`:
send them in `urls` to `POST /api/v1/tools/persona-brief`.

Same tiers as the creation call, with their own daily counter per UTC day: 20 discoveries per
day per IP address without an API key, 50 for a signed-in account, 200 with the API key of an
account whose plan includes API access. A key whose plan does not include API access returns
401: remove the `Authorization` header to use the free anonymous tier.

Quota headers: `X-RateLimit-Limit`, `X-RateLimit-Used`, `X-RateLimit-Remaining`,
`X-RateLimit-Reset`. `Retry-After` is set on 429 and 503. A 400, 502 or 503 answer gives the
consumed quota back; SERVICE_UNAVAILABLE consumes none.

**Request format.** Send the body as JSON with `Content-Type: application/json`: any other
content type returns 415. Without an `Authorization` header, a request sent by a web page of
another site (an `Origin` other than the SERPmantics app, or `Sec-Fetch-Site: cross-site`)
returns 403. Server-to-server calls send no `Origin` header and are not affected.

## Request body

- object
  - `site` string, required: URL or domain of the website. A bare domain is completed with https.

## Response `200`

Pages found in the sitemaps.

- object
  - `success` boolean
  - `data` object
    - `site` string
    - `sitemapsRead` integer
    - `totalFound` integer
    - `truncated` boolean
    - `urls` object[]
      - `url` string
      - `lastmod` string, date-time, nullable: Last modification date read in the sitemap, ISO 8601 UTC, null when absent or unreadable.
      - `suggested` boolean

## Other responses

- `400`: INVALID_INPUT or INVALID_URL, the site is missing or is not an http(s) URL (details.reason NOT_HTTP_URL or TOO_LONG), refused before any quota is consumed. INVALID_URL with details.reason UNRESOLVABLE_HOST when the domain does not resolve, and BLOCKED_ADDRESS when the address is private, local or blocked: in both cases nothing was read and the quota is given back.
- `401`: UNAUTHORIZED, the Authorization header does not authenticate. Remove it to use the free anonymous tier.
- `403`: CROSS_SITE_FORBIDDEN, request without an Authorization header sent by a web page of another site (Origin other than the SERPmantics app, or Sec-Fetch-Site cross-site). Refused before any quota is consumed. Server-to-server calls send no Origin header and are not affected.
- `405`: METHOD_NOT_ALLOWED
- `415`: UNSUPPORTED_MEDIA_TYPE, the body is not sent with Content-Type application/json (a charset parameter is accepted). Refused before authentication and before any quota is consumed.
- `422`: NO_SITEMAP, no sitemap was found. The site was reached and its robots.txt read, so the discovery stays counted. Send the URLs of a few articles directly to the creation call.
- `429`: RATE_LIMITED, daily discovery limit of your tier reached. See details.reset_at. Retry-After is set.
- `502`: UPSTREAM_ERROR, the service did not answer. The quota is given back.
- `503`: SERVICE_BUSY, too many site discoveries are running: retry after Retry-After seconds, the quota is given back. SERVICE_UNAVAILABLE, the daily counter itself is unavailable: the request is refused before anything is read, no quota is consumed, and Retry-After says when to try again.

---

[API](https://skmtc.dev/serpmantics/apis/api-serpmantics.md) · [All operations](https://skmtc.dev/serpmantics/apis/api-serpmantics/llms.txt) · [OpenAPI document](https://skmtc.dev/serpmantics/apis/api-serpmantics/revisions/e71b28ef35a8?raw)