From 1f10cf8ef9c10dec81e002e1955d60ac53189e1e Mon Sep 17 00:00:00 2001 From: Andrew Gwozdziewycz Date: Fri, 11 Sep 2026 09:54:48 -0700 Subject: [PATCH] docs: document Cedar policy support in AI Governance API Re-vendor the AI Governance OpenAPI spec to reflect Cedar:V1 policy support (CedarV1Policy schema, cedar_v1 fields on Policy/Create/Update requests) and cursor-based pagination on ListPolicies. --- content/reference/api/ai-governance/api.yaml | 97 ++++++++++++++++++-- 1 file changed, 87 insertions(+), 10 deletions(-) diff --git a/content/reference/api/ai-governance/api.yaml b/content/reference/api/ai-governance/api.yaml index e552b2d7b6c9..66fa9bb9c0ac 100644 --- a/content/reference/api/ai-governance/api.yaml +++ b/content/reference/api/ai-governance/api.yaml @@ -52,21 +52,54 @@ paths: tags: [policies] summary: List policies description: > - Returns a shallow summary of all policies for the org. + Returns a shallow summary of the org's policies, one page at a time. The rule set is not included; use GetPolicy to fetch the full object. + + + Results are paginated with an opaque cursor. Pass `page_size` to bound + the page; if more policies remain, the response includes a + `next_page_token` to pass as `page_token` on the next request. Iterate + until `next_page_token` is absent. Treat the token as opaque — do not + parse or construct it. + parameters: + - name: page_size + in: query + required: false + description: > + Maximum number of policies to return. Defaults to 100 if omitted or + zero; values above 100 are capped at 100. + schema: + type: integer + format: int32 + minimum: 0 + maximum: 100 + default: 100 + - name: page_token + in: query + required: false + description: > + Opaque cursor from a previous response's `next_page_token`. Omit to + fetch the first page. + schema: + type: string responses: "200": - description: Object wrapping an array of policy summaries under `data`. Rule sets are not included; use GetPolicy to fetch a full policy. + description: Object wrapping an array of policy summaries under `data`, with an optional `next_page_token`. Rule sets are not included; use GetPolicy to fetch a full policy. content: application/json: schema: type: object - required: [data] + required: [data, next_page_token] properties: data: type: array items: $ref: "#/components/schemas/PolicySummary" + next_page_token: + type: [string, "null"] + description: > + The opaque cursor for the next page, or `null` on the last page. + example: AQpteyJQSyI6Im15LW9yZyIsIlNLIjoicG9saWN5I3BvbF8ifQ examples: default: value: @@ -79,6 +112,9 @@ paths: created_at: "2026-04-22T00:00:00Z" updated_at: "2026-04-22T00:00:00Z" type: allowlist_v0 + next_page_token: AQpteyJQSyI6Im15LW9yZyIsIlNLIjoicG9saWN5I3BvbF8ifQ + "400": + $ref: "#/components/responses/InvalidArgument" "401": $ref: "#/components/responses/Unauthenticated" "403": @@ -581,14 +617,17 @@ components: type: type: string description: > - Identifies the rule-set format. Always `allowlist_v0`, corresponding - to the `allowlist_v0` property on the full Policy object. + Identifies the policy type. `allowlist_v0` for network/filesystem + allowlist policies; `cedar_v1` for Cedar language policies. + enum: [allowlist_v0, cedar_v1] examples: - allowlist_v0 Policy: type: object - description: Full policy representation including the allowlist rule set. + description: > + Full policy representation. Exactly one of `allowlist_v0` or `cedar_v1` + is present, depending on the policy type. required: [id, name, org, scope, created_at, updated_at] properties: id: @@ -618,6 +657,8 @@ components: - "2026-04-22T00:00:00Z" allowlist_v0: $ref: "#/components/schemas/AllowlistV0" + cedar_v1: + $ref: "#/components/schemas/CedarV1Policy" Scope: type: object @@ -656,6 +697,33 @@ components: items: $ref: "#/components/schemas/Rule" + CedarV1Policy: + type: object + description: > + Cedar:V1 policy body. Present on `Policy` when `PolicySummary.type` is + `cedar_v1`. Cedar policies encode their rules directly in `text` rather + than in the rules sub-resource; the rules endpoints are not available for + Cedar policies. + required: [text, schema_url] + properties: + text: + type: string + description: > + One or more Cedar `permit` or `forbid` statements. Must be + syntactically valid Cedar and must not carry an `@id` annotation + (IDs are server-assigned). + examples: + - 'permit(principal, action == MCP::Action::"call_tool", resource is MCP::Tool);' + schema_url: + type: string + description: > + URL of the Cedar schema this policy was authored against. The + evaluator looks up the schema by this URL from its built-in + registry. Use `https://schemas.docker.com/policy/cedar/v1/mcp/v0` + for MCP policies. + examples: + - "https://schemas.docker.com/policy/cedar/v1/mcp/v0" + Rule: type: object description: A single allow or deny rule within an allowlist policy. @@ -679,7 +747,11 @@ components: CreatePolicyRequest: type: object - description: Fields required to create a new policy. + description: > + Fields required to create a new policy. Omitting `cedar_v1` creates an + `allowlist_v0` policy with an empty rule set. Supplying `cedar_v1` creates + a Cedar:V1 policy; rules are embedded in the Cedar text rather than managed + via the rules sub-resource. required: [name] properties: name: @@ -689,6 +761,8 @@ components: - "Security Research — hardened" scope: $ref: "#/components/schemas/Scope" + cedar_v1: + $ref: "#/components/schemas/CedarV1Policy" CreateRuleRequest: type: object @@ -744,9 +818,10 @@ components: UpdatePolicyRequest: type: object description: > - Partial update of a policy's metadata. Only fields present in the body - are updated; the rule set is not modified here. At least one field must - be present. + Partial update of a policy. Only fields present in the body are updated; + absent fields are left unchanged. At least one field must be present. + For `cedar_v1` policies, supply `cedar_v1` to replace the policy text; + `name` and `scope` may be combined freely. properties: name: type: string @@ -756,6 +831,8 @@ components: - Security Research scope: $ref: "#/components/schemas/ScopePatch" + cedar_v1: + $ref: "#/components/schemas/CedarV1Policy" ScopePatch: type: object