Policy Governance

Propose a policy change (maker)

Proposes a change to a policy’s content (Policy Governance, maker-checker). is the existing version this proposal is a change against (“the version being replaced”); proposedContent’s own policyVersion may equal it (an in-place content patch) or differ (a version bump). Requires a human-authenticated caller (credentialHolderType USER); a SERVICE-credentialed or unverified caller is denied with 403 NON_HUMAN_CALLER_DENIED, and a signed caller.non_human_denied audit event is recorded. proposedContent is validated with the same rules POST /policies/validate checks, plus: proposedContent.policyId must equal , and proposedContent.policyVersion must match ^[A-Za-z0-9._-]+$.

POST

policies

{name}

{version}

pending-changes

Propose a policy change (maker)

curl --request POST \
  --url http://localhost:3000/policies/{name}/{version}/pending-changes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "proposedContent": {
    "policyId": "openapi-capture-demo",
    "policyVersion": "1.0.0",
    "schemaVersion": "1.0.0",
    "rules": [
      {
        "id": "always-approve",
        "condition": {
          "always": true
        },
        "outcome": {
          "action": "approve",
          "reason": "OpenAPI spec capture fixture"
        }
      }
    ]
  },
  "reason": "Capture a real Pending Policy Change for the OpenAPI spec"
}
'

import requests

url = "http://localhost:3000/policies/{name}/{version}/pending-changes"

payload = {
    "proposedContent": {
        "policyId": "openapi-capture-demo",
        "policyVersion": "1.0.0",
        "schemaVersion": "1.0.0",
        "rules": [
            {
                "id": "always-approve",
                "condition": { "always": True },
                "outcome": {
                    "action": "approve",
                    "reason": "OpenAPI spec capture fixture"
                }
            }
        ]
    },
    "reason": "Capture a real Pending Policy Change for the OpenAPI spec"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    proposedContent: {
      policyId: 'openapi-capture-demo',
      policyVersion: '1.0.0',
      schemaVersion: '1.0.0',
      rules: [
        {
          id: 'always-approve',
          condition: {always: true},
          outcome: {action: 'approve', reason: 'OpenAPI spec capture fixture'}
        }
      ]
    },
    reason: 'Capture a real Pending Policy Change for the OpenAPI spec'
  })
};

fetch('http://localhost:3000/policies/{name}/{version}/pending-changes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "3000",
  CURLOPT_URL => "http://localhost:3000/policies/{name}/{version}/pending-changes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'proposedContent' => [
        'policyId' => 'openapi-capture-demo',
        'policyVersion' => '1.0.0',
        'schemaVersion' => '1.0.0',
        'rules' => [
                [
                                'id' => 'always-approve',
                                'condition' => [
                                                                'always' => true
                                ],
                                'outcome' => [
                                                                'action' => 'approve',
                                                                'reason' => 'OpenAPI spec capture fixture'
                                ]
                ]
        ]
    ],
    'reason' => 'Capture a real Pending Policy Change for the OpenAPI spec'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:3000/policies/{name}/{version}/pending-changes"

	payload := strings.NewReader("{\n  \"proposedContent\": {\n    \"policyId\": \"openapi-capture-demo\",\n    \"policyVersion\": \"1.0.0\",\n    \"schemaVersion\": \"1.0.0\",\n    \"rules\": [\n      {\n        \"id\": \"always-approve\",\n        \"condition\": {\n          \"always\": true\n        },\n        \"outcome\": {\n          \"action\": \"approve\",\n          \"reason\": \"OpenAPI spec capture fixture\"\n        }\n      }\n    ]\n  },\n  \"reason\": \"Capture a real Pending Policy Change for the OpenAPI spec\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:3000/policies/{name}/{version}/pending-changes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"proposedContent\": {\n    \"policyId\": \"openapi-capture-demo\",\n    \"policyVersion\": \"1.0.0\",\n    \"schemaVersion\": \"1.0.0\",\n    \"rules\": [\n      {\n        \"id\": \"always-approve\",\n        \"condition\": {\n          \"always\": true\n        },\n        \"outcome\": {\n          \"action\": \"approve\",\n          \"reason\": \"OpenAPI spec capture fixture\"\n        }\n      }\n    ]\n  },\n  \"reason\": \"Capture a real Pending Policy Change for the OpenAPI spec\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:3000/policies/{name}/{version}/pending-changes")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"proposedContent\": {\n    \"policyId\": \"openapi-capture-demo\",\n    \"policyVersion\": \"1.0.0\",\n    \"schemaVersion\": \"1.0.0\",\n    \"rules\": [\n      {\n        \"id\": \"always-approve\",\n        \"condition\": {\n          \"always\": true\n        },\n        \"outcome\": {\n          \"action\": \"approve\",\n          \"reason\": \"OpenAPI spec capture fixture\"\n        }\n      }\n    ]\n  },\n  \"reason\": \"Capture a real Pending Policy Change for the OpenAPI spec\"\n}"

