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_beforeanddropped_from_beforesay how many. - Refused with
409 conflictonce 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}/suggestionsAuthorization
| Header | Type | Required |
|---|---|---|
Authorization | Bearer asky_sk_… | required |
Idempotency-Key | string | required |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_id | uuid | required | From List brands |
draft_id | uuid | required | From List content drafts |
Query parameters
None.
Body
application/json, up to 1 MB.
| Field | Type | Required | Description |
|---|---|---|---|
suggestions | array, 1 to 20 | required | Each { "reason": "...", "category": "...", "edits": [...] }; at most 40 edits across all suggestions |
suggestions[].reason | string, up to 300 chars | required | Why, for the reviewer. At most two sentences |
suggestions[].category | string | required | One of structure, answers, faq, freshness, citations, links, brand_density, voice, readability, keywords, coverage, format_fit, metadata, schema |
suggestions[].edits | array | required | Block edits, below |
Block edits
Body edits address the numbered blocks Get content outline returns. Each edit is one object:
| Field | Type | Required | Description |
|---|---|---|---|
op | "replace" | "insert" | "delete" | required | replace swaps block N, insert places new html before block N (N equal to the block count appends), delete removes block N |
index | integer | required | Block index from the outline |
html | string, up to 20,000 chars | for replace and insert | The new html |
base_hash | string | required while the body has blocks | The 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_hashno longer matches its block is refused with409 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
imgmay 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
200
{
"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
| Field | Type | Description |
|---|---|---|
data.suggestion_id | uuid | required. The set waiting for review; withdraw it with Withdraw content suggestions |
data.draft_id | uuid | required |
data.suggestions | integer | required. Suggestions in the set |
data.added | integer | required. Suggestions this call added |
data.kept_from_before | integer | required. Undecided earlier suggestions carried into the set |
data.dropped_from_before | integer | required. Earlier suggestions left out: their passage changed, their change is already in the article, or this call changes the same block |
data.review_url | string | required. Where the team reviews the set |
data.live_page_updated | boolean | required. Always false |
data.translations_unchanged | array | required. The draft’s translations, which suggestions do not reach |
request_id | string | required |
Last updated on