create_persona_brief
create_persona_briefGenerate an AI persona and brand voice brief from the pages of a website (free tool)
Reads public pages of a website and produces an editorial persona and writing style brief:
who writes, for whom, tone on 6 axes, vocabulary, structure, do and don't lists, verified
quotes from the pages, style metrics measured on the text, and a ready-to-paste writing
prompt for any AI writing tool (brief.writingPrompt, plus brief.writingPromptCompact
of at most 1500 characters).
Asynchronous, poll the result. This call only starts the job and answers HTTP 202 with a
briefId and a pollUrl. Call GET /api/v1/tools/persona-brief?briefId=... every 3 seconds
until status is done or failed. A brief takes about 80 seconds plus 5 seconds per page,
rounded up to the half minute: about 2 min for 3 pages, 2 min 30 s for 10 pages.
MCP clients must call the get_persona_brief tool again until the status is terminal.
Identical requests are reused for 72 hours. The same set of URLs, in any order, with the
same outputLanguage and the same brandName, returns the brief already computed instead of
computing it again: HTTP 200 with reused true, status already done, the original
briefId and reusedCreatedAt, the date of the brief it reuses. Nothing is created, and your
daily quota is given back, so a reused answer costs you nothing. The pages of a reused brief
are listed in the order of the original request, not in the order you just sent. Send
force true to skip the lookup and compute a new brief, which answers 202 and consumes quota.
Addresses. Duplicate URLs, compared once normalized, are read once. A private, local or
blocked address is not refused by this call: the brief is created, and that page ends with
status failed and failureReason BLOCKED_ADDRESS (the brief fails with NO_USABLE_PAGE when
no other page could be read).
Tiers, per UTC day. Every tier is capped at 10 URLs per brief since 21 September 2026.
Without an API key, free anonymous tier: 3 briefs per day per IP address, 10 URLs per brief.
Signed-in account on the web interface, plan without API access: 10 briefs per day, 10 URLs per brief.
API key of an account whose plan includes API access, pro tier: 50 briefs per day, 10 URLs per brief.
The API key of an account whose plan does NOT include API access does not authenticate, and the
call returns 401. Remove the Authorization header to use the free anonymous tier instead.
Quota headers: X-RateLimit-Limit, X-RateLimit-Used, X-RateLimit-Remaining,
X-RateLimit-Reset (Unix time of the next UTC midnight). Retry-After is set on 429 and 503.
A 502 or 503 answer gives the consumed quota back, and so does a 429 FREE_CAPACITY_REACHED
and a 200 reused answer; 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| urls | Yes | Public http(s) URLs of representative pages of one website, 5 to 10 articles give the best brief. At most 10 URLs, whatever the tier, each of at most 2048 characters. | |
| force | No | True to compute a new brief even when an identical one exists, which answers 202 and consumes quota. Any value that is not a boolean returns 400 INVALID_BODY. | |
| brandName | No | Optional brand name, on a single line, used in the brief. | |
| outputLanguage | No | Language in which the brief is written. When omitted, the service chooses it. |