response = http.request(request)
puts response.read_body

{
  "pendingPolicyChangeId": "6f4e4020-adf5-4449-938d-27aab58f66b7",
  "policyName": "openapi-capture-demo",
  "policyVersion": "1.0.0",
  "proposedContent": {
    "policyId": "openapi-capture-demo",
    "policyVersion": "1.0.0",
    "schemaVersion": "1.0.0",
    "rules": [
      {
        "id": "always-approve",
        "condition": {
          "always": true
        },
        "outcome": {
          "action": "approve",
          "reason": "OpenAPI spec capture fixture"
        }
      }
    ]
  },
  "proposedBy": "human-maker",
  "proposedAt": "2026-09-15T03:47:13.920Z",
  "status": "PENDING_APPROVAL",
  "reason": "Capture a real Pending Policy Change for the OpenAPI spec"
}

{
  "error": "reason is required."
}

{
  "error": "authentication required"
}

{
  "error": "This action requires a caller credential provisioned as a verified human (credentialHolderType: USER).",
  "code": "NON_HUMAN_CALLER_DENIED"
}

Authorizations

Authorization

string

header

required

Caller API key issued by scripts/generate-api-key.ts. Sent as Authorization: Bearer . Verified against a stored SHA-256 hash in constant time by packages/api/src/auth/StaticKeyAuthenticator.ts. Required on every route not listed as exempt in this document's top-level description. See /api-reference/authentication.

Path Parameters

name

string

required

Pattern: ^[A-Za-z0-9._-]+$

version

string

required

Pattern: ^[A-Za-z0-9._-]+$

Body

application/json

Request body for POST /policies/{name}/{version}/pending-changes.

proposedContent

object

required

The full proposed policy.json content, in its entirety. Its policyId must equal the {name} path parameter, and its policyVersion must match ^[A-Za-z0-9._-]+$. Validated against the same rules POST /policies/validate checks.

reason

string

required

Free-text justification. Required, non-empty.

Response

Pending Policy Change created.

A proposed change to a policy's content, held in a durable pending state until a second, distinct human explicitly approves or rejects it (Policy Governance, maker-checker). Only ever moves from PENDING_APPROVAL to APPROVED or REJECTED, exactly once.

pendingPolicyChangeId

string

required

Unique Pending Policy Change identifier.

policyName

string

required

The policy this proposal targets, same identifier as Policy.policyId.

policyVersion

string

required

The existing version this proposal is a change against ("the version being replaced"). Not necessarily equal to proposedContent's own declared version: an in-place patch and a version bump are both legitimate.

proposedContent

object

required

The full proposed policy.json content, in its entirety, not a diff or patch.

proposedBy

string

required

Identity of the proposer (maker). Always a human-authenticated (credentialHolderType USER) caller.

proposedAt

string<date-time>

required

status

enum<string>

required

Available options:

PENDING_APPROVAL,

APPROVED,

REJECTED

reason

string

required

Free-text justification from the proposer, required at creation.

resolvedBy

string

Identity of the resolver (checker). Absent while PENDING_APPROVAL. Never equal to proposedBy.

resolvedAt

string<date-time>

Absent while PENDING_APPROVAL.

rejectionReason

string

Present only when status is REJECTED.

coverageWarnings

string[]

Present only when non-empty: uncovered-fact warnings from PolicyValidator.findUncoveredFacts against proposedContent.

ruleConflicts

string[]

Present only when non-empty: advisory rule-conflict warnings from PolicyValidator.findRuleConflicts against proposedContent, never blocking.

Propose a policy change (maker)

curl --request POST \
  --url http://localhost:3000/policies/{name}/{version}/pending-changes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "proposedContent": {
    "policyId": "openapi-capture-demo",
    "policyVersion": "1.0.0",
    "schemaVersion": "1.0.0",
    "rules": [
      {
        "id": "always-approve",
        "condition": {
          "always": true
        },
        "outcome": {
          "action": "approve",
          "reason": "OpenAPI spec capture fixture"
        }
      }
    ]
  },
  "reason": "Capture a real Pending Policy Change for the OpenAPI spec"
}
'

import requests

url = "http://localhost:3000/policies/{name}/{version}/pending-changes"

