Improve a skill
Fix a field, add new fields, or re-learn how a skill opens each result. A cloud browser relearns it, a short check run tests it, and it goes live only if it is better.
mode:
fix(default): a run’sdiagnosisshows a field missing, for examplephone: 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.feedbackis 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
API key with the vd_sk_ prefix. Create keys from Settings, API Keys in the dashboard.
Headers
Retry-safe key. The same key from the same account returns what it already started.
Path Parameters
Body
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.
fix, add_fields, relearn_details "fix"
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.
3 - 2000"The phone is on the details page — click the place name, the panel opens, the number is next to the phone icon."
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.
10Inputs for the check run. Omit to use the recorded example.
Response
Improvement started (or the existing one, for a repeated Idempotency-Key).
"imp_3f9a1c2b7d4e5f60"
queued, working, validating, done, failed "/v1/skill-improvements/imp_3f9a1c2b7d4e5f60"
The mode it ran in.
fix, add_fields, relearn_details 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).
api, mcp, assistant, web, brain, imported The name of the person who started it.
fields: relearn where the fields live. rerecord: redo the steps.
fields, rerecord The diagnosis it started from.
The check run's diagnosis, when fields are still missing.
True: the new version is live. False: kept as a candidate, the old recipe restored.
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.
running, improved, kept_old, no_change, failed, applied True for a past Refine or Re-learn entry imported into this history.
What the engine decided.
The live version when it ended.
The version kept but not made live.

