Skip to main content
POST
Improve a Skill
Pick what to do with mode:
  • fix (default): a run’s diagnosis shows a field missing, for example phone: found on 0/5 rows — tried the result cards. Say where the data is, the way you would tell a person: “The phone is on the details page — click the place name, the panel opens, the number is next to the phone icon.”
  • add_fields: capture new fields, for example “also capture the star rating and review count”. A field that is only a new name for one the skill already has is merged into it (details.merged). An unclear one comes back as a question (details.ambiguous). Only really new fields are learned.
  • relearn_details: rebuild how the skill opens each result, when the site changed or the fields from each result’s details page come back empty. feedback is an optional note.
feedback is required for fix and add_fields, and optional for relearn_details. The call answers at once. Poll GET /v1/skill-improvements/{improvement_id} until status is done or failed. If the check run does not show the new version is better, the attempt is kept as a candidate version and the old version stays live. Every change shows up in the skill’s change history. See Improve a skill for full examples.

Authorizations

Authorization
string
header
required

API key with the vd_sk_ prefix. Create keys from Settings, API Keys in the dashboard.

Headers

Idempotency-Key
string

Retry-safe key. The same key from the same account returns what it already started.

Path Parameters

slug
string
required

Body

application/json
mode
enum<string>
default:fix

What to do. fix: relearn the Skill from a hint about where the data is. add_fields: capture new fields described in feedback. relearn_details: rebuild the steps that open each result, for when the site changed or detail fields come back empty.

Available options:
fix,
add_fields,
relearn_details
Example:

"fix"

feedback
string

Plain English, 3–2,000 characters. Required for fix (what is wrong and where the data really is) and add_fields (the new fields to capture, for example "also capture the star rating and review count"). Optional for relearn_details, as a note. A request without it in fix or add_fields mode gets 422.

Required string length: 3 - 2000
Example:

"The phone is on the details page — click the place name, the panel opens, the number is next to the phone icon."

fields
string[] | null

Up to 10 field names. For fix: the output fields the hint is about; omit to use the last run's missing fields, or the fields the hint names. For add_fields: the names of the new fields; omit to let Valendata name them from feedback. Ignored for relearn_details.

Maximum array length: 10
Example:
example_input
object | null

Inputs for the check run. Omit to use the recorded example.

Response

Improvement started (or the existing one, for a repeated Idempotency-Key).

improvement_id
string
Example:

"imp_3f9a1c2b7d4e5f60"

status
enum<string>
Available options:
queued,
working,
validating,
done,
failed
status_url
string
Example:

"/v1/skill-improvements/imp_3f9a1c2b7d4e5f60"

skill_id
string
slug
string | null
mode
enum<string>

The mode it ran in.

Available options:
fix,
add_fields,
relearn_details
source
enum<string>

Where it was started: api, mcp, assistant (Igris), web (the web app), brain (the workflow Brain chat), or imported (a past Refine or Re-learn from before improvements were unified).

Available options:
api,
mcp,
assistant,
web,
brain,
imported
started_by_name
string | null

The name of the person who started it.

feedback
string | null
strategy
enum<string> | null

fields: relearn where the fields live. rerecord: redo the steps.

Available options:
fields,
rerecord
target_fields
string[]
diagnosis
object | null

The diagnosis it started from.

diagnosis_after
object | null

The check run's diagnosis, when fields are still missing.

fields_before
object
fields_after
object
changes
object[]
improved
boolean | null

True: the new version is live. False: kept as a candidate, the old recipe restored.

result
enum<string>

Short verdict. running: not finished. improved: the new version is live. kept_old: not better, so the old version stayed live. no_change: nothing needed changing. failed: see error. applied: imported from the old Refine history, applied without a check run.

Available options:
running,
improved,
kept_old,
no_change,
failed,
applied
imported
boolean

True for a past Refine or Re-learn entry imported into this history.

details
object | null

What the engine decided.

recipe_version_before
integer | null
recipe_version
integer | null

The live version when it ended.

candidate_version
integer | null

The version kept but not made live.

outcome
string | null
error
string | null
credits_charged
integer
created_at
string<date-time> | null
updated_at
string<date-time> | null
finished_at
string<date-time> | null
idempotent_replay
boolean