Build a content brief

Embed
Preview of the card
<a href="https://seolyticize.com/docs/ref-build-content-brief"><img src="https://seolyticize.com/docs/_api/public/orgs/71cb2b7a-a719-4003-b3ea-6321dc1db8ab/spaces/3bf2dbf7-3faa-473c-ba3b-30588f5f8de4/pages/4fde7a11-e375-445c-bccd-735f42136a15/social-card.svg?v=3e7ae33eec8b" alt="Build a content brief" width="600" height="315"></a>
POSThttps://seolyticize.com/api/v1/tools/build_content_brief

A writer's brief for a keyword (or a cluster: the keyword plus relatedKeywords), built from the pages that rank: search intent and the format that wins (list, how-to, comparison, review, landing page, article), target length, the outline to cover, must-cover and nice-to-have terms, questions to answer (People Also Ask and the ranking pages'), structure and schema to include, the client's own pages to link to and from, and each competing page with what it misses — and ownership, a warning for each keyword the keyword registry already gives another page ('this already belongs to /x'). Also: each competitor scored 1–10 on depth, format, SEO and UX (out of 40), with claude-seo's full excluded list left out as non-competitors (encyclopedias, social and content platforms, search engines, marketplaces, forums, news and media, data platforms, directories, comparison aggregators, job boards, SEO tools, AI platforms, government and academic domains, and tag, author, login, legal and feed paths on any domain), and thinCompetition set when fewer than 3 real competitors remain; a section template for the page type (pageType: service, blog, case_study, category, landing, faq, location, about or homepage; default from the intent) with its goal, sections, schema (never FAQPage) and keyword placement; gaps typed topic, depth or quality with priority = impact × advantage ÷ effort; a required information-gain statement; the E-E-A-T the page needs; words per section; the featured-snippet section and format; title 50–60 and description 130–150 character targets; and with targetUrl, improve mode marking each section keep, strengthen or add against the page as it stands. Answers 'brief me on this keyword' and 'what should this post cover'. save: true keeps it as a research note on the client brief. Same cost as get_serp_content_profile.

Parameters

Idempotency-Keystringheader
Any unique string, up to 200 characters. A retry with the same key and body is answered from the first answer (Idempotent-Replayed: true) for a day, so it never buys or writes twice; the same key with another body is refused.

Request body

application/json
clientIdstringrequired
keywordstringrequired
relatedKeywordsstring[]
targetUrlstring
The page this brief is for, if it exists, so it is not suggested as its own internal link.
pageTypestring
The kind of page, for its section template: service, blog, case_study, category, landing, faq, location, about or homepage. Default: guessed from the search intent.
depthinteger
= 10
saveboolean
= false
locationCodeinteger
Google location code (2840 United States, 2826 United Kingdom, 2724 Spain). Default: the client's project.
= null
languageCodestring
Language code (en, es). Default: the client's project.
= null
maxCostMicrosinteger
Optional spending limit for this call, in micro-USD (1,000,000 = $1). A purchase that would take the call past it is refused before anything is bought. Pass the estimate from estimate_cost, or what the user agreed to spend.
dryRunboolean
True to buy nothing and get the quote instead: what the call would cost at most and what it would buy.
{
  "clientId": "string",
  "keyword": "string",
  "relatedKeywords": [
    "string"
  ],
  "targetUrl": "string",
  "pageType": "service",
  "depth": 10,
  "save": false,
  "locationCode": null,
  "languageCode": null,
  "maxCostMicros": 0,
  "dryRun": true
}

Code samples

