> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Enhance Prompt

Use this API to check whether a prompt has enough detail for agent execution. It returns either a "sufficient" signal or a specific clarification request with suggested options. It does **not** modify the prompt; it only checks completeness.

# Endpoint

`POST https://api.velt.dev/v2/agents/prompt/enhance`

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/docs/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="prompt" type="string" required>
      Min 1 char. The user's raw prompt to validate.
    </ParamField>

    <ParamField body="provider" type="string">
      LLM provider override: `"gemini"` or `"claude"`.
    </ParamField>

    <ParamField body="userContextFields" type="object[]">
      Optional declared user-context fields, so the enhancer knows which runtime inputs the agent will already collect and does not ask for them again. Each entry: `{ id, title, type, example?, defaultValue? }`.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### 1. Simple prompt

```JSON theme={null}
{
  "data": {
    "prompt": "Check that the page uses our brand colors"
  }
}
```

#### 2. With provider override and declared user context

```JSON theme={null}
{
  "data": {
    "prompt": "Verify all CTAs use the correct color",
    "provider": "claude",
    "userContextFields": [
      { "id": "brand_color", "title": "Primary brand color", "type": "string" }
    ]
  }
}
```

# Response

#### Success Response (prompt is sufficient)

When the prompt contains enough information, `requirement` is `null`:

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Prompt enhanced successfully",
    "data": {
      "enhancedPrompt": {
        "requirement": null
      }
    }
  }
}
```

#### Success Response (needs clarification)

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Prompt enhanced successfully",
    "data": {
      "enhancedPrompt": {
        "requirement": "Please specify which brand colors to verify",
        "context": "We need the exact hex values or color names to check accurately",
        "suggestion": [
          "check primary brand color #1A73E8 only",
          "check all brand palette colors"
        ],
        "suggestion_type": "single-select"
      }
    }
  }
}
```

**Response fields:**

| Field             | Type           | Present When        | Description                                                             |
| ----------------- | -------------- | ------------------- | ----------------------------------------------------------------------- |
| `requirement`     | string \| null | always              | `null` if the prompt is sufficient; a clarification question otherwise. |
| `context`         | string         | needs clarification | Additional context explaining why clarification is needed.              |
| `suggestion`      | string\[]      | needs clarification | Suggested options for the user to choose from.                          |
| `suggestion_type` | string         | needs clarification | `"boolean"`, `"single-select"`, `"multi-select"`, or `"info"`.          |

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

**Errors:** `INVALID_ARGUMENT` (missing or empty `prompt`).

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "status": "success",
      "message": "Prompt enhanced successfully",
      "data": {
        "enhancedPrompt": { "requirement": null }
      }
    }
  }
  ```
</ResponseExample>