> ## Documentation Index > Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt > Use this file to discover all available pages before exploring further. # Read one policy > The authoritative answer to "does this policy exist, and is it here?". A client that proves a policy's absence from a cached collection cannot tell a genuinely missing policy from a list that is merely stale or failed to load, and renders all three as a 404. This read separates them: `404` means the policy does not exist (or, with `project_id`, is not attached to that project), and any other failure is reported as what it is. With `project_id` the response carries the project-scoped `result_summary`, exactly as the project's policy list does, so a detail view needs no second shape. ## OpenAPI ````yaml /api-reference/earnie/policies-openapi.json get /v1/policies/{id} openapi: 3.0.3 info: title: Earnie Policies API description: >- Author policies, attach them to projects, and read how projects, scans, and findings evaluate against them. version: 1.0.0 servers: - url: https://{tenant}.earnie.dev description: Your Earnie deployment variables: tenant: default: your-company description: >- Your organization's Earnie address, as shown in your browser when you sign in. security: - bearerAuth: [] paths: /v1/policies/{id}: parameters: - name: id in: path required: true schema: type: integer format: int64 get: summary: Read one policy description: >- The authoritative answer to "does this policy exist, and is it here?". A client that proves a policy's absence from a cached collection cannot tell a genuinely missing policy from a list that is merely stale or failed to load, and renders all three as a 404. This read separates them: `404` means the policy does not exist (or, with `project_id`, is not attached to that project), and any other failure is reported as what it is. With `project_id` the response carries the project-scoped `result_summary`, exactly as the project's policy list does, so a detail view needs no second shape. operationId: GetPolicy parameters: - name: project_id in: query required: false schema: type: string format: uuid description: >- Read the policy through this project's attachment. The project must belong to the caller's organization; a policy that exists but is not attached to it answers `404`, because it is not this project's policy to show. responses: '200': description: The policy content: application/json: schema: $ref: '#/components/schemas/Policy' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- No such policy, or (with `project_id`) not attached to that project. This is the ONLY missing-resource answer — a transport or server failure must never be rendered as one. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Policy: type: object required: - id - slug - source - module - category - name - description - agent_rule - agent_rule_stale - enabled - action - expression - parameter_spec - values - revision - created_at - updated_at properties: id: type: integer format: int64 readOnly: true slug: type: string description: >- Stable, human-readable identifier safe across deploys and migrations. Generated from `name` (kebab-cased) on Create when not supplied; templates ship with deterministic slugs (e.g. `block-copyleft-licenses`). Immutable after creation. source: allOf: - $ref: '#/components/schemas/PolicySource' readOnly: true description: >- Server-managed origin of the policy. Seeded templates return `seed`; user-authored rows return `custom`. module: type: string description: >- Finding domain the policy targets (e.g. `scans`, `crypto`, `crypto_finder`). AI provenance is an xBOM enrichment, not a separate policy domain. category: type: string description: Grouping within a scanner (e.g. `licenses`, `vulnerabilities`). name: type: string description: type: string description: Human-readable explanation of what the policy checks and why. agent_rule: type: string description: >- Keep it to roughly 200 bytes. That is not a stored-length limit — nothing rejects a longer one — it is where the RENDERED sentence is truncated with an ellipsis before it reaches an agent, measured after placeholders are substituted and in bytes rather than characters. A short rule whose `{banned_licenses}` expands to three hundred bytes is truncated too. The cap exists because this text sits in every prompt of every session. Written in the second person, one sentence, no CEL: "Do not add dependencies licensed {banned_licenses}." `{key}` placeholders name `parameter_spec[].key` entries and are substituted with the policy's current `values` at render time, so one sentence stays true after a parameter is tuned. A list value renders as `a, b or c`. A placeholder naming no parameter is rejected on save. Empty is allowed and means "no agent rule": rendering falls back to `description`, and last to the CEL expression labelled as such, so a policy without one still reaches an agent. Like `description` it is prose and NOT part of the policy `revision` — rewording what an agent reads does not change what the gate does. agent_rule_stale: type: boolean readOnly: true description: >- True when `agent_rule` was written against different rule logic than this policy now carries — its `action`, `expression`, or the set of parameter keys has changed since the sentence was last saved. An agent rule is hand-written prose and cannot be derived from CEL, so nothing keeps it true when the expression moves underneath it. This is how the product notices: the sentence still renders (it is usually still mostly right), but the policy is flagged so a human can review it. Saving the agent rule again clears the flag. Parameter VALUES are deliberately excluded: `{key}` placeholders already keep the sentence true across a retune, so a threshold tweak never raises this. False when the policy has no agent rule, and false for a row that predates the stored basis — "unknown" must not read as "stale". enabled: type: boolean action: $ref: '#/components/schemas/Action' expression: type: string description: >- CEL string. Compiled via `cel-go` on save (parse + type check + params.X consistency) and evaluated against findings via `Eval` (see `/preview` for the live-evaluation surface). parameter_spec: type: array items: $ref: '#/components/schemas/ParameterSpec' values: type: object additionalProperties: true description: >- Current parameter values keyed by `parameter_spec[].key`. Every declared key needs a value or a `default` in its spec entry, including a parameter the expression only reads behind `has()`; a key left out is stored with its `default`. See `ValuesInvalidError`. revision: type: string readOnly: true description: >- The policy's immutable content revision: a `sha256:` digest over the canonical form of the gating content — `action`, `expression`, `parameter_spec`, `values`. It is byte-identical to the `policy_hash` an evaluation records and to the revision a scan's policy snapshot names, so "which revision produced this verdict" and "which revision is live now" are answered in one vocabulary. Mutations echo it back in `If-Match`. A stale revision is `409 policy_conflict`; a policy edit is never last-write-wins. It covers the gating content and nothing else. Renaming a policy or rewriting its description leaves the revision unchanged, because neither changes what the gate does, and `enabled` is carried by presence in a scan's snapshot rather than by the digest. created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true result_summary: $ref: '#/components/schemas/PolicyResultSummary' Error: type: object required: - code - message properties: code: type: string message: type: string PolicySource: type: string enum: - seed - custom description: >- Server-managed provenance of the policy row. seed → curated template from the embedded manifest custom → user-authored policy created through the API Action: type: string enum: - block - warn - require description: >- Enforcement action applied when the policy fires. Verdict mapping: block → block warn → warn require → require ParameterSpec: type: object required: - key - label - type properties: key: type: string description: >- Semantic identifier (e.g. `min_stars`, `blocked_severities`). Referenced inside the expression as `params.`. label: type: string type: $ref: '#/components/schemas/ParameterType' options: type: array items: type: string nullable: true default: description: >- Used as the value when `values` leaves this key out, and stored as such. Must itself fit `type` and `options`. A parameter with no `default` must always be given a value. constrains: type: string nullable: true description: >- Optional field-catalog `path` this parameter's values should be drawn from (e.g. `license.spdx_id`). Descriptive metadata only — NOT validated against the catalog at save time; consumed by frontend parameter pickers (out of scope for this change) to reuse `GET /fields/{path}/values`. PolicyResultSummary: type: object required: - state - violations_count - affected_files_count - affected_components_count properties: state: $ref: '#/components/schemas/EvaluationState' violations_count: type: integer minimum: 0 affected_files_count: type: integer minimum: 0 description: >- Distinct non-empty finding locators among current, non-approved violations. affected_components_count: type: integer minimum: 0 description: >- Distinct non-empty component identifiers among current, non-approved violations. missing_enrichments: type: array items: type: string description: >- Canonical enrichment identifiers required before evaluation can complete. error_message: type: string last_evaluated_at: type: string format: date-time ParameterType: type: string enum: - string - int - float - bool - enum - enum_set - tag_list description: >- Runtime type of a parameter slot. Drives the UI input control and validation hints. EvaluationState: type: string enum: - passed - violated - not_evaluated - error securitySchemes: bearerAuth: type: http scheme: bearer description: >- An Earnie API key, sent as `Authorization: Bearer sk_earnie_...`. Create one under Settings > API keys. The key's scopes decide which operations it may call. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.