Policies

Overview

The Confident AI SDK exposes every Policy method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

List Policies

Lists the custom access policies this project owns. Each is a named set of project permissions, returned with every permission it grants as a resource:action pair such as promptBranch:merge. These are what you attach to this project's roles; the global, system-defined roles do not draw their permissions from policies, so nothing here applies to them. A project's policies are separate from your organization's.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.list_policies()

For async mode, call a_list_policies and await it as shown below:

result = await project.a_list_policies(...)

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.listPolicies();

Returns

This method returns an object of type PolicyList.

Create Policy

Creates a custom policy in this project from a set of permissions and returns it. A policy on its own grants nobody anything: it takes effect only once it is attached to a project role, and then applies to every member holding that role.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.create_policy(
    name="Billing read-only",
    permission_ids=["<PERMISSION-ID>"],
    description="Lets a role read invoices and model costs, but change neither.",
)

For async mode, call a_create_policy and await it as shown below:

result = await project.a_create_policy(...)

Parameters

Parameter	Type	Description
`name`	`str`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permission_ids`	`List[str]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`Optional[str]`	What the policy is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.createPolicy(
  "Billing read-only",
  ["<PERMISSION-ID>"],
  {
    description: "Lets a role read invoices and model costs, but change neither."
  },
);

Parameters

Parameter	Type	Description
`name`	`string`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permissionIds`	`string[]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`string \| null`	What the policy is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

Returns

This method returns an object of type Policy.

Update Policy

Replaces a project policy's name, description, and granted permissions. The change reaches people through the roles the policy is attached to, and it reaches them immediately: every member holding any of those roles gains or loses the affected permissions on their next call.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.update_policy(
    policy_id="<POLICY-ID>",
    name="Billing read-only",
    permission_ids=["<PERMISSION-ID>"],
    description="Lets a role read invoices and model costs, but change neither.",
)

For async mode, call a_update_policy and await it as shown below:

result = await project.a_update_policy(...)

Parameters

Parameter	Type	Description
`policy_id`	`str`	Required. The id of the project policy.
`name`	`str`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permission_ids`	`List[str]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`Optional[str]`	What the policy is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.updatePolicy(
  "<POLICY-ID>",
  "Billing read-only",
  ["<PERMISSION-ID>"],
  {
    description: "Lets a role read invoices and model costs, but change neither."
  },
);

Parameters

Parameter	Type	Description
`policyId`	`string`	Required. The id of the project policy.
`name`	`string`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permissionIds`	`string[]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`string \| null`	What the policy is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

Returns

This method returns an object of type Policy.

Delete Policy

Permanently deletes a project policy. Unlike a role, a policy in use is not protected: it is detached from every project role holding it, and members of those roles lose the permissions it granted on their next request. The permissions themselves survive, as do the roles — though a role left with no policies can do nothing in the project. List the project's roles first to see which carry this policy.

from confident_ai import ConfidentAI

client = ConfidentAI()

project = client.project(project_id="<PROJECT-ID>")
result = project.delete_policy(policy_id="<POLICY-ID>")

For async mode, call a_delete_policy and await it as shown below:

result = await project.a_delete_policy(...)

Parameters

Parameter	Type	Description
`policy_id`	`str`	Required. The id of the project policy.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const project = client.project("<PROJECT-ID>");
const result = await project.deletePolicy("<POLICY-ID>");

Parameters

Parameter	Type	Description
`policyId`	`string`	Required. The id of the project policy.

Returns

This method returns an object of type PolicyRef.

Methods (Stateless)

These methods take every argument themselves, so a caller reaches them through client.projects without opening a Project first.

List Policies

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.list_policies(project_id="<PROJECT-ID>")

For async mode, call a_list_policies and await it as shown below:

