---
updatedAt: 2026-10-15T16:03:46.000Z
agentTools:
  siteIndex: https://developer.jamf.com/llms.txt
  projectIndex: https://developer.jamf.com/platform-api/llms.txt
---

# Preview - List all versions for a policy

**Preview:** _This endpoint is currently in a preview state and is subject to breaking changes without warning._

**Preview endpoint.** Expected to reach general availability by 2027-03-03,
pending feedback on request and response shape.

Returns a paginated list of all published versions for the specified policy.


**Required Permissions:** `ai-policies:read`

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "AI Governance Policies API",
    "version": "1.0.0",
    "description": "API for managing AI governance policies\n\n**Preview:** Every endpoint in this API is in preview. All are expected to graduate\nto general availability within 6 months (by 2027-03-03), pending feedback on\nrequest/response shape. Every successful (2xx) response carries a\n`Jamf-Preview: true` header.",
    "termsOfService": "https://www.jamf.com/developer-resources/api-license-agreement/",
    "contact": {
      "name": "Jamf Developer",
      "url": "https://developer.jamf.com"
    }
  },
  "x-preview": true,
  "servers": [
    {
      "url": "https://{region}.api.jamfcloud.com/ai/governance/policies",
      "description": "Jamf Beta API Gateway - prod",
      "variables": {
        "region": {
          "default": "us",
          "enum": [
            "us",
            "eu",
            "apac"
          ],
          "description": "Geographic deployment region"
        }
      }
    }
  ],
  "security": [
    {
      "oauth2": []
    }
  ],
  "tags": [
    {
      "name": "policies",
      "description": "AI governance policy CRUD with draft/publish versioning. The Policy document\nholds mutable draft settings (updated via PATCH). Publishing snapshots the draft\ninto an immutable PolicyVersion. Delete is a soft archive.\n"
    }
  ],
  "paths": {
    "/v1/policies/{policyId}/versions": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PolicyId"
        }
      ],
      "get": {
        "operationId": "listPolicyVersions",
        "tags": [
          "policies"
        ],
        "summary": "Preview - List all versions for a policy",
        "description": "**Preview:** _This endpoint is currently in a preview state and is subject to breaking changes without warning._\n\n**Preview endpoint.** Expected to reach general availability by 2027-03-03,\npending feedback on request and response shape.\n\nReturns a paginated list of all published versions for the specified policy.\n\n\n**Required Permissions:** `ai-policies:read`",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Environment-Id"
          },
          {
            "$ref": "#/components/parameters/PageParam"
          },
          {
            "$ref": "#/components/parameters/PageSizeParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of policy versions",
            "headers": {
              "Jamf-Preview": {
                "$ref": "#/components/headers/JamfPreview"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyVersionListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "oauth2": [
              "ai-policies:read"
            ]
          }
        ],
        "x-required-privileges": [
          "ai-policies:read"
        ],
        "x-preview": true
      }
    }
  },
  "components": {
    "headers": {
      "JamfPreview": {
        "description": "Present on every successful (2xx) response from a preview endpoint. See\nthe API description for preview status and expected graduation.\n",
        "schema": {
          "type": "boolean",
          "enum": [
            true
          ]
        }
      }
    },
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "Obtain an access token by calling the API Gateway's token endpoint using the OAuth2 client-credentials flow.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://{region}.api.jamfcloud.com/auth/token",
            "scopes": {
              "ai-policies:create": "",
              "ai-policies:delete": "",
              "ai-policies:read": "",
              "ai-policies:update": ""
            }
          }
        }
      }
    },
    "parameters": {
      "PolicyId": {
        "name": "policyId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Policy ID"
      },
      "PageParam": {
        "name": "page",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 0,
          "minimum": 0
        },
        "description": "0-based page number"
      },
      "PageSizeParam": {
        "name": "page-size",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 100,
          "minimum": 1,
          "maximum": 500
        },
        "description": "Maximum number of results to return per page"
      },
      "X-Environment-Id": {
        "name": "X-Environment-Id",
        "in": "header",
        "required": true,
        "description": "The environment UUID identifier.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
          "example": "e77c1408-10c8-4007-b177-abc9157fbcaa"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid authentication",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Insufficient permissions",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "schemas": {
      "ApiError": {
        "type": "object",
        "description": "Standard error response envelope returned for all non-2xx status codes.",
        "required": [
          "httpStatus",
          "traceId",
          "errors"
        ],
        "properties": {
          "httpStatus": {
            "type": "integer",
            "format": "int32",
            "minimum": 400,
            "maximum": 599,
            "description": "HTTP status of the response",
            "example": 404
          },
          "traceId": {
            "type": "string",
            "description": "Trace ID for request correlation",
            "example": "abc123def456"
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiErrorItem"
            }
          }
        }
      },
      "ApiErrorItem": {
        "type": "object",
        "description": "A single error detail within an ApiError response.",
        "required": [
          "code",
          "description"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code (e.g. TOOL_ID_UNKNOWN, SCHEMA_VALIDATION_FAILED, POLICY_NOT_FOUND)",
            "example": "POLICY_NOT_FOUND"
          },
          "field": {
            "type": "string",
            "description": "Dot-path to the offending field (for validation errors)",
            "example": "settings.enabled"
          },
          "description": {
            "type": "string",
            "example": "The requested policy does not exist"
          }
        }
      },
      "VendorSettings": {
        "type": "object",
        "description": "Vendor tool settings payload. Shape is tool-specific and defined by the vendor's\nJSON Schema, which is served by GET /v1/tools/{toolId}/schemas/{schemaVersion}\n(see the ToolSchemaResponse schema). Only keys the admin explicitly set are\npresent. Validated at write time against the vendor schema for the request's\nschemaVersion.\n",
        "additionalProperties": true
      },
      "PolicyVersion": {
        "type": "object",
        "description": "An immutable published snapshot of a policy's settings at a point in time.",
        "required": [
          "id",
          "policyId",
          "versionNumber",
          "toolId",
          "schemaVersion",
          "settings",
          "createdAt",
          "createdBy"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "660e8400-e29b-41d4-a716-446655440001"
          },
          "policyId": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "versionNumber": {
            "type": "integer",
            "example": 3
          },
          "toolId": {
            "type": "string",
            "example": "com.anthropic.claudecode"
          },
          "schemaVersion": {
            "type": "string",
            "example": "2026-05-12"
          },
          "settings": {
            "$ref": "#/components/schemas/VendorSettings"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-15T09:30:00Z"
          },
          "createdBy": {
            "type": "string",
            "description": "Actor ID",
            "example": "auth0|user123"
          }
        }
      },
      "PolicyVersionListResponse": {
        "type": "object",
        "description": "Paginated list of published policy versions.",
        "required": [
          "totalCount",
          "results"
        ],
        "properties": {
          "totalCount": {
            "type": "integer",
            "example": 5
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PolicyVersion"
            }
          }
        }
      }
    }
  },
  "x-scope-types": [
    "environment"
  ]
}
```