cURL
curl -X POST "https://seolyticize.com/api/v1/tools/build_content_brief" \
  -H "Authorization: Bearer $SEOLYTICIZE_API_KEY" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"string","keyword":"string","relatedKeywords":["string"],"targetUrl":"string","pageType":"service","depth":10,"save":false,"locationCode":null,"languageCode":null,"maxCostMicros":0,"dryRun":true}'
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 The tool's result under data, and its meta.
Example
{
  "data": {},
  "meta": {
    "requestId": "string",
    "costMicros": 0,
    "cached": true,
    "cachedFrom": "string",
    "dataAsOf": "string",
    "sources": [
      "string"
    ],
    "partial": true,
    "next": [
      {
        "tool": "string",
        "args": {},
        "why": "string"
      }
    ],
    "nextCursor": "string",
    "dryRun": true
  }
}
Schema
datarequired
metaobjectrequired
Beside every answer: what it cost, whether it came from cache, how fresh it is, whether it is complete, and what to call next.
Show child parameters
requestIdstringrequired
costMicrosintegerrequired
Charged by this call, micro-USD (1,000,000 = $1).
cachedbooleanrequired
True when nothing was bought.
cachedFromstring
When the oldest cached answer used was bought.
dataAsOfstring
sourcesstring[]
partialbooleanrequired
True when the data is incomplete: a running crawl, unfinished days, unread pages.
nextobject[]required
Show child parameters
toolstring
argsobject
whystring
nextCursorstring
Pass as cursor for the next page.
dryRunboolean
Headers
X-RateLimit-Limitinteger
Requests this key may make per window.
X-RateLimit-Remaininginteger
Requests left in the current window.
X-RateLimit-Resetinteger
Seconds until the current window resets.
X-Request-Idstring
The id to quote about this request.
400 The body was not JSON or did not match the tool's input schema.
Example
{
  "error": "string",
  "code": "string",
  "next": "string",
  "requestId": "string"
}
Schema
errorstringrequired
A sentence written for the caller. Internal failures are reduced to 'The request could not be completed.' and never carry detail.
codestring
A stable snake_case reason to branch on; GET /api/v1/errors lists them all.
nextstring
The call or step that fixes it, when there is one.
requestIdstring
Quote it when asking about a failure.
Headers
X-RateLimit-Limitinteger
Requests this key may make per window.
X-RateLimit-Remaininginteger
Requests left in the current window.
X-RateLimit-Resetinteger
Seconds until the current window resets.
401 No key, or a key that is unknown or revoked.

Same as 400 · POST /api/v1/tools/build_content_brief

Headers
WWW-Authenticatestring
403 The key's role does not permit the tool, or the key may not reach the named client.

Same as 400 · POST /api/v1/tools/build_content_brief

Headers
X-RateLimit-Limitinteger
Requests this key may make per window.
X-RateLimit-Remaininginteger
Requests left in the current window.
X-RateLimit-Resetinteger
Seconds until the current window resets.
404 No tool by that name.

Same as 400 · POST /api/v1/tools/build_content_brief

Headers
X-RateLimit-Limitinteger
Requests this key may make per window.
X-RateLimit-Remaininginteger
Requests left in the current window.
X-RateLimit-Resetinteger
Seconds until the current window resets.
409 A request with this Idempotency-Key is still running.

Same as 400 · POST /api/v1/tools/build_content_brief

Headers
X-RateLimit-Limitinteger
Requests this key may make per window.
X-RateLimit-Remaininginteger
Requests left in the current window.
X-RateLimit-Resetinteger
Seconds until the current window resets.
422 A well-formed request the product declined, with the reason — a duplicate name, a plan limit, nothing configured to run.

Same as 400 · POST /api/v1/tools/build_content_brief

Headers
X-RateLimit-Limitinteger
Requests this key may make per window.
X-RateLimit-Remaininginteger
Requests left in the current window.
X-RateLimit-Resetinteger
Seconds until the current window resets.
429 This key has used its window.

Same as 400 · POST /api/v1/tools/build_content_brief

Headers
X-RateLimit-Limitinteger
Requests this key may make per window.
X-RateLimit-Remaininginteger
Requests left in the current window.
X-RateLimit-Resetinteger
Seconds until the current window resets.
Retry-Afterinteger
Seconds to wait before retrying.
500 The request could not be completed.

Same as 400 · POST /api/v1/tools/build_content_brief

Headers
X-RateLimit-Limitinteger
Requests this key may make per window.
X-RateLimit-Remaininginteger
Requests left in the current window.
X-RateLimit-Resetinteger
Seconds until the current window resets.
Updated