---
title: "Analyze Instruction Gaps"
method: POST
path: "/voice/agents/{agentId}/generation/gaps/analyze"
tags: ["Voice Agent Intelligence"]
---

# Analyze Instruction Gaps

`POST /voice/agents/{agentId}/generation/gaps/analyze`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/voice/agents/{agentId}/generation/gaps/analyze`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

### Analyze Instruction Gaps

Requires the OWNER or ADMIN role. Advisory only -- compares the agent's current instructions against anchors/original intent/conversation summaries you supply and suggests up to 3 patches. Nothing is written; pass a suggestion's suggestedPatch to Apply Instruction Gap to actually apply it.

## Path parameters

- `agentId` string, required

## Request body

- object
  - `anchors` string[]: Specific requirements the instructions must cover. Defaults to empty.
  - `originalPrompt` string: The original generation prompt, for context.
  - `conversationSummaries` string[]: Recent call summaries, to ground suggestions in what actually came up. Defaults to empty.

## Response `200`

OK

- object
  - `status` 'success'
  - `data` object
    - `gaps` object[]: Up to 3 suggestions. Nothing is persisted by this endpoint.
      - `description` string
      - `suggestedPatch` string: Pass this straight into Apply Instruction Gap's suggestedPatch.
      - `insertAfterSection` string, nullable
      - `severity` 'low' | 'medium' | 'high'

## Other responses

- `403`: Caller's role is not OWNER or ADMIN
- `404`: Agent not found

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)