---
title: "Recommend presets for an intent"
method: POST
path: "/presets/recommend"
tags: ["Presets"]
---

# Recommend presets for an intent

`POST /presets/recommend`

## Request

- Base URL: `https://api.varg.ai/v2`
- URL: `https://api.varg.ai/v2/presets/recommend`
- Auth: one of:
  - none
  - HTTP bearer

Ranks presets against a free-text description of what you want, using
keyword overlap over name, description and metadata. Presets with no
match are excluded. `confidence` is comparable only within one response.
Auth is optional.

## Request body

- PresetRecommendRequest
  - `intent` string, required: Free-text description of what you want.
  - `type` string: Narrow to one parameter type.
  - `namespace` string: Narrow to one id system.
  - `tool` string: Only presets deliverable into this tool.
  - `limit` integer: Max results. Larger values are clamped to 50; invalid values fall back to 10.

## Response `200`

Ranked recommendations

- PresetRecommendResponse
  - `count` integer, required
  - `data` PresetRecommendation[], required
    - `id` string, required
    - `kind` string, required
    - `type` string, required
    - `namespace` string, required
    - `name` string, required
    - `description` string, nullable, required
    - `preview_url` string, nullable, required
    - `metadata` object, required
    - `confidence` number, required: Match strength; comparable only within one response.
    - `why` string[], required: Match reasons, for example `name`, `description`, `tone=deep` (metadata value) or `axis:tone` (metadata key).

## Other responses

- `400`: Body is not a JSON object or `intent` is missing or blank

## Changes

- **2026-10-20** `43bcf5ea398d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/varg/apis/varg-api/changes/presets/recommend/post.md)

---

[API](https://skmtc.dev/varg/apis/varg-api.md) · [All operations](https://skmtc.dev/varg/apis/varg-api/llms.txt) · [OpenAPI document](https://skmtc.dev/varg/apis/varg-api/revisions/09d49a6d852f?raw)