How to tell which format an article uses

GET the article:

GET /api/v2/sites/:site_id/articles/:article_id

A newly created article may not report schema_version: 5 until you write HTML with v5_contents. Always write the body with v5_contents for new articles.

Endpoints

Send Accept: application/json and JSON bodies on writes. Authenticate with Basic auth (login and API token or password) or an OAuth Bearer token. OAuth tokens need the kb.write scope for v5_contents and image uploads, including GET.

Create an article

POST /articles creates the article record. It does not set the body.

curl -u LOGIN:API_TOKEN \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"article":{"title":"How to reset a password","chapter_id":123,"published":false}}' \
  https://YOUR_ACCOUNT.screenstepslive.com/api/v2/sites/SITE_ID/articles

Store the returned id. Next, GET v5_contents (see below). Empty HTML on a new article is expected.

Read editable HTML

Use html_body from GET article when you only need to display the article. Use v5_contents when you will change it.

curl -u LOGIN:API_TOKEN \
  -H "Accept: application/json" \
  https://YOUR_ACCOUNT.screenstepslive.com/api/v2/sites/SITE_ID/articles/ARTICLE_ID/v5_contents

Example response:

{
  "article": {
    "id": 12345,
    "html": "<div data-doc-type=\"article\"><p>Existing HTML</p></div>",
    "schema_version": 5,
    "draft": true,
    "published": false,
    "etag": "\"abc123...\""
  }
}

• html is the current-editor document (what the editor stores), not a full HTML page.
• etag is required on the next PUT. Copy this JSON field exactly into the If-Match header.
• Do not send the response ETag header if it looks like W/"...". That weak form does not match and returns 412.

If this request returns 409 with code wrong_schema, the article is classic. Stop and use Updating article content through the API instead.

Update article HTML

PUT replaces the entire document. There is no PATCH on this path.

1. GET v5_contents and copy the JSON etag

    

2. Build the full HTML document

   Wrap the fragment in <div data-doc-type="article">...</div>. Prefer starting from the HTML you just fetched and changing only what you need. Do not send <html>, <body>, or inline data: images.

3. PUT v5_contents with If-Match and publish

   publish is required and must be inside the article object. true publishes a new version. false saves a working copy. A caller without publish permission who sends publish: true receives 403.

curl -u LOGIN:API_TOKEN \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "abc123..."' \
  -d '{"article":{"html":"<div data-doc-type=\"article\"><h2>Reset a password</h2><p>Open Settings, then choose Users.</p></div>","publish":false}}' \
  https://YOUR_ACCOUNT.screenstepslive.com/api/v2/sites/SITE_ID/articles/ARTICLE_ID/v5_contents

Successful response is the same shape as GET, with a new etag. Store that etag for the next write.

After publish: true, confirm "published": true and "draft": false in the JSON. HTTP 200 alone does not prove the article published.

Optional fields on the same article object:

• author_note_message — only valid when publish is true (stored with the published version).
• overwrite_connected_editors — default false. If someone has the article open in the live editor, PUT returns 409 editing_conflict unless this is true.

Example HTML

Headings, paragraphs, lists, and ScreenSteps blocks are siblings inside the wrapper:

<div data-doc-type="article">
  <h2>Reset a password</h2>
  <p>Open Settings, then choose Users.</p>
  <ol class="ss-block ss-block--steps">
    <li class="ss-block--steps__item" data-index="1">
      <span class="ss-block--steps__item-title">Select the user</span>
    </li>
    <li class="ss-block--steps__item" data-index="2">
      <span class="ss-block--steps__item-title">Click Reset password</span>
      <div class="ss-block--steps__item-body"><p>The user receives an email with a link.</p></div>
    </li>
  </ol>
</div>

Add images

New images do not go through POST /files. Prepare an upload, PUT the file bytes to the signed URL, then include the returned attributes on an <img> in the article HTML.

1. Prepare the upload

   POST /api/v2/sites/:site_id/articles/:article_id/v5_image_uploads
   
   {"v5_image_upload":{"filename":"screenshot.png"}}

   Allowed extensions: jpg, jpeg, png, gif, svg.

2. PUT the image bytes to upload_url

   Send any upload_headers from the prepare response. Confirm that PUT succeeded before writing the article.

3. PUT v5_contents with the image markup

   Apply html_attributes from the prepare response (src, data-cloud-asset-id, and related attributes) on the <img>. Image uploads do not change the article etag — reuse the etag from GET v5_contents.

Update metadata without changing HTML

Title, tags, published state, owner, and chapter stay on:

PUT /api/v2/sites/:site_id/articles/:id

Do not send html, html_body, or content_blocks on this request. A successful metadata update often returns {} with HTTP 200.

Delete an article

curl -u LOGIN:API_TOKEN \
  -X DELETE \
  -H "Accept: application/json" \
  https://YOUR_ACCOUNT.screenstepslive.com/api/v2/sites/SITE_ID/articles/ARTICLE_ID

Success is HTTP 204 with no body.

Common errors

v5_contents and image-upload errors use an array:

{
  "errors": [
    {"status": "412", "code": "stale_content", "title": "...", "detail": "..."}
  ]
}

Do not use these routes for current-editor articles

• POST /api/v2/sites/:site_id/articles/:id/contents
• POST /api/v2/sites/:site_id/articles/:id/html_import
• content_blocks on PUT/PATCH article
• POST /api/v2/sites/:site_id/files

Those routes write the legacy block schema, or they convert a current-editor article back to it.