> ## Documentation Index > Fetch the complete documentation index at: https://docs.penelope.health/llms.txt > Use this file to discover all available pages before exploring further. # List Policies > List medical policies with structured filters. Supports filtering by medical codes, payers, LOBs, LOB categories, states, effective dates, and full-text search (q). Results default to relevance order: ranked against q when given, otherwise against the descriptions of the filtered codes (first 20) — non-matching policies are still returned, sorted last. With neither q nor codes, results come back in policy-id order. Payer/LOB/state filters use current applicability by default, or the request's effective_date window when supplied. Set include_applicability=true to include the same current/date-windowed applicability, and include_code_groups=true for associated codes. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/policies/filter openapi: 3.1.0 info: title: Penelope Health API description: REST API for querying the Penelope Health knowledge graph. version: 1.0.0 servers: - url: https://api-sandbox.penelope.health description: Sandbox - url: https://api.penelope.health description: Production security: [] paths: /v1/policies/filter: post: summary: List Policies description: >- List medical policies with structured filters. Supports filtering by medical codes, payers, LOBs, LOB categories, states, effective dates, and full-text search (q). Results default to relevance order: ranked against q when given, otherwise against the descriptions of the filtered codes (first 20) — non-matching policies are still returned, sorted last. With neither q nor codes, results come back in policy-id order. Payer/LOB/state filters use current applicability by default, or the request's effective_date window when supplied. Set include_applicability=true to include the same current/date-windowed applicability, and include_code_groups=true for associated codes. operationId: list_policies_v1_policies_filter_post requestBody: content: application/json: schema: $ref: '#/components/schemas/PolicyFilterRequest' examples: policy_search: summary: Text search scoped to a LOB category value: policies: q: blepharoplasty lobs: - commercial limit: 3 include_applicability: true required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PaginatedResponse_PolicyResult_' example: data: - policy_id: bcbsm/76765/2026-03-01 policy_number: '76765' title: MEDICAL POLICY - BLEPHAROPLASTY AND REPAIR OF BROW PTOSIS effective_from_date: '2026-03-01' file_url: >- https://www.bcbsm.com/amslibs/content/dam/public/mpr/mprsearch/pdf/76765.pdf file_type: pdf listing_url: https://www.bcbsm.com/providers/mpradmin/ summary: >- This policy addresses surgical management of upper eyelid redundant tissue and eyebrow descent—blepharoplasty and repair of brow ptosis—focusing on restoration of function (visual field preservation, relief of dermatitis, prosthetic fit, and refractory blepharospasm). It defines objective functional... score: 4.3 applicability: - payer_ids: - KRPCH payer_names: - Blue Cross Blue Shield of Michigan lobs: - commercial - medicare_advantage state: MI - policy_id: bsc/medical/BSC7.01/2026-04-01 policy_number: BSC7.01 title: >- Blepharoplasty, Blepharoptosis Repair (Levator Resection) and Brow Lift (Repair of Brow Ptosis) effective_from_date: '2026-04-01' file_url: >- https://www.blueshieldca.com/content/dam/bsca/en/provider/docs/medical-policies/Blepharoplasty-Blepharoptosis-Repair-Brow-Lift.pdf file_type: pdf listing_url: >- https://www.blueshieldca.com/en/provider/authorizations/policy-medical/list summary: >- This Blue Shield of California medical policy (BSC7.01) addresses functional indications and medical necessity criteria for upper and lower eyelid blepharoplasty, blepharoptosis/ptosis repair (including levator resection and frontalis sling techniques), and brow lift/brow ptosis repair. It applies R... score: 4.2 applicability: - payer_ids: - JDGWJ payer_names: - Blue Shield of California lobs: - commercial - individual_aca - medicare_advantage state: CA - policy_id: anthem/abcbs/CG-SURG-03/2026-01-06 policy_number: CG-SURG-03 title: >- CG-SURG-03 Blepharoplasty, Blepharoptosis Repair, and Brow Lift effective_from_date: '2026-01-06' file_url: >- https://anthem.com/medpolicies/abcbs/active/gl_pw_a051144.html file_type: html listing_url: >- https://www.anthem.com/medpolicies/abcbs/active/fulllist.json summary: >- This clinical UM guideline (CG-SURG-03) addresses medical necessity criteria for blepharoplasty, blepharoptosis (ptosis) repair, and brow lift procedures of the upper and lower eyelids and forehead when performed for functional/visual-field impairment. It distinguishes medically necessary, reconstru... score: 4.1 applicability: - payer_ids: - TBEZC payer_names: - Anthem Blue Cross Blue Shield of Colorado lobs: - commercial - individual_aca - medicaid - medicare_advantage state: CO - payer_ids: - DRWRY payer_names: - Anthem Blue Cross Blue Shield of Connecticut lobs: - commercial - individual_aca - medicaid - medicare_advantage state: CT - payer_ids: - VDCLI payer_names: - Anthem Blue Cross Blue Shield of Georgia lobs: - commercial - individual_aca - medicaid - medicare_advantage state: GA - payer_ids: - AOQAR payer_names: - Anthem Blue Cross Blue Shield of Indiana lobs: - commercial - individual_aca - medicaid - medicare_advantage state: IN - payer_ids: - DXTYZ payer_names: - Anthem BlueCross BlueShield Kentucky lobs: - commercial - individual_aca - medicaid - medicare_advantage state: KY - payer_ids: - YJHSX payer_names: - Anthem Blue Cross Blue Shield of Maine lobs: - commercial - individual_aca - medicaid - medicare_advantage state: ME - payer_ids: - XUAZF payer_names: - Anthem Blue Cross Blue Shield Missouri lobs: - commercial - individual_aca - medicaid - medicare_advantage state: MO - payer_ids: - QCFIB payer_names: - Anthem Blue Cross and Blue Shield New Hampshire lobs: - commercial - individual_aca - medicaid - medicare_advantage state: NH - payer_ids: - ERSOT payer_names: - Anthem Blue Cross and Blue Shield Nevada lobs: - commercial - individual_aca - medicaid - medicare_advantage state: NV - payer_ids: - BHNXS payer_names: - Anthem Blue Cross Blue Shield Ohio lobs: - commercial - individual_aca - medicaid - medicare_advantage state: OH - payer_ids: - VLFZU payer_names: - Anthem Blue Cross and Blue Shield Wisconsin lobs: - commercial - individual_aca - medicaid - medicare_advantage state: WI limit: 3 offset: 0 has_more: true '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: PolicyFilterRequest: properties: policies: anyOf: - $ref: '#/components/schemas/PolicyFilter' - type: 'null' description: >- Policy filters. All fields optional; fields are AND'd together, and within a list field multiple values are OR'd. code_refs.match selects OR ('any', default) vs AND ('all') across refs. sort: type: string enum: - policy_id_asc - policy_id_desc - title_asc - title_desc - policy_number_asc - policy_number_desc - relevance title: Sort description: >- Sort order. Defaults to relevance: ranked against q when given, otherwise against the descriptions of the filtered codes; with neither, policy-id order. default: relevance examples: - relevance limit: type: integer maximum: 100 minimum: 1 title: Limit description: Maximum number of results to return default: 20 examples: - 20 offset: type: integer minimum: 0 title: Offset description: Number of results to skip for pagination default: 0 examples: - 0 include_applicability: type: boolean title: Include Applicability description: >- Include each policy's payer/LOB/geography applicability. Returns current applicability by default, or — when a policies.effective_date window is given — the applicability in effect during that window. default: false examples: - true include_code_groups: type: boolean title: Include Code Groups description: >- Include code groups (grouped by code system, relationship, and category) default: false examples: - true additionalProperties: false type: object title: PolicyFilterRequest description: POST body for /v1/policies/filter. PaginatedResponse_PolicyResult_: properties: data: items: $ref: '#/components/schemas/PolicyResult' type: array title: Data description: Array of result objects limit: type: integer title: Limit description: Maximum number of results requested examples: - 20 offset: type: integer title: Offset description: Number of results skipped for pagination examples: - 0 has_more: type: boolean title: Has More description: True if more results exist beyond this page examples: - false type: object required: - data - limit - offset - has_more title: PaginatedResponse[PolicyResult] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PolicyFilter: properties: q: anyOf: - type: string - type: 'null' title: Q description: Full-text search query across policy titles and summaries. examples: - blepharoplasty code_refs: anyOf: - $ref: '#/components/schemas/CodeRefFilter' - type: 'null' description: >- Filter by medical codes; refs are OR'd by default (match=any), match=all requires a policy to match every ref. lob_ids: anyOf: - items: type: string type: array - type: 'null' title: Lob Ids description: Filter by line-of-business IDs examples: - - KMQTZ_commercial_US_ payer_ids: anyOf: - items: type: string type: array - type: 'null' title: Payer Ids description: Filter by insurance payer IDs examples: - - KMQTZ lobs: anyOf: - items: $ref: '#/components/schemas/LobCategory' type: array - type: 'null' title: Lobs description: Filter by line-of-business categories examples: - - commercial states: anyOf: - items: type: string type: array - type: 'null' title: States description: >- Filter by US state codes. Nationwide LOBs (state IS NULL) are always included. examples: - - CA - NY effective_date: anyOf: - $ref: '#/components/schemas/EffectiveDateFilter' - type: 'null' description: >- Restrict to policies in effect during this date range (their effective period overlaps the window). retired: anyOf: - type: boolean - type: 'null' title: Retired description: >- Filter by retirement status. true=retired (no longer in effect), false=active (currently in effect), null/omit=both. examples: - false additionalProperties: false type: object title: PolicyFilter description: |- All policy filters. All fields optional; fields are AND'd together, and within a list field multiple values are OR'd. code_refs.match selects OR ('any', default) vs AND ('all') across refs. PolicyResult: properties: policy_id: type: string title: Policy Id description: Unique policy identifier examples: - uhc/MP.002/2026-01-01 policy_number: type: string title: Policy Number description: Policy number assigned by the payer examples: - MP.002.28 title: type: string title: Title description: Policy title examples: - Brow Ptosis and Eyelid Repair effective_from_date: type: string format: date title: Effective From Date description: First day the policy is in effect (inclusive) examples: - '2026-01-01' effective_to_date: anyOf: - type: string format: date - type: 'null' title: Effective To Date description: >- First date the policy is no longer in effect (exclusive end); null if currently active examples: - null file_url: type: string title: File Url description: Original URL from which the policy file was downloaded examples: - >- https://www.uhcprovider.com/content/dam/provider/docs/public/policies/comm-medical-drug/brow-ptosis-and-eyelid-repair.pdf file_type: type: string enum: - pdf - html - md title: File Type description: >- Format of the stored copy of the policy document, downloadable via the download-url endpoint. examples: - pdf listing_url: type: string title: Listing Url description: URL of the listing page where the policy was found examples: - >- https://www.uhcprovider.com/en/policies-protocols/comm-medical-drug-policies/comm-medical-drug-policies.html summary: anyOf: - type: string - type: 'null' title: Summary description: AI-generated policy summary examples: - >- This policy covers blepharoplasty and brow lift procedures when medically necessary for functional impairment... score: anyOf: - type: number - type: 'null' title: Score description: >- Relevance score. Present when results are relevance-ranked — against q, or against the descriptions of the filtered codes. Null under non-relevance sorts, and for policies whose title/summary don't match the ranking text (those sort last). examples: - 4.26 applicability: anyOf: - items: $ref: '#/components/schemas/LobApplicability' type: array - type: 'null' title: Applicability description: >- Payer/LOB/geography applicability. Only included when include_applicability=true. examples: - null code_groups: anyOf: - items: $ref: '#/components/schemas/PolicyCodeGroup' type: array - type: 'null' title: Code Groups description: >- Codes referenced by this policy, grouped by system and relationship. null when include_code_groups=false; a list (possibly empty) otherwise. examples: - null type: object required: - policy_id - policy_number - title - effective_from_date - effective_to_date - file_url - file_type - listing_url - summary title: PolicyResult description: >- Single fixed type -- nullable fields are null when not requested/relevant. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError CodeRefFilter: properties: match: type: string enum: - any - all title: Match description: >- 'any' (default) = policy matches at least one ref (OR); 'all' = policy matches every ref (AND). default: any examples: - all refs: items: $ref: '#/components/schemas/CodeReference' type: array minItems: 1 title: Refs description: >- Code references to match against. Within a single ref, codes (and relationship values) are OR'd. additionalProperties: false type: object required: - refs title: CodeRefFilter description: >- Combine multiple CodeReferences with either OR ('any') or AND ('all') semantics. LobCategory: type: string enum: - commercial - medicare_part_a - medicare_part_b - medicare_advantage - medicare_part_d - medicaid - individual_aca title: LobCategory description: Line-of-business categories. EffectiveDateFilter: properties: start: anyOf: - type: string format: date - type: 'null' title: Start description: >- Window start (inclusive). Returns policies still in effect on or after this date (active policies with no end date are always included). examples: - '2025-01-01' end: anyOf: - type: string format: date - type: 'null' title: End description: >- Window end (inclusive). Returns policies that had taken effect on or before this date. examples: - '2025-06-15' additionalProperties: false type: object title: EffectiveDateFilter description: >- Restrict results to policies in effect during a date range (what applied on/over these dates). LobApplicability: properties: payer_ids: items: type: string type: array title: Payer Ids description: Payer IDs that share this coverage scope examples: - - KMQTZ payer_names: items: type: string type: array title: Payer Names description: Display names of payers examples: - - UnitedHealthcare lobs: items: $ref: '#/components/schemas/LobCategory' type: array title: Lobs description: LOB categories this scope applies to examples: - - commercial - individual_aca state: anyOf: - type: string - type: 'null' title: State description: US state for this scope (null if nationwide) examples: - null type: object required: - payer_ids - payer_names - lobs - state title: LobApplicability description: >- Single applicability scope — Cartesian product of payers × LOBs × geography. PolicyCodeGroup: properties: code_system: type: string enum: - CPT - CPT_MODIFIER - HCPCS - HCPCS_MODIFIER - ICD10CM title: Code System description: Code system type examples: - CPT relationship: type: string enum: - COVERS - DOES_NOT_COVER - REFERENCES title: Relationship description: Relationship type between policy and codes examples: - COVERS category: anyOf: - type: string - type: 'null' title: Category description: Semantic category from policy, if provided examples: - Brow Ptosis Procedures codes: items: type: string type: array title: Codes description: List of codes in this group examples: - - '19318' - '19319' - '67900' descriptions: items: type: string type: array title: Descriptions description: Human-readable descriptions, aligned 1:1 with codes list examples: - - Upper eyelid blepharoplasty - Repair blepharoptosis type: object required: - code_system - relationship - category - codes title: PolicyCodeGroup description: Group of codes with same system, relationship, and category. CodeReference: properties: code_system: type: string enum: - CPT - CPT_MODIFIER - HCPCS - HCPCS_MODIFIER - ICD10CM title: Code System description: >- Code system. Only supported tables: CPT, CPT_MODIFIER, HCPCS, HCPCS_MODIFIER, ICD10CM. examples: - CPT codes: items: type: string type: array minItems: 1 title: Codes description: >- List of codes to match within the specified code system. Case-insensitive; ICD-10-CM codes may be sent dotted or dotless ('J33.0' and 'J330' are equivalent). examples: - - '15823' - '67900' relationship: anyOf: - items: type: string enum: - COVERS - DOES_NOT_COVER - REFERENCES type: array - type: 'null' title: Relationship description: >- Filter by relationship type (COVERS, DOES_NOT_COVER, REFERENCES). Omit for all. examples: - - COVERS - DOES_NOT_COVER - REFERENCES additionalProperties: false type: object required: - code_system - codes title: CodeReference description: Find policies linked to these codes via specified relationships. securitySchemes: APIKeyHeader: type: apiKey in: header name: x-api-key ````