> ## Documentation Index > Fetch the complete documentation index at: https://docs.chainloop.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get a policy by name > Retrieves a policy by its name, optionally specifying a particular version by digest. If no digest is provided, the latest version is returned. ## OpenAPI ````yaml https://api.app.chainloop.dev/openapi.yaml get /v1/policies/{policy_name} openapi: 3.0.1 info: contact: email: support@chainloop.dev name: Chainloop Support url: https://chainloop.dev termsOfService: https://chainloop.dev/terms title: Chainloop Platform API version: '1.0' servers: - url: https://api.app.chainloop.dev/ security: - bearerToken: [] tags: - description: AI-powered agent operations name: AgentsService - name: ArtifactService - name: AssessmentService - description: Service for polling the status of asynchronous operations name: AsyncOperationsService - name: AttestationsService - name: PolicyService - name: ComplianceService - name: ComponentService - name: EnvironmentsService - name: EvidenceService - name: FindingService - name: LogicalEnvironmentsService - name: ProductsService - name: ProjectsService - name: UserService externalDocs: description: Chainloop Official Documentation url: https://docs.chainloop.dev paths: /v1/policies/{policy_name}: get: tags: - PolicyService summary: Get a policy by name description: >- Retrieves a policy by its name, optionally specifying a particular version by digest. If no digest is provided, the latest version is returned. operationId: PolicyService_Get parameters: - description: The name of the policy to retrieve in: path name: policy_name required: true schema: type: string - description: >- if set, it will return the policy with the given digest otherwise it will return the latest version If set, returns the policy with the given digest; otherwise returns the latest version in: query name: digest schema: type: string - description: |- Organization owning this policy (empty for best effort fallback) Organization owning this policy (empty for best effort fallback) in: query name: organization_name schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/v1PolicyServiceGetResponse' description: A successful response. '400': content: application/json: schema: $ref: '#/components/schemas/v1BadRequestResponse' description: Bad Request - The request was invalid or cannot be served. '401': content: application/json: schema: $ref: '#/components/schemas/v1UnauthorizedResponse' description: Unauthorized - Authentication is required. '403': content: application/json: schema: $ref: '#/components/schemas/v1PermissionDeniedResponse' description: Forbidden - You do not have permission to access this resource. '500': content: application/json: schema: $ref: '#/components/schemas/v1InternalServerErrorResponse' description: Internal Server Error - An unexpected error occurred on the server. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. components: schemas: v1PolicyServiceGetResponse: description: Response containing a policy and its metadata example: version_references: - digest: digest created_at: '2000-01-23T04:56:07.000Z' - digest: digest created_at: '2000-01-23T04:56:07.000Z' inputs_json_schema: inputs_json_schema data: metadata: organization: organization name: name description: description annotations: key: annotations display_name: display_name finding_type: finding_type kind: kind api_version: api_version spec: path: path auto_match: path: path ref: ref embedded: embedded inputs: - default: default name: name description: description required: true - default: default name: name description: description required: true policies: - path: path ref: ref kind: kind attestation_phases: - ATTESTATION_PHASE_UNSPECIFIED - ATTESTATION_PHASE_UNSPECIFIED embedded: embedded - path: path ref: ref kind: kind attestation_phases: - ATTESTATION_PHASE_UNSPECIFIED - ATTESTATION_PHASE_UNSPECIFIED embedded: embedded type: type embedded: embedded builtin: true organization_id: organization_id digest: digest raw: format: FORMAT_UNSPECIFIED body: body organization_name: organization_name policy: metadata: organization: organization name: name description: description annotations: key: annotations display_name: display_name finding_type: finding_type kind: kind api_version: api_version spec: path: path auto_match: path: path ref: ref embedded: embedded inputs: - default: default name: name description: description required: true - default: default name: name description: description required: true policies: - path: path ref: ref kind: kind attestation_phases: - ATTESTATION_PHASE_UNSPECIFIED - ATTESTATION_PHASE_UNSPECIFIED embedded: embedded - path: path ref: ref kind: kind attestation_phases: - ATTESTATION_PHASE_UNSPECIFIED - ATTESTATION_PHASE_UNSPECIFIED embedded: embedded type: type embedded: embedded latest: true properties: data: $ref: '#/components/schemas/v1Policy' policy: $ref: '#/components/schemas/v1Policy' digest: description: The digest of the policy type: string raw: $ref: '#/components/schemas/v1RawBody' latest: description: Whether this is the latest version of the policy type: boolean builtin: description: Whether this policy is builtin or custom title: Whether this policy is builtin or custom type: boolean organization_id: description: >- ID of the organization owning this policy (empty for builtin policies) title: Organization owning this policy (empty for builtin policies) type: string organization_name: description: Name of the organization owning this policy type: string version_references: description: References to all versions of this policy items: $ref: '#/components/schemas/v1PolicyVersionReference' title: All references to the policy versions type: array inputs_json_schema: description: JSON schema of the inputs required by the policy title: The JSON schema version of the inputs of the policy type: string title: PolicyServiceGetResponse type: object v1BadRequestResponse: description: Response for bad request example: code: 0 details: - details - details message: message properties: code: default: 3 description: >- The error code indicating the type of error. It's fixed to 3, which is the code for INVALID_ARGUMENT. format: int32 type: integer message: description: A human-readable message providing more details about the error. type: string details: description: Additional details about the error. items: type: string type: array required: - code - message title: BadRequestResponse type: object v1UnauthorizedResponse: description: Response for unauthorized access example: code: 6 details: - details - details message: message properties: code: default: 16 description: >- The error code indicating the type of error. It's fixed to 16, which is the code for UNAUTHENTICATED. format: int32 type: integer message: description: A human-readable message providing more details about the error. type: string details: description: Additional details about the error. items: type: string type: array required: - code - message title: UnauthorizedResponse type: object v1PermissionDeniedResponse: description: Response for permission denied example: code: 1 details: - details - details message: message properties: code: default: 7 description: >- The error code indicating the type of error. It's fixed to 7, which is the code for PERMISSION_DENIED. format: int32 type: integer message: description: A human-readable message providing more details about the error. type: string details: description: Additional details about the error. items: type: string type: array required: - code - message title: PermissionDeniedResponse type: object v1InternalServerErrorResponse: description: Response for internal server error example: code: 5 details: - details - details message: message properties: code: default: 13 description: >- The error code indicating the type of error. It's fixed to 13, which is the code for INTERNAL_ERROR. format: int32 type: integer message: description: A human-readable message providing more details about the error. type: string details: description: Additional details about the error. items: type: string type: array required: - code - message title: InternalServerErrorResponse type: object rpcStatus: example: code: 5 details: - '@type': '@type' - '@type': '@type' message: message properties: code: format: int32 type: integer message: type: string details: items: $ref: '#/components/schemas/protobufAny' type: array type: object v1Policy: description: >- A policy that can be applied to materials in Chainloop to validate compliance with specific requirements example: metadata: organization: organization name: name description: description annotations: key: annotations display_name: display_name finding_type: finding_type kind: kind api_version: api_version spec: path: path auto_match: path: path ref: ref embedded: embedded inputs: - default: default name: name description: description required: true - default: default name: name description: description required: true policies: - path: path ref: ref kind: kind attestation_phases: - ATTESTATION_PHASE_UNSPECIFIED - ATTESTATION_PHASE_UNSPECIFIED embedded: embedded - path: path ref: ref kind: kind attestation_phases: - ATTESTATION_PHASE_UNSPECIFIED - ATTESTATION_PHASE_UNSPECIFIED embedded: embedded type: type embedded: embedded properties: api_version: description: API version for the policy title: API version for the policy type: string kind: description: Kind of resource, must be Policy title: Kind of resource, must be "Policy" type: string metadata: $ref: '#/components/schemas/v1Metadata' spec: $ref: '#/components/schemas/v1PolicySpec' title: Policy type: object v1RawBody: example: format: FORMAT_UNSPECIFIED body: body properties: body: format: byte pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ type: string format: $ref: '#/components/schemas/RawBodyRawBodyFormat' title: Raw representation in bytes of a resource in json, yaml or cue type: object v1PolicyVersionReference: example: digest: digest created_at: '2000-01-23T04:56:07.000Z' properties: digest: title: The digest of the policy type: string created_at: format: date-time title: The timestamp when the policy was created type: string title: PolicyVersionReference represents the reference to a policy version type: object protobufAny: additionalProperties: type: object example: '@type': '@type' properties: '@type': type: string type: object v1Metadata: description: >- DUPLICATED from chainloop-dev/chainloop: app/controlplane/api/workflowcontract/v1/crafting_schema.proto Keep in sync with the upstream source. Note: field numbers 6-7 diverge from upstream (which has organization=6, finding_type=7). The platform added display_name=6, so organization shifted to 7 and finding_type to 8. example: organization: organization name: name description: description annotations: key: annotations display_name: display_name finding_type: finding_type properties: name: title: the name of the policy type: string display_name: title: optional display name (platform-only, not present in upstream) type: string description: type: string annotations: additionalProperties: type: string type: object organization: type: string finding_type: description: >- Declares the structured output schema for policy violations. Upstream field number is 7, but shifted to 8 here due to display_name occupying field 6. type: string type: object v1PolicySpec: description: >- Specification of a policy, defining its behavior and applicable material types example: path: path auto_match: path: path ref: ref embedded: embedded inputs: - default: default name: name description: description required: true - default: default name: name description: description required: true policies: - path: path ref: ref kind: kind attestation_phases: - ATTESTATION_PHASE_UNSPECIFIED - ATTESTATION_PHASE_UNSPECIFIED embedded: embedded - path: path ref: ref kind: kind attestation_phases: - ATTESTATION_PHASE_UNSPECIFIED - ATTESTATION_PHASE_UNSPECIFIED embedded: embedded type: type embedded: embedded properties: path: description: Path to a policy script (deprecated) title: Path to a policy script. It might consist of a URI reference type: string embedded: description: Embedded source code for the policy (deprecated) title: Embedded source code (only Rego supported currently) type: string type: description: The material type this policy applies to type: string policies: description: List of policy specifications items: $ref: '#/components/schemas/v1PolicySpecV2' title: List of policy specifications for this policy type: array inputs: description: Input parameters for this policy items: $ref: '#/components/schemas/v1PolicyInput' title: Input parameters required or optional for this policy type: array auto_match: $ref: '#/components/schemas/v1AutoMatch' title: PolicySpec type: object RawBodyRawBodyFormat: default: FORMAT_UNSPECIFIED enum: - FORMAT_UNSPECIFIED - FORMAT_JSON - FORMAT_YAML - FORMAT_CUE title: |- buf:lint:ignore ENUM_VALUE_PREFIX buf:lint:ignore ENUM_ZERO_VALUE_SUFFIX type: string v1PolicySpecV2: description: >- Version 2 of policy specification, defining the policy source and applicable material kind example: path: path ref: ref kind: kind attestation_phases: - ATTESTATION_PHASE_UNSPECIFIED - ATTESTATION_PHASE_UNSPECIFIED embedded: embedded properties: path: description: Path to a policy script (deprecated, use ref instead) title: >- Path to a policy script, might be a URI reference to an external script Deprecated: use ref instead type: string embedded: description: >- Embedded source code for the policy (only Rego is currently supported) title: >- Embedded source code for the policy (only Rego language is currently supported) type: string ref: description: Generic reference for file:// and http(s):// schemes title: Generic reference for file:// and http(s):// schemes type: string kind: description: The material type this policy applies to title: |- The material type this policy applies to Cannot be ARTIFACT type: string attestation_phases: description: >- Controls at which attestation phases this policy is evaluated. Empty means all phases. items: $ref: '#/components/schemas/v1AttestationPhase' type: array title: PolicySpecV2 type: object v1PolicyInput: description: >- Defines an input parameter that can be passed to a policy during evaluation example: default: default name: name description: description required: true properties: name: description: Name of the input parameter title: >- Name of the input parameter, must contain only letters, numbers, and underscores type: string description: description: Human-readable description of this input parameter title: Human-readable description of the input parameter type: string required: description: Whether this input parameter is required title: Whether this input parameter is required type: boolean default: description: Default value for this input parameter if not provided title: Default value for this input parameter if not provided type: string title: PolicyInput type: object v1AutoMatch: description: Auto-matching policy script example: path: path ref: ref embedded: embedded properties: path: description: Path to an auto-matching policy script (deprecated, use ref instead) title: >- Path to a policy script, might be a URI reference to an external script Deprecated: use ref instead type: string embedded: description: >- Embedded source code for the auto-matching policy (only Rego is currently supported) title: >- Embedded source code for the auto-matching policy (only Rego language is currently supported) type: string ref: description: Generic reference for file:// and http(s):// schemes title: Generic reference for file:// and http(s):// schemes type: string title: AutoMatch type: object v1AttestationPhase: default: ATTESTATION_PHASE_UNSPECIFIED description: >- DUPLICATED from chainloop-dev/chainloop: app/controlplane/api/workflowcontract/v1/crafting_schema.proto Keep in sync with the upstream source. Lifecycle phases that control when an attestation policy is evaluated. Only applicable to policies with kind ATTESTATION in PolicySpecV2. enum: - ATTESTATION_PHASE_UNSPECIFIED - INIT - PUSH type: string securitySchemes: bearerToken: description: Bearer token for authentication type: http scheme: bearer bearerFormat: JWT ````