Update a policy’s details

PATCH/workspaces/{workspace}/policies/{policy}

Changes the title, summary, owner, visibility, review cadence or requirement mapping. The policy text is edited through drafts, not here.

Authentication

Send an API token as a bearer token. This endpoint needs a read and write token, made by an editor, admin or owner. Create one in My account → API tokens; see scopes and roles.

Authorization: Bearer 42|bynh_pat_•••••••Header

Path parameters

workspacestringRequired
Your workspace slug, e.g. dokan.
policyintegerRequired
Policy id.

Request body

application/json

titlestringmax 160
Name (slug does not change).
visibilityenum
Where it appears. One of public, nda, internal.
review_every_daysenum
Changing it on a published policy recomputes next_review_at from the publish date. One of 90, 180, 365, 730.
summarystring, nullablemax 280
One-line summary.
owner_idinteger, nullable
A member of this workspace. Defaults to you on create.
requirement_idsstring, nullablemax 200
Replaces the mapping; each must be a requirement of a followed framework.

Response

200 OK

Policy detail.

idintegerPolicy id (used in paths).
slugstringUsed in the public URL.
titlestringName.
summarystring|nullOne-line summary.
owner{id, name}|nullOwner.
visibilityenumWhere it appears. One of public, nda, internal.
visibility_labelstringLocalized.
review_every_daysenumReview cadence. One of 90, 180, 365, 730.
next_review_atstring|nullYYYY-MM-DD.
statusenumDerived from the open version and review date. One of draft, in_review, changes_requested, published, review_due, overdue.
published_versioninteger|nullPublished version number.
published_atstring|nullISO 8601.
open_versionobject|nullnumber, status (draft | in_review | changes_requested), reviewer {id, name}|null, waiting_on_you (for the token owner).
taglinestringLocalized one-liner, e.g. “v3 · v4 in draft”.
requirements_countintegerMapped requirements.
requirements[]objectid, code, title, framework {slug, short_name}, met.
closes{gaps, frameworks}Mapped requirements in followed frameworks that aren’t met today (what publishing could close).
publishedVersion|nullPublished version with body.
draftVersion|nullOpen version with body.
versions[]VersionAll versions, body null. Version: id, number, status (draft | in_review | changes_requested | published | superseded), body, change_summary, in_changelog, author, reviewer, requested_by, review_note, review_requested_at, reviewer_note, reviewed_at, published_by, published_at, created_at, updated_at.
public_urlstring|nullSet only for public policies with a published version.
trust_domainstringCustom domain or {slug}.bynh.io.
people[]{id, name, role}Members who can edit.
summary_excerptstring|nullExcerpt of the published body.

Rate limits

This endpoint counts toward your general limit of 120 requests a minute and its own limit of 60 a minute. Its own limit answers 429 without Retry-After; wait and try again.

Errors

401The token is missing, wrong, revoked or expired.

403The token is read-only (message: “This token is read-only. Create a read and write token to make changes.”). Or: The token’s owner is a viewer (“Viewers can read everything but can’t change it.”), or the workspace’s editing is paused (a billing message, e.g. “Your trial has ended, so editing is paused. …”).

404The token belongs to another workspace, or its owner is no longer a member.

422Messages include “Give the policy a name, like “Data retention”.”, “Keep the name to 160 characters.”, “Choose where the policy appears.”, “Choose how often it’s reviewed.”, “Choose someone in this workspace.”, “Keep the summary to 280 characters.”, “The policy is too long. Keep it under 60,000 characters.”, “Pick requirements from the frameworks you follow.”

429evidence-writes limit (60/min).

Every error is JSON with a message. See Errors.

Next →Mark a policy reviewed

curl -X PATCH "https://api.bynh.io/api/v1/workspaces/dokan/policies/1" \
  -H "Authorization: Bearer $BYNH_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_id": 21,
    "review_every_days": 180
  }'

Response200 OK

application/json

{
  "data": {
    "id": 6,
    "slug": "access-control",
    "title": "Access control",
    "summary": "Who can reach Dokan systems and data, and how access is granted and removed.",
    "owner": {
      "id": 14,
      "name": "Sara Alqahtani"
    },
    "visibility": "public",
    "visibility_label": "Public",
    "review_every_days": 180,
    "next_review_at": "2026-10-11",
    "status": "review_due",
    "published_version": 3,
    "published_at": "2026-04-14T11:20:00+00:00",
    "open_version": null,
    "tagline": "v3 · Added MFA for the back office",
    "requirements_count": 4,
    "requirements": [
      {
        "id": 1204,
        "code": "A.5.15",
        "title": "Access control",
        "framework": {
          "slug": "iso-27001",
          "short_name": "ISO 27001"
        },
        "met": true
      }
    ],
    "closes": {
      "gaps": 0,
      "frameworks": 0
    },
    "published": {
      "id": 41,
      "number": 3,
      "status": "published",
      "body": "## 1. Why this policy exists\n\nDokan grants access on a need-to-know basis…",
      "change_summary": "Added MFA for the back office",
      "in_changelog": true,
      "author": {
        "id": 14,
        "name": "Sara Alqahtani"
      },
      "reviewer": {
        "id": 21,
        "name": "Faisal Alharbi"
      },
      "requested_by": {
        "id": 14,
        "name": "Sara Alqahtani"
      },
      "review_note": null,
      "review_requested_at": "2026-04-10T09:00:00+00:00",
      "reviewer_note": "Looks right.",
      "reviewed_at": "2026-04-13T15:32:10+00:00",
      "published_by": {
        "id": 14,
        "name": "Sara Alqahtani"
      },
      "published_at": "2026-04-14T11:20:00+00:00",
      "created_at": "2026-04-09T08:12:00+00:00",
      "updated_at": "2026-04-14T11:20:00+00:00"
    },
    "draft": null,
    "versions": [
      {
        "id": 41,
        "number": 3,
        "status": "published",
        "body": null,
        "change_summary": "Added MFA for the back office",
        "in_changelog": true,
        "author": {
          "id": 14,
          "name": "Sara Alqahtani"
        },
        "reviewer": {
          "id": 21,
          "name": "Faisal Alharbi"
        },
        "requested_by": {
          "id": 14,
          "name": "Sara Alqahtani"
        },
        "review_note": null,
        "review_requested_at": "2026-04-10T09:00:00+00:00",
        "reviewer_note": "Looks right.",
        "reviewed_at": "2026-04-13T15:32:10+00:00",
        "published_by": {
          "id": 14,
          "name": "Sara Alqahtani"
        },
        "published_at": "2026-04-14T11:20:00+00:00",
        "created_at": "2026-04-09T08:12:00+00:00",
        "updated_at": "2026-04-14T11:20:00+00:00"
      }
    ],
    "public_url": "https://trust.dokan.sa/policies/access-control",
    "trust_domain": "trust.dokan.sa",
    "people": [
      {
        "id": 21,
        "name": "Faisal Alharbi",
        "role": "editor"
      },
      {
        "id": 14,
        "name": "Sara Alqahtani",
        "role": "owner"
      }
    ],
    "summary_excerpt": "Dokan grants access on a need-to-know basis…"
  }
}

Examples use Dokan, a sample workspace. Responses are shortened where lists are long.