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

# Validate Prompt

Use this API to expand a simple instruction into a structured QA task with an analysis prompt, tool requirements, response descriptions, and demo examples. This is the transformation step that turns a one-line instruction into a comprehensive QA task definition you can ship as an agent.

# Endpoint

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

# 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 simple instruction to expand.

**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. Each entry: `{ id, title, type, example?, defaultValue? }`.

## **Example Requests**

#### 1. Broken links

```JSON theme={null}
{
  "data": {
    "prompt": "Make sure there are no broken links on the page"
  }
}
```

#### 2. Accessibility check

```JSON theme={null}
{
  "data": {
    "prompt": "Check all images have alt text and all form inputs have labels"
  }
}
```

# Response

The `validationResult` object maps to the `PromptValidatorResult` interface.

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Prompt validated successfully",
    "data": {
      "validationResult": {
        "analysis_prompt": "## Objective\nIdentify all broken or non-functional hyperlinks on the page\n\n## Scope\nAll anchor elements (<a href>) and embedded resource URLs\n\n## Detection Logic\nHTTP HEAD/GET validation of link targets, checking for non-2xx status codes\n\n## Output Format\nList of broken links with source element, target URL, and HTTP status",
        "requires_tool": "TOOL_TEXT_EXTRACTOR",
        "response_descriptions": {
          "title": "Brief description of the broken link",
          "severity": "critical for 5xx errors, high for 4xx, medium for timeouts, low for redirects",
          "targetText": "The anchor text of the broken link",
          "suggestion": "The correct URL or action to fix the broken link",
          "issueType": "broken-link"
        },
        "demos": {
          "detection_dimensions": ["Link targets", "HTTP status codes", "Redirect chains"],
          "cases": [
            {
              "id": "demo-1",
              "title": "Broken link to documentation",
              "tier": "obvious_match",
              "dimension_tested": "HTTP status codes: 404",
              "html": "<a href=\"https://docs.example.com/api\">API Reference</a>",
              "expected": "detected",
              "reason": "Link returns 404 Not Found"
            }
          ]
        },
        "suggested_required_inputs": []
      }
    }
  }
}
```

**Response fields (`PromptValidatorResult`):**

| Field | Type | Description |
| - | - | - |
| `analysis_prompt` | string | Markdown-formatted QA analysis prompt (objective, scope, detection logic, output format). |
| `requires_tool` | string | `"TOOL_TEXT_EXTRACTOR"` or `"NONE"`. |
| `response_descriptions` | object | Per-field descriptions for AI response shaping. |
| `demos` | object | Demo test cases with detection dimensions and tiered cases. |
| `suggested_required_inputs` | object\[] | Runtime-dependent fields the user must provide at execution time. Each entry is `{ name, description, example, reason }`, all four present. Transform them before use: map `name` to `id`, `description` to `title`, keep `example`, and supply a `type` of `"string"`, `"number"`, or `"boolean"`. `reason` is explanatory only and is not part of the [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md) shape. Sending an entry verbatim as an `input.userContextFields` element is rejected. |

#### 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 validated successfully",
    "data": {
      "validationResult": {
        "analysis_prompt": "## Objective\n...",
        "requires_tool": "NONE",
        "response_descriptions": {},
        "demos": {},
        "suggested_required_inputs": []
      }
    }
  }
}
```


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