payload = {
    "proposedContent": {
        "policyId": "openapi-capture-demo",
        "policyVersion": "1.0.0",
        "schemaVersion": "1.0.0",
        "rules": [
            {
                "id": "always-approve",
                "condition": { "always": True },
                "outcome": {
                    "action": "approve",
                    "reason": "OpenAPI spec capture fixture"
                }
            }
        ]
    },
    "reason": "Capture a real Pending Policy Change for the OpenAPI spec"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    proposedContent: {
      policyId: 'openapi-capture-demo',
      policyVersion: '1.0.0',
      schemaVersion: '1.0.0',
      rules: [
        {
          id: 'always-approve',
          condition: {always: true},
          outcome: {action: 'approve', reason: 'OpenAPI spec capture fixture'}
        }
      ]
    },
    reason: 'Capture a real Pending Policy Change for the OpenAPI spec'
  })
};

fetch('http://localhost:3000/policies/{name}/{version}/pending-changes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "3000",
  CURLOPT_URL => "http://localhost:3000/policies/{name}/{version}/pending-changes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'proposedContent' => [
        'policyId' => 'openapi-capture-demo',
        'policyVersion' => '1.0.0',
        'schemaVersion' => '1.0.0',
        'rules' => [
                [
                                'id' => 'always-approve',
                                'condition' => [
                                                                'always' => true
                                ],
                                'outcome' => [
                                                                'action' => 'approve',
                                                                'reason' => 'OpenAPI spec capture fixture'
                                ]
                ]
        ]
    ],
    'reason' => 'Capture a real Pending Policy Change for the OpenAPI spec'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:3000/policies/{name}/{version}/pending-changes"

	payload := strings.NewReader("{\n  \"proposedContent\": {\n    \"policyId\": \"openapi-capture-demo\",\n    \"policyVersion\": \"1.0.0\",\n    \"schemaVersion\": \"1.0.0\",\n    \"rules\": [\n      {\n        \"id\": \"always-approve\",\n        \"condition\": {\n          \"always\": true\n        },\n        \"outcome\": {\n          \"action\": \"approve\",\n          \"reason\": \"OpenAPI spec capture fixture\"\n        }\n      }\n    ]\n  },\n  \"reason\": \"Capture a real Pending Policy Change for the OpenAPI spec\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:3000/policies/{name}/{version}/pending-changes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"proposedContent\": {\n    \"policyId\": \"openapi-capture-demo\",\n    \"policyVersion\": \"1.0.0\",\n    \"schemaVersion\": \"1.0.0\",\n    \"rules\": [\n      {\n        \"id\": \"always-approve\",\n        \"condition\": {\n          \"always\": true\n        },\n        \"outcome\": {\n          \"action\": \"approve\",\n          \"reason\": \"OpenAPI spec capture fixture\"\n        }\n      }\n    ]\n  },\n  \"reason\": \"Capture a real Pending Policy Change for the OpenAPI spec\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:3000/policies/{name}/{version}/pending-changes")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"proposedContent\": {\n    \"policyId\": \"openapi-capture-demo\",\n    \"policyVersion\": \"1.0.0\",\n    \"schemaVersion\": \"1.0.0\",\n    \"rules\": [\n      {\n        \"id\": \"always-approve\",\n        \"condition\": {\n          \"always\": true\n        },\n        \"outcome\": {\n          \"action\": \"approve\",\n          \"reason\": \"OpenAPI spec capture fixture\"\n        }\n      }\n    ]\n  },\n  \"reason\": \"Capture a real Pending Policy Change for the OpenAPI spec\"\n}"

response = http.request(request)
puts response.read_body

{
  "pendingPolicyChangeId": "6f4e4020-adf5-4449-938d-27aab58f66b7",
  "policyName": "openapi-capture-demo",
  "policyVersion": "1.0.0",
  "proposedContent": {
    "policyId": "openapi-capture-demo",
    "policyVersion": "1.0.0",
    "schemaVersion": "1.0.0",
    "rules": [
      {
        "id": "always-approve",
        "condition": {
          "always": true
        },
        "outcome": {
          "action": "approve",
          "reason": "OpenAPI spec capture fixture"
        }
      }
    ]
  },
  "proposedBy": "human-maker",
  "proposedAt": "2026-09-15T03:47:13.920Z",
  "status": "PENDING_APPROVAL",
  "reason": "Capture a real Pending Policy Change for the OpenAPI spec"
}

{
  "error": "reason is required."
}

{
  "error": "authentication required"
}

{
  "error": "This action requires a caller credential provisioned as a verified human (credentialHolderType: USER).",
  "code": "NON_HUMAN_CALLER_DENIED"
}

Get Started

Core Concepts

Guides

SDKs

REST API

Security & Deployment

Integrations

Tutorials

Advanced

Support

Changelog

Propose a policy change (maker)

Authorizations

Path Parameters

Body

Response