result = await client.projects.a_list_policies(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project, which must belong to your organization.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.listPolicies("<PROJECT-ID>");

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project, which must belong to your organization.

Returns

This method returns an object of type PolicyList.

Create Policy

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.create_policy(
    project_id="<PROJECT-ID>",
    name="Billing read-only",
    permission_ids=["<PERMISSION-ID>"],
    description="Lets a role read invoices and model costs, but change neither.",
)

For async mode, call a_create_policy and await it as shown below:

result = await client.projects.a_create_policy(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project, which must belong to your organization.
`name`	`str`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permission_ids`	`List[str]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`Optional[str]`	What the policy is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.createPolicy(
  "<PROJECT-ID>",
  "Billing read-only",
  ["<PERMISSION-ID>"],
  {
    description: "Lets a role read invoices and model costs, but change neither."
  },
);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project, which must belong to your organization.
`name`	`string`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permissionIds`	`string[]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`string \| null`	What the policy is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

Returns

This method returns an object of type Policy.

Update Policy

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.update_policy(
    project_id="<PROJECT-ID>",
    policy_id="<POLICY-ID>",
    name="Billing read-only",
    permission_ids=["<PERMISSION-ID>"],
    description="Lets a role read invoices and model costs, but change neither.",
)

For async mode, call a_update_policy and await it as shown below:

result = await client.projects.a_update_policy(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the policy belongs to.
`policy_id`	`str`	Required. The id of the project policy.
`name`	`str`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permission_ids`	`List[str]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`Optional[str]`	What the policy is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.updatePolicy(
  "<PROJECT-ID>",
  "<POLICY-ID>",
  "Billing read-only",
  ["<PERMISSION-ID>"],
  {
    description: "Lets a role read invoices and model costs, but change neither."
  },
);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the policy belongs to.
`policyId`	`string`	Required. The id of the project policy.
`name`	`string`	Required. The name of the policy, unique within the organization or project that owns it. It is what identifies the policy when attaching it to a role.
`permissionIds`	`string[]`	Required. The ids of the permissions this policy grants. This is the policy's complete permission set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the policy granting nothing. Discover assignable ids with the permissions endpoint of the same scope; an id from the other scope's catalog is stored but never matches a permission check here.
`description`	`string \| null`	What the policy is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.

Returns

This method returns an object of type Policy.

Delete Policy

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.projects.delete_policy(
    project_id="<PROJECT-ID>",
    policy_id="<POLICY-ID>",
)

For async mode, call a_delete_policy and await it as shown below:

result = await client.projects.a_delete_policy(...)

Parameters

Parameter	Type	Description
`project_id`	`str`	Required. The id of the project the policy belongs to.
`policy_id`	`str`	Required. The id of the project policy.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.projects.deletePolicy(
  "<PROJECT-ID>",
  "<POLICY-ID>",
);

Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The id of the project the policy belongs to.
`policyId`	`string`	Required. The id of the project policy.

Returns

This method returns an object of type PolicyRef.

Types

Policy

A named set of permissions owned by an organization or by a project. A policy is attached to roles of the same scope, never to a member directly, so it only grants anything once a role that holds it is assigned to someone.

class Policy:
    id: str
    name: str
    description: Optional[str]
    permissions: List[PolicyPermission]

idstrRequired

The id of the policy, generated by Confident AI.

Example: "<POLICY-ID>"

namestrRequired

The name of the policy.

Example: "Billing read-only"

descriptionOptional[str]Required

What the policy is for, or null when it has no description.

Example: "Lets a role read invoices and model costs, but change neither."

permissionsList[PolicyPermission]Required

The permissions this policy grants.

See PolicyPermission.

interface Policy {
  id: string;
  name: string;
  description: string | null;
  permissions: PolicyPermission[];
}

idstringRequired

The id of the policy, generated by Confident AI.

Example: "<POLICY-ID>"

namestringRequired

The name of the policy.

Example: "Billing read-only"

descriptionstring | nullRequired

What the policy is for, or null when it has no description.

Example: "Lets a role read invoices and model costs, but change neither."

permissionsPolicyPermission[]Required

The permissions this policy grants.

See PolicyPermission.

PolicyList

The policies available to attach to the roles of the same organization or project.

class PolicyList:
    policies: List[Policy]

policiesList[Policy]Required

The custom policies the organization or project owns.

See Policy.

interface PolicyList {
  policies: Policy[];
}

policiesPolicy[]Required

The custom policies the organization or project owns.

See Policy.

PolicyPermission

A permission granted by a policy. Its name is a resource:action pair such as billing:read or dataset:read; the permissions endpoint of the same scope (GET /v2/organization/permissions or GET /v2/projects/{projectId}/permissions) lists every pair a policy there can grant.

class PolicyPermission:
    id: str
    name: str

idstrRequired

The id of the permission, generated by Confident AI.

Example: "<PERMISSION-ID>"

namestrRequired

The permission, written as resource:action — the resource it applies to, then what it allows on it.

Example: "billing:read"

interface PolicyPermission {
  id: string;
  name: string;
}

idstringRequired

The id of the permission, generated by Confident AI.

Example: "<PERMISSION-ID>"

namestringRequired

The permission, written as resource:action — the resource it applies to, then what it allows on it.

Example: "billing:read"

PolicyRef

Confirmation that the policy no longer exists.

class PolicyRef:
    id: str

idstrRequired

The id of the policy that was deleted.

Example: "<POLICY-ID>"

interface PolicyRef {
  id: string;
}

idstringRequired

The id of the policy that was deleted.

Example: "<POLICY-ID>"

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on September 30, 2026

Built byConfident AI