> ## 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. # Get Provider Guidance > Analyze a clinical encounter transcript against insurance policy criteria. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/provider-guidance 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/provider-guidance: post: summary: Get Provider Guidance description: >- Analyze a clinical encounter transcript against insurance policy criteria. operationId: get_provider_guidance_v1_provider_guidance_post requestBody: content: application/json: schema: $ref: '#/components/schemas/ProviderGuidanceRequest' examples: functional_blepharoplasty: summary: Synthetic encounter note value: note: >- Patient presents with bilateral upper eyelid ptosis causing visual field obstruction. MRD-1 measured at 1.5 mm bilaterally. Taped visual field testing shows 30% superior field improvement. Plan: functional blepharoplasty evaluation. payer_id: KMQTZ lob: commercial state: TX required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ProviderGuidancePublic' example: questions: - question: Any bleeding disorders? rationale: >- UHC MP.002 requires documentation of bleeding-disorder screening before approving surgical intervention. policy_reference: policy_id: uhc/MP.002/2026-01-01 citation: >- Patient must be evaluated for bleeding disorders prior to procedure. note_citation: Patient scheduled for excision next week. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: ProviderGuidanceRequest: properties: note: type: string maxLength: 100000 title: Note description: Clinical encounter note examples: - >- Patient presents with bilateral upper eyelid ptosis causing visual field obstruction... payer_id: type: string title: Payer Id description: Unique Stedi payer ID (see https://www.stedi.com/healthcare/network) examples: - KMQTZ - HPQRS lob: $ref: '#/components/schemas/LobCategory' description: Line-of-business category examples: - commercial state: $ref: '#/components/schemas/USState' description: Member state or jurisdiction code examples: - TX type: object required: - note - payer_id - lob - state title: ProviderGuidanceRequest ProviderGuidancePublic: properties: status: $ref: '#/components/schemas/ProviderGuidanceStatus' description: >- Outcome of the analysis. With a non-empty `output`: - `medical_necessity_not_met` — contradictions only - `documentation_gaps` — questions only - `medical_necessity_not_met_and_documentation_gaps` — both With an empty `output` (disambiguated): - `no_documentation_gaps` — a relevant policy was found and every applicable criterion is already satisfied - `no_applicable_policy` — a procedure is planned but no policy directly authorizes it - `no_procedure_planned` — nothing is affirmatively planned in this encounter examples: - medical_necessity_not_met_and_documentation_gaps output: items: oneOf: - $ref: '#/components/schemas/ClinicalQuestionPublic' - $ref: '#/components/schemas/ClinicalContradictionPublic' discriminator: propertyName: type mapping: contradiction: '#/components/schemas/ClinicalContradictionPublic' question: '#/components/schemas/ClinicalQuestionPublic' type: array title: Output description: >- Contradiction findings (documented values that fail a criterion) followed by outstanding clinical questions (missing documentation), based on policy criteria. Contradictions always come first. examples: - - note_citation: baseline serum uric acid prior to initiation 5.4 mg/dL policy_reference: citation: >- Documentation is provided that individual has a baseline serum uric acid of 6 mg/dL or greater. policy_id: anthem/clinical_criteria/CC-0057/2025-07-23 rationale: >- Anthem CC-0057 requires a documented baseline serum uric acid of 6 mg/dL or greater prior to initiating pegloticase; the note records 5.4 mg/dL. type: contradiction - note_citation: Patient scheduled for excision next week. policy_reference: citation: >- Patient must be evaluated for bleeding disorders prior to procedure. policy_id: uhc/MP.002/2026-01-01 question: Any bleeding disorders? rationale: >- UHC MP.002 requires documentation of bleeding-disorder screening before approving surgical intervention. type: question type: object required: - status - output title: ProviderGuidancePublic HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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. USState: type: string enum: - AL - AK - AZ - AR - CA - CO - CT - DE - FL - GA - HI - ID - IL - IN - IA - KS - KY - LA - ME - MD - MA - MI - MN - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - OH - OK - OR - PA - RI - SC - SD - TN - TX - UT - VT - VA - WA - WV - WI - WY - DC - AS - GU - PR - VI - CNMI - NF - SF - DN - QN - UN - EM - WM title: USState description: >- US states, territories, and Medicare contractor jurisdictions. Includes standard 50 US states, DC, territories, and Medicare contractor jurisdiction subdivisions (e.g., Northern California, Queens NY). ProviderGuidanceStatus: type: string enum: - medical_necessity_not_met - documentation_gaps - medical_necessity_not_met_and_documentation_gaps - no_documentation_gaps - no_applicable_policy - no_procedure_planned title: ProviderGuidanceStatus description: >- Outcome of the guidance analysis. Non-empty statuses reflect the composition of `output` and are derived programmatically by a model validator (contradictions ⇒ medical necessity is failed; questions ⇒ documentation is missing). The empty statuses disambiguate the cases that would otherwise all serialize as an empty list: criteria all met vs. no applicable policy vs. nothing planned. ClinicalQuestionPublic: properties: type: type: string const: question title: Type default: question question: type: string title: Question description: A short clinical question in plain language. examples: - Any bleeding disorders? - 6 months+ of conservative treatment? - Size changes? - Pain at lesion? rationale: type: string title: Rationale description: Why this information is needed, citing the policy examples: - >- UHC MP.002 requires documentation of failed conservative treatment before approving surgical intervention. policy_reference: $ref: '#/components/schemas/PolicyReferencePublic' description: Policy id and verbatim citation from the policy document note_citation: type: string title: Note Citation description: >- Verbatim text extract from the clinical note that motivates this question. type: object required: - question - rationale - policy_reference - note_citation title: ClinicalQuestionPublic ClinicalContradictionPublic: properties: type: type: string const: contradiction title: Type default: contradiction rationale: type: string title: Rationale description: >- Why this criterion is failed, naming the documented value and the required threshold. examples: - >- Anthem CC-0057 requires a documented baseline serum uric acid of 6 mg/dL or greater prior to initiating pegloticase; the note records 5.4 mg/dL. policy_reference: $ref: '#/components/schemas/PolicyReferencePublic' description: Policy id and verbatim citation from the policy document note_citation: type: string title: Note Citation description: >- Verbatim text extract from the clinical note that conflicts with the criterion. type: object required: - rationale - policy_reference - note_citation title: ClinicalContradictionPublic description: |- A criterion the note explicitly fails — a judgement, not a question. Emitted only when the note documents a concrete value/finding that conflicts with a policy criterion (e.g. uric acid 5.4 mg/dL where the policy requires ≥ 6 mg/dL). Merely-missing documentation is a ClinicalQuestion, not a contradiction. 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 PolicyReferencePublic: properties: policy_id: type: string title: Policy Id description: Unique policy identifier examples: - uhc/MP.002/2026-01-01 citation: type: string title: Citation description: Verbatim text extract from the policy document. type: object required: - policy_id - citation title: PolicyReferencePublic securitySchemes: APIKeyHeader: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.