> ## 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

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**prompt** `string` *required*

Min 1 char. The user's raw prompt to validate.

**provider** `string`

LLM provider override: `"gemini"`, `"claude"`, or `"openai"`. Any other value is accepted by the request schema but then fails the call with `INTERNAL`. Omit the field to use the platform default.

**userContextFields** `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? }`.

## **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`).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.