Skip to content
bynhDocs
Log in

Create a policy

POST/workspaces/{workspace}/policies

Creates a policy with a draft version 1. Start from a template to get its text, summary and requirement mapping. Nothing is public until the draft is published.

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.

Request body

application/json

  • titlestringRequiredmax 160

    Name.

  • visibilityenumRequired

    Where it appears. One of public, nda, internal.

  • review_every_daysenumRequired

    Review cadence. One of 90, 180, 365, 730.

  • templateenum

    Fills body, summary and requirement_ids when you don’t send them. One of data-retention, business-continuity, vendor-management, access-control, incident-response, acceptable-use.

  • summarystring, nullablemax 280

    One-line summary.

  • owner_idinteger, nullable

    A member of this workspace. Defaults to you on create.

  • bodystring, nullablemax 60000

    Markdown for version 1 (create only; cleaned). On PATCH it is validated but ignored — edit text through the draft endpoints.

  • requirement_idsstring, nullablemax 200

    Replaces the mapping; each must be a requirement of a followed framework.

Response

201 Created

The 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 →Get a policy
curl -X POST "https://api.bynh.io/api/v1/workspaces/dokan/policies" \
  -H "Authorization: Bearer $BYNH_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Data retention",
    "visibility": "public",
    "review_every_days": 365,
    "template": "data-retention"
  }'

Response201 Created

application/json
{
  "data": {
    "id": 12,
    "slug": "data-retention",
    "title": "Data retention",
    "summary": "How long each kind of data is kept, and how it’s deleted.",
    "owner": {
      "id": 14,
      "name": "Sara Alqahtani"
    },
    "visibility": "public",
    "visibility_label": "Public",
    "review_every_days": 365,
    "next_review_at": null,
    "status": "draft",
    "published_version": null,
    "published_at": null,
    "open_version": {
      "number": 1,
      "status": "draft",
      "reviewer": null,
      "waiting_on_you": false
    },
    "tagline": "v1 draft",
    "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": 3,
      "frameworks": 2
    },
    "published": null,
    "draft": {
      "id": 77,
      "number": 1,
      "status": "draft",
      "body": "## 1. Why this policy exists\n\nDokan keeps data only as long as it needs it…",
      "change_summary": null,
      "in_changelog": false,
      "author": {
        "id": 14,
        "name": "Sara Alqahtani"
      },
      "reviewer": null,
      "requested_by": null,
      "review_note": null,
      "review_requested_at": null,
      "reviewer_note": null,
      "reviewed_at": null,
      "published_by": null,
      "published_at": null,
      "created_at": "2026-10-01T08:00:00+00:00",
      "updated_at": "2026-10-01T08:00:00+00:00"
    },
    "versions": [],
    "public_url": null,
    "trust_domain": "trust.dokan.sa",
    "people": [
      {
        "id": 21,
        "name": "Faisal Alharbi",
        "role": "editor"
      },
      {
        "id": 14,
        "name": "Sara Alqahtani",
        "role": "owner"
      }
    ],
    "summary_excerpt": null
  }
}

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