Get a policy

GET/workspaces/{workspace}/policies/{policy}

Returns one policy with its published text, any open draft, its version history, mapped requirements and public link.

Authentication

Send an API token as a bearer token. This endpoint needs a read token, made by any member of the workspace. 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 (not the slug).

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. When you go over, wait for the number of seconds in Retry-After.

Errors

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

404The token belongs to another workspace, or its owner is no longer a member. Or: No policy with that id in this workspace.

Every error is JSON with a message. See Errors.

Next →Update a policy’s details

curl "https://api.bynh.io/api/v1/workspaces/dokan/policies/1" \
  -H "Authorization: Bearer $BYNH_TOKEN" \
  -H "Accept: application/json"

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": 365,
    "next_review_at": "2027-04-14",
    "status": "published",
    "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.