Skip to Content
APIEndpointsSuggest content edits

Suggest content edits

Stores suggested changes to a draft’s body for the team to review in the editor, where each suggestion shows as red and green text with its reason and is accepted or declined there. Nothing in the article changes until someone accepts.

  • Each suggestion is one decision: a reason (at most two sentences, plain text), a category and the block edits that make it.
  • Sending again while earlier suggestions are still undecided adds to them: the earlier ones are kept where their passage is unchanged, and kept_from_before and dropped_from_before say how many.
  • Refused with 409 conflict once the team has started deciding, while a Content Refresh review is open, or while a finished review waits to be published.
  • List content suggestions shows what the team decided.

Requires the write:content scope, and the workspace must be enabled for API writes.

POST /v1/brands/{brand_id}/content/{draft_id}/suggestions

Authorization

HeaderTypeRequired
AuthorizationBearer asky_sk_…required
Idempotency-Keystringrequired

Path parameters

ParameterTypeRequiredDescription
brand_iduuidrequiredFrom List brands
draft_iduuidrequiredFrom List content drafts

Query parameters

None.

Body

application/json, up to 1 MB.

FieldTypeRequiredDescription
suggestionsarray, 1 to 20requiredEach { "reason": "...", "category": "...", "edits": [...] }; at most 40 edits across all suggestions
suggestions[].reasonstring, up to 300 charsrequiredWhy, for the reviewer. At most two sentences
suggestions[].categorystringrequiredOne of structure, answers, faq, freshness, citations, links, brand_density, voice, readability, keywords, coverage, format_fit, metadata, schema
suggestions[].editsarrayrequiredBlock edits, below

Block edits

Body edits address the numbered blocks Get content outline returns. Each edit is one object:

FieldTypeRequiredDescription
op"replace" | "insert" | "delete"requiredreplace swaps block N, insert places new html before block N (N equal to the block count appends), delete removes block N
indexintegerrequiredBlock index from the outline
htmlstring, up to 20,000 charsfor replace and insertThe new html
base_hashstringrequired while the body has blocksThe outline’s hash for block N; for an append, the last block’s
  • Indexes are fixed: every index addresses the outline as you read it, never as changed by your other edits. To add several blocks in one place, send one insert per block, all with the same index, in reading order.
  • An edit whose base_hash no longer matches its block is refused with 409 conflict, and so is the whole set: read the outline again and rebuild the edits. Nothing is written.
  • Allowed tags: p, h1 to h5, ul, ol, li, blockquote, pre, code, strong, em, s, u, a, img, hr, br, table, tr, th, td. Anything else is removed before the edit is checked, as the editor would store it.
  • An img may only use an image already in the draft.
  • At most 40 edits per call, one per block.

Request

curl --request POST \ --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/content/7c1e2b90-3f4d-4a8e-9b21-5d6f7a8b9c0d/suggestions' \ --header 'Authorization: Bearer <api-key>' \ --header 'Idempotency-Key: <unique-per-attempt>' \ --header 'Content-Type: application/json' \ --data '{"suggestions":[{"reason":"Answers the question in the first sentence, which AI answers quote most.","category":"answers","edits":[{"op":"replace","index":1,"html":"<p>A CRM gives a small team one shared record of every customer.</p>","base_hash":"a83b0d71"}]}]}'

Response

{ "data": { "suggestion_id": "0b9d6c4e-21a7-4f3b-8e5d-9c1a2b3c4d5e", "draft_id": "7c1e2b90-3f4d-4a8e-9b21-5d6f7a8b9c0d", "suggestions": 1, "added": 1, "kept_from_before": 0, "dropped_from_before": 0, "review_url": "https://app.askylabs.com/content/7c1e2b90-3f4d-4a8e-9b21-5d6f7a8b9c0d", "live_page_updated": false, "translations_unchanged": [] }, "request_id": "req_7d21b0af59c34e18b6ac" }

Response fields

FieldTypeDescription
data.suggestion_iduuidrequired. The set waiting for review; withdraw it with Withdraw content suggestions
data.draft_iduuidrequired
data.suggestionsintegerrequired. Suggestions in the set
data.addedintegerrequired. Suggestions this call added
data.kept_from_beforeintegerrequired. Undecided earlier suggestions carried into the set
data.dropped_from_beforeintegerrequired. Earlier suggestions left out: their passage changed, their change is already in the article, or this call changes the same block
data.review_urlstringrequired. Where the team reviews the set
data.live_page_updatedbooleanrequired. Always false
data.translations_unchangedarrayrequired. The draft’s translations, which suggestions do not reach
request_idstringrequired
Last updated on