Browse all documentation

Write an article

Draft an article in the background from a fix, a tracked question or a brand page. Uses one monthly article.

POST/api/v1/brands/{brandId}/articleswrite

Call the corresponding write_article MCP tool with JSON arguments. Supply brandId and other path values as named arguments when the endpoint has them.

Request details

Required scope: A valid write token.

Request example
curl --request POST \
  --url "https://searchseal.com/api/v1/brands/b7e4c2a0-5d1f-4c8e-9a3b-2f6d8e1c4a70/articles" \
  --header "Authorization: Bearer $SEARCHSEAL_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"fixId":"f5c2e8a1-9d3b-4e7f-a0c6-1b4d7e9f2a38","format":"guide","length":"standard"}'

Returns 202 with the queued article. Use Get article until status is ready or failed, usually within two minutes.

If an article for the same fix, question or page is queued or writing, returns it without using another article.

At the monthly limit, 409 limit_reached includes articlesUsed and articlesMax. At the daily AI spending limit, returns 429 rate_limited.

Request parameters

NameLocationRequiredTypeDescription
brandIdpathYesuuidAn active brand ID returned by the brand list.
fixIdbodyNouuidA "Write a page" or "Improve a page" fix. Send it alone.
questionIdbodyNouuidA tracked question the page answers.
pageUrlbodyNostringA page on the brand's domain or a subdomain to rewrite.
formatbodyNo"guide" | "comparison" | "faq" | "how_to"Optional page format: guide, comparison, faq or how_to, chosen from the fix or question if omitted.
lengthbodyNo"short" | "standard" | "long"Optional length: short (about 600 words), standard (about 1,000, default) or long (about 1,600).
notesbodyNostringOptional owner instructions for the writer, up to 500 characters, such as facts to include or avoid.

Response fields

Response body example
{
  "id": "d8b3f1c6-4a2e-4d9b-8c7f-3e1a5b9d2c64",
  "brandId": "b7e4c2a0-5d1f-4c8e-9a3b-2f6d8e1c4a70",
  "fixId": "f5c2e8a1-9d3b-4e7f-a0c6-1b4d7e9f2a38",
  "questionId": "e3a9d1e2-7b4c-4f60-8e2a-9c1d5b7f3e21",
  "kind": "new_page",
  "pageUrl": null,
  "language": "en",
  "status": "queued",
  "title": null,
  "checkScore": null,
  "edited": false,
  "error": null,
  "source": "api",
  "createdAt": "2026-09-26T08:14:51.402Z",
  "finishedAt": null,
  "format": "guide",
  "length": "standard",
  "phase": null,
  "phaseAt": null,
  "publishedAt": null,
  "publishedUrl": null,
  "publishCheck": null,
  "proof": null,
  "metaDescription": null,
  "markdown": null,
  "html": null,
  "jsonld": null,
  "check": null,
  "notes": null,
  "meta": {
    "generatedAt": "2026-09-26T08:15:02.114Z",
    "timeZone": "Asia/Jakarta"
  }
}
FieldTypeDescription
iduuidArticle ID.
fixIduuid | nullThe fix it was written from.
questionIduuid | nullThe tracked question it answers.
kind"new_page" | "rewrite"A new page, or a rewrite of pageUrl on the brand site.
status"queued" | "writing" | "ready" | "failed"Writing takes a minute or two. A failed article counts toward your monthly limit only if AI processing already ran; error explains why it failed.
titlestring | nullThe page title once ready.
checkScoreinteger | nullThe draft page check score, 0 to 100.
editedbooleanWhether the owner has edited the draft.
format"guide" | "comparison" | "faq" | "how_to"Optional page format: guide, comparison, faq or how_to, chosen from the fix or question if omitted.
length"short" | "standard" | "long"Optional length: short (about 600 words), standard (about 1,000, default) or long (about 1,600).
phase"reading" | "writing" | "checking" | nullCurrent phase while queued or writing: reading_sources, writing or checking; null when finished or failed.
phaseAtstring | nullWhen the current phase started, in ISO 8601 format.
publishedAtstring | nullWhen the owner marked it published.
publishedUrlstring | nullWhere the page went live.
publishCheckobject | nullLive page check when marked published, outside your limit: { id, status, score, error }.
proofobject | nullBefore-and-after results for the completed fix: status (waiting, measured, not_comparable, not_measured), metric, before, after, change, dueAt, reason, and beforeAnswers/afterAnswers as { named, total }.
metaDescriptionstring | nullThe meta description.
notesstring | nullOptional owner instructions for the writer, up to 500 characters, such as facts to include or avoid.
markdownstring | nullPage Markdown, with owner edits when saved. Fill in every [bracketed placeholder] before publishing.
htmlstring | nullThe Markdown rendered, with no raw HTML.
jsonldobject | nullOrganization, Article and FAQPage structured data as one @graph.
checkobject | nullDraft page check: score, checks, todo (changes to make yourself) and autoFixed.

Successful REST responses from this endpoint include the shown meta fields. Read about data-through dates.

Possible errors

  • 400 invalid_request — An input failed validation. Field details may appear in errors.
  • 401 unauthorized — Authentication failed because the token is absent, unrecognized or revoked.
  • 403 forbidden — Account access or token permissions do not allow this request. Check the message for the cause.
  • 404 not_found — The resource is missing or unavailable to this account, including inactive brands.
  • 409 limit_reached — The account’s active-question capacity is exhausted.
  • 429 rate_limited — A quota was reached or could not be checked. Wait the Retry-After delay before retrying.
  • 500 server_error — The server failed to complete the operation.

For the shared error format, see status codes, quotas and retries. Next endpoint: Get article.