Skip to main content
A version is a frozen copy of an article’s title, content, and language taken at a specific point in the article’s history. Versions exist so you can audit edits and roll back to a prior body when a change goes wrong.

​
How versions are written

There are two paths into the version log. Both append immutable rows to the article’s history.

​
Auto-snapshots on PATCH

Every PATCH /articles/{id} that changes title or content snapshots the previous state before the new values land. The snapshot’s change_summary is "Auto-snapshot before API update". You don’t have to do anything to opt in — auto-snapshotting is the default for the API surface, so any edit is reversible.
A PATCH that only touches metadata (status, visibility, category, language, tags) does not create a snapshot — the body didn’t change.

​
Manual snapshots

POST /articles/{id}/versions writes a version from the article’s current state. Use this when you want to mark a checkpoint that didn’t ride along with an edit — e.g. before a risky bulk PATCH, or to annotate a published version with a meaningful change_summary. 
curl https://api.awardee.dev/v1/articles/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e/versions \
  -X POST \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e" \
  -H "Content-Type: application/json" \
  -d '{ "change_summary": "Pre-rewrite checkpoint" }'

​
The version object

{
  "object": "article_version",
  "id": "5d694e14-5440-4f5d-9e8a-7c3b2a1d0f9e",
  "article_id": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "version_number": 3,
  "title": "Returns & refunds",
  "content": "## Our policy\n\nReturns are accepted within 30 days...",
  "language": "en",
  "change_summary": "Auto-snapshot before API update",
  "created_at": "2026-05-22T14:20:00+00:00"
}
​
version_number
integer
required
Monotonically increasing per article, starting at 1. Gaps don’t appear; deletes aren’t supported.
​
language
string
required
The language tag the article carried when the snapshot was taken. A snapshot captures one language at a time — the primary article’s language. Translations are not versioned through the API.
​
change_summary
string | null
Free-form note attached to the snapshot. For auto-snapshots this is set to "Auto-snapshot before API update"; for manual snapshots it’s whatever you passed in the body.

​
Listing and reading

GET /articles/{id}/versions is paginated (page, page_size). GET /articles/{id}/versions/{version} reads one by its integer version_number. 
# List versions
curl "https://api.awardee.dev/v1/articles/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e/versions?page=1&page_size=25" \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"

# Read a specific version
curl https://api.awardee.dev/v1/articles/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e/versions/2 \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"

​
Restoring a prior version

POST /articles/{id}/versions/{version}/restore copies the version’s title and content back into the live article. The article’s current state is snapshotted first, so the restore is itself reversible — you can roll the restore back by restoring the snapshot it created. 
curl https://api.awardee.dev/v1/articles/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e/versions/2/restore \
  -X POST \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e" \
  -H "Idempotency-Key: restore-2026-05-22-1"
The response is the article in its restored state. If the article was published at the time of the restore, the indexing pipeline re-runs against the restored body — you’ll see indexing_status move back through pending → processing → indexed, and the article.indexed webhook fires when it lands.
Restoring a published article requires the articles.publish scope (in addition to articles.manage), because the live, indexed body is being overwritten. API keys are org-wide so this matters only for OAuth tokens.

​
Limitations

  • Versions are immutable. There is no PATCH or DELETE endpoint for an article_version.
  • Versions snapshot the primary language only. Translations are not versioned through the API.
  • Deleting an article deletes all of its versions.