> ## Documentation Index > Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Review An Agent Prompt > Run DialNexa agent prompt review checks before publishing a Single Prompt Agent or Conversational Flow Agent version. Changes state - verify before retry Review an agent prompt before publishing. The operation can check instructions, variables, speech quality, contradictions, hallucination risks, language, model fallback, post-call capture, and call-handling settings without editing or publishing the agent version. ## When To Use Agent Prompt Review * Check a draft prompt before creating an immutable version. * Review only the check groups relevant to your release gate. * Generate a `fix_prefill` instruction that can be sent to an editing assistant. * Recheck the same content after changing the prompt or version configuration. ## Before You Call It * Use an `agent_` ID from [List Agents](/docs/api-reference/v1/agents/list). * Use a version number returned by [Get Agent Details](/docs/api-reference/v1/agents/get). * Keep `prompt_text` at `100,000` characters or fewer. Omit it to review the stored version prompt. * An empty or whitespace-only `prompt_text` also falls back to the stored prompt. ## Choose Prompt Review Checks Omit `checks` to run every available group. Send a smaller list when you need a faster focused review. | Check | What it evaluates | | --------------- | ----------------------------------------------------------------------------- | | `structure` | Prompt length, missing sections, and instruction alignment. | | `variables` | Undefined or unused dynamic variables. | | `speech` | Wording and punctuation that may sound poor when spoken. | | `unknowable` | Claims or questions the prompt does not provide enough information to answer. | | `conflicts` | Instructions that cannot both be followed. | | `language` | Prompt and configured language consistency. | | `models` | Primary and fallback model configuration. | | `capture` | Knowledge base and post-call field grounding. | | `call_handling` | Welcome message, silence, and duration configuration. | The `unknowable` and `conflicts` groups use model-based checks. Leaving both out avoids those model calls. ## Response Fields | Field | Meaning | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `review_fingerprint` | Stable fingerprint for the reviewed prompt, variables, checks, and review engine. | | `findings` | Warning and informational findings. Each item includes a stable `fingerprint`, `kind`, `family`, message, optional evidence, and acknowledgement state. | | `new_warning_count` | Warnings that have not already been accepted or dismissed. | | `reviewed_at` | ISO 8601 time when the report was produced. | | `degraded` | `true` when model-based checks could not run and only the available deterministic checks completed. | | `cached` | `true` when an unchanged review reused a previous complete report. | | `fix_prefill` | A ready-to-use instruction composed from the unacknowledged warnings. | ## Side Effects And Retry Safety This operation does not edit or publish the agent version. It can run billable model work, may take several seconds, and can store a complete report for reuse. Complete, non-degraded reports can be cached for identical inputs. Degraded reports are not cached so a later request can retry the full review. It is safe to retry after a timeout, but first allow enough time for the original review to finish. An identical completed request can return the cached report. ## Verify The Result Check `degraded` before treating the review as complete. Review every item where `acknowledged` is `false`, then either revise the prompt or record a decision with [Acknowledge A Prompt Review Finding](/docs/api-reference/v1/agents/acknowledge-prompt-review-finding). Publishing remains a separate user action. ## Operation-Specific Errors | Status | Meaning | What to do | | ------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `400 Bad Request` | The prompt is too long, a check name is invalid, or a path parameter failed validation. | Correct the request and retry. | | `401 Unauthorized` | The API key is missing or invalid. | Send a valid workspace API key. | | `404 Not Found` | The agent version was not found in the authenticated workspace. | Confirm the agent ID, version number, and workspace. | ## Related Lifecycle Operations * [Get Agent Details](/docs/api-reference/v1/agents/get) to find version numbers and the stored prompt. * [Update Agent](/docs/api-reference/v1/agents/update) to revise a draft before publishing. * [Acknowledge A Prompt Review Finding](/docs/api-reference/v1/agents/acknowledge-prompt-review-finding) to accept or dismiss one reviewed finding. ## OpenAPI ````yaml POST /v1/agent-versions/{agentId}/version/{versionNumber}/prompt-review openapi: 3.0.0 info: title: DialNexa API description: Public `/v1` REST API for the DialNexa voice AI platform. version: 1.0.0 servers: - url: https://api.dialnexa.com description: DialNexa production API security: - bearer: [] tags: - name: Agents - name: Batch Calls - name: Calls - name: Knowledge Base - name: Languages - name: LLMs - name: Phone Numbers - name: Transcribers - name: Webhooks - name: Voices - name: Workflows - name: Workflow Leads paths: /v1/agent-versions/{agentId}/version/{versionNumber}/prompt-review: post: tags: - Agents summary: Review An Agent Prompt description: >- Reviews one agent version prompt and configuration without editing or publishing the agent. operationId: reviewAgentPrompt parameters: - name: agentId required: true in: path description: Signed agent ID. schema: example: agent_2g7Xy3tY53gRlp type: string - name: versionNumber required: true in: path description: Agent version number to review. schema: type: integer minimum: 1 example: 1 requestBody: required: false content: application/json: schema: type: object properties: prompt_text: type: string maxLength: 100000 description: >- Draft prompt text to review instead of the stored version prompt. Omit or send blank text to use the stored prompt. checks: type: array description: Check groups to run. Omit to run every group. items: type: string enum: - structure - variables - speech - unknowable - conflicts - language - models - capture - call_handling examples: focusedReview: summary: Review speech, contradictions, and hallucination risks value: checks: - speech - conflicts - unknowable responses: '201': description: Prompt review completed. content: application/json: schema: type: object required: - review_fingerprint - findings - new_warning_count - reviewed_at - degraded - cached - fix_prefill properties: review_fingerprint: type: string description: SHA-256 fingerprint of the reviewed inputs. findings: type: array items: type: object required: - severity - family - kind - message - fingerprint - acknowledged properties: severity: type: string enum: - warning - info family: type: string enum: - prompt - config kind: type: string enum: - contradiction - hallucination_risk - undefined_variable - unused_variable - thin_prompt - missing_section - tts_dashes - instruction_misaligned - instruction_inert - speech_unfriendly - flow_break - flow_note - branch_gap - fallback_without_model - fallback_same_as_primary - welcome_script_mismatch - unused_knowledge_base - postcall_field_ungrounded - timeout_extreme message: type: string evidence: type: string nullable: true fingerprint: type: string pattern: ^[0-9a-f]{40}$ acknowledged: type: boolean new_warning_count: type: integer minimum: 0 reviewed_at: type: string format: date-time degraded: type: boolean cached: type: boolean fix_prefill: type: string examples: success: summary: Review with one warning value: review_fingerprint: >- 12a8f88ad6f0f521347705e2af1417f1fc8396f2e2913fcb056082ee1c51723f findings: - severity: warning family: prompt kind: undefined_variable message: >- The prompt uses a variable that has no configured default. evidence: '{{customer_tier}}' fingerprint: 6a763e1fa5d7c82cbb9e54e10d4232cfdd2423ba acknowledged: false new_warning_count: 1 reviewed_at: '2026-08-31T03:15:00.000Z' degraded: false cached: false fix_prefill: >- Fix the unacknowledged prompt review warnings without changing the agent's intended call objective. '400': description: Invalid request or path parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Agent version not found in the authenticated workspace. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearer: [] components: schemas: ErrorResponse: type: object properties: statusCode: type: integer example: 400 message: oneOf: - type: string - type: array items: type: string example: phone_number must be a valid E.164 phone number error: type: string example: Bad Request required: - statusCode - message - error securitySchemes: bearer: scheme: bearer type: http ````