Update Policy
curl --request PATCH \
--url https://{host}/api/policy/v2/policies/{policy_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"name": "<string>",
"description": "<string>",
"support_contact": "<string>",
"tags": [
"<string>"
],
"application_ids": [
"<string>"
],
"rules": [
{
"actions": [
"tools/call:create_issue"
],
"name": "Engineering read access",
"description": "<string>",
"authorized": false,
"active": true,
"roles_groups": [
"*"
],
"condition": {
"match": {
"expr": "P.attr.department == 'Engineering'"
}
}
}
]
}
EOFimport requests
url = "https://{host}/api/policy/v2/policies/{policy_id}"
payload = {
"name": "<string>",
"description": "<string>",
"support_contact": "<string>",
"tags": ["<string>"],
"application_ids": ["<string>"],
"rules": [
{
"actions": ["tools/call:create_issue"],
"name": "Engineering read access",
"description": "<string>",
"authorized": False,
"active": True,
"roles_groups": ["*"],
"condition": { "match": { "expr": "P.attr.department == 'Engineering'" } }
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
support_contact: '<string>',
tags: ['<string>'],
application_ids: ['<string>'],
rules: [
{
actions: ['tools/call:create_issue'],
name: 'Engineering read access',
description: '<string>',
authorized: false,
active: true,
roles_groups: ['*'],
condition: {match: {expr: 'P.attr.department == \'Engineering\''}}
}
]
})
};
fetch('https://{host}/api/policy/v2/policies/{policy_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{host}/api/policy/v2/policies/{policy_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'support_contact' => '<string>',
'tags' => [
'<string>'
],
'application_ids' => [
'<string>'
],
'rules' => [
[
'actions' => [
'tools/call:create_issue'
],
'name' => 'Engineering read access',
'description' => '<string>',
'authorized' => false,
'active' => true,
'roles_groups' => [
'*'
],
'condition' => [
'match' => [
'expr' => 'P.attr.department == \'Engineering\''
]
]
]
]
]),
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 := "https://{host}/api/policy/v2/policies/{policy_id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://{host}/api/policy/v2/policies/{policy_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{host}/api/policy/v2/policies/{policy_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"policy": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organization_id": "<string>",
"name": "<string>",
"status": "<string>",
"mcp_server_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"created_by_user_id": "<string>",
"updated_by_user_id": "<string>",
"support_contact": "<string>",
"description": "<string>",
"application_ids": [
"<string>"
],
"tags": [
"<string>"
],
"rules": [
{
"actions": [
"tools/call:create_issue"
],
"name": "Engineering read access",
"description": "<string>",
"authorized": false,
"active": true,
"roles_groups": [
"*"
],
"condition": {
"match": {
"expr": "P.attr.department == 'Engineering'"
}
}
}
]
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Policies
Update Policy
Update a policy. Sending rules REPLACES the entire rule list.
There is no “add a rule” operation. To add one, read the policy first and send
every existing rule back alongside the new one — sending only the new rule
deletes the others, and the call still returns 200 with a policy that looks
perfectly healthy. Omit rules entirely to change only metadata.
Verify afterwards rather than assuming: GET /v2/policies/{policy_id}/revisions
lists what each change actually did, and compare_policy_revisions diffs two of
them. A revision summarising removals you did not intend is how you catch a
partial send — and it is also how you recover, since the diff records what was
taken out.
Other fields are a partial update: omitted ones are left alone. mcp_server_id
is immutable — rules reference server-specific tool actions, so retargeting is a
new policy, not an edit.
PATCH
/
api
/
policy
/
v2
/
policies
/
{policy_id}
Update Policy
curl --request PATCH \
--url https://{host}/api/policy/v2/policies/{policy_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"name": "<string>",
"description": "<string>",
"support_contact": "<string>",
"tags": [
"<string>"
],
"application_ids": [
"<string>"
],
"rules": [
{
"actions": [
"tools/call:create_issue"
],
"name": "Engineering read access",
"description": "<string>",
"authorized": false,
"active": true,
"roles_groups": [
"*"
],
"condition": {
"match": {
"expr": "P.attr.department == 'Engineering'"
}
}
}
]
}
EOFimport requests
url = "https://{host}/api/policy/v2/policies/{policy_id}"
payload = {
"name": "<string>",
"description": "<string>",
"support_contact": "<string>",
"tags": ["<string>"],
"application_ids": ["<string>"],
"rules": [
{
"actions": ["tools/call:create_issue"],
"name": "Engineering read access",
"description": "<string>",
"authorized": False,
"active": True,
"roles_groups": ["*"],
"condition": { "match": { "expr": "P.attr.department == 'Engineering'" } }
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
support_contact: '<string>',
tags: ['<string>'],
application_ids: ['<string>'],
rules: [
{
actions: ['tools/call:create_issue'],
name: 'Engineering read access',
description: '<string>',
authorized: false,
active: true,
roles_groups: ['*'],
condition: {match: {expr: 'P.attr.department == \'Engineering\''}}
}
]
})
};
fetch('https://{host}/api/policy/v2/policies/{policy_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{host}/api/policy/v2/policies/{policy_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'support_contact' => '<string>',
'tags' => [
'<string>'
],
'application_ids' => [
'<string>'
],
'rules' => [
[
'actions' => [
'tools/call:create_issue'
],
'name' => 'Engineering read access',
'description' => '<string>',
'authorized' => false,
'active' => true,
'roles_groups' => [
'*'
],
'condition' => [
'match' => [
'expr' => 'P.attr.department == \'Engineering\''
]
]
]
]
]),
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 := "https://{host}/api/policy/v2/policies/{policy_id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://{host}/api/policy/v2/policies/{policy_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{host}/api/policy/v2/policies/{policy_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"support_contact\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"application_ids\": [\n \"<string>\"\n ],\n \"rules\": [\n {\n \"actions\": [\n \"tools/call:create_issue\"\n ],\n \"name\": \"Engineering read access\",\n \"description\": \"<string>\",\n \"authorized\": false,\n \"active\": true,\n \"roles_groups\": [\n \"*\"\n ],\n \"condition\": {\n \"match\": {\n \"expr\": \"P.attr.department == 'Engineering'\"\n }\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"policy": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organization_id": "<string>",
"name": "<string>",
"status": "<string>",
"mcp_server_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"created_by_user_id": "<string>",
"updated_by_user_id": "<string>",
"support_contact": "<string>",
"description": "<string>",
"application_ids": [
"<string>"
],
"tags": [
"<string>"
],
"rules": [
{
"actions": [
"tools/call:create_issue"
],
"name": "Engineering read access",
"description": "<string>",
"authorized": false,
"active": true,
"roles_groups": [
"*"
],
"condition": {
"match": {
"expr": "P.attr.department == 'Engineering'"
}
}
}
]
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
ApiKeyOAuth2
A Barndoor API key, sent as Authorization: Bearer <key>. Keys are prefixed bdai_ and are opaque — do not attempt to decode one. Interchangeable with an OAuth 2.0 access token.
Path Parameters
Body
application/json
Request body for partial updates to an existing policy.
Human-friendly policy name, unique within an organization
Longer description of the policy.
Primary point of contact associated with the policy.
Tags for categorizing the policy.
The current lifecycle status of the policy.
Available options:
DRAFT, ACTIVE, INACTIVE, ARCHIVED AI agents this policy applies to, as application UUIDs. An empty or omitted list means the policy applies to ALL agents — it must never contain an empty string. Retrieve real ids from GET /api/registry/v1/agents.
Full set of rules that govern the policy. This REPLACES the existing rule list on update — send the complete set, not a delta. Anything no rule grants is denied. Write ONE rule per distinct roles_groups set: put every action for a principal on a single rule and let the :approve suffix carry allow-vs-confirm, rather than splitting reads and writes across two rules naming the same principal.
Show child attributes
Show child attributes
Response
Successful Response
Envelope for detail responses.
Detailed representation of a policy including rules.
Show child attributes
Show child attributes