create_persona_brief

io.github.AmauryDvl/serpmantics · Verify this server

Generate 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.