Skip to content
adversarial

Change which version of a document the organization is adopting

PATCH
/v1/documents/{slug}
curl --request PATCH \
  --url https://api.adversarial.com/api/v1/documents/cisp \
  --header 'Content-Type: application/json' \
  --data '{ "adopting_version": "2026.09.01" }'

Setting adopting_version starts holding that version so it can be configured from the new template’s defaults ahead of going live — no edits carry over from the version it replaces, and the current version remains the policy of record until the held version’s proposal is approved. Setting it to null releases whatever is held. Starting adoption denies any open proposal on the outgoing live version.

Idempotent in both directions: adopting the version already in force or already held, and releasing when nothing is held, all change nothing.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
slug
required
string

The document slug

Example
cisp

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Request to change which version an organization is adopting.

object
adopting_version
required

The version to adopt, or null to release the one being adopted. The field is required — a PATCH that names nothing is a client error, not a silent no-op.

string | null
Example
2026.09.01

Responses

Section titled “Responses”

200

Section titled “200”

How the organization now stands

Media typeapplication/json

How an organization stands on one document: the version in force, and the version it is adopting, if any. The body of GET/PATCH /documents/{slug}.

object
adopting_version
One of:

The version the organization holds but has not promoted. Approving its proposal is what makes it current.

string
current
One of:

The version currently in force — the organization’s policy of record. For an uninitialized document this is the template it would initialize to; None while an adoption started from that state is in flight, because the draft is then the only version the organization holds.

object
archived_date

When the organization retired this version. Only set on archived rows.

string | null format: date-time
category
required

The compliance-program section containing a document.

string
Allowed values: governance procedure policy
description
required
string
latest_version
required

The edition of a document as YYYY.MM.NN: the year and month it was issued, then a two-digit sequence number counting editions issued in that month.

string
slug
required
string
state
One of:
One of:

The document has not been initialized yet. It is possible for the document to have details, meaning that a proposal is “open” to initialize it.

object
value
required
string
Allowed values: uninitialized
title
required
string
version
required

The version this row describes.

string
version_state
required

Whether a document version is the organization’s current one, a retired one it previously used, or an in-flight adoption draft.

string
Allowed values: current archived draft
Example
{
  "adopting_version": "2026.09.01",
  "current": {
    "category": "governance",
    "latest_version": "2026.09.01",
    "slug": "cisp",
    "state": {
      "value": "uninitialized"
    },
    "version": "2026.09.01",
    "version_state": "current"
  }
}

404

Section titled “404”

No registered template with this slug and version

409

Section titled “409”

A different version of this document is already being adopted