Enhance Prompt

POST /v2/agents/prompt/enhance

Enhance Prompt

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/prompt/enhance \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "prompt": "<string>",
    "provider": "<string>",
    "userContextFields": [
      {}
    ]
  }
}
'

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

Use this API to validate whether a prompt has enough detail for agent execution. Returns either a “sufficient” signal or a specific clarification request with suggested options.

This endpoint does not modify the prompt — it only checks completeness. Use it as a guardrail before letting a user save an underspecified agent. To expand a simple instruction into a structured QA task, use Validate Prompt.

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.

Body

Params

data · object · required

Show properties

prompt · string · required

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

provider · string

LLM provider override: "gemini" or "claude".

userContextFields · object[]

Optional userContextFields declarations the user has already added to the agent. The enhancer takes them into account when judging completeness.

Each entry: { id, title, type, example?, defaultValue? }. type is "string", "number", or "boolean".

Example Requests

1. Check completeness of a vague prompt

{
  "data": {
    "prompt": "Check that the page uses our brand colors"
  }
}

2. Check completeness with a provider override

{
  "data": {
    "prompt": "Verify all CTAs use the correct color",
    "provider": "claude"
  }
}

3. Check completeness with declared user-context fields

{
  "data": {
    "prompt": "Check that the page uses {{brand_color}} on all buttons",
    "userContextFields": [
      { "id": "brand_color", "title": "Primary brand color", "type": "string", "example": "#1A73E8" }
    ]
  }
}

Response

Success Response (prompt is sufficient)

When the prompt contains enough information, requirement is null:

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

Success Response (needs clarification)

When the prompt needs more detail:

{
  "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"
      }
    }
  }
}

Field	Type	Present When	Description
requirement	string | null	always	null if sufficient; clarification question if not
context	string	needs clarification	Why the 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

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

Errors: INVALID_ARGUMENT (missing or empty prompt).

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