Skip to main content
POST
Improve a skill
Pick a mode: fix (default), add_fields, or relearn_details. feedback is required for the first two. The call answers at once; read Get an improvement until status is done or failed. When to use each mode, how to read a run’s diagnosis, and what happens step by step are in Improve a skill. MCP tool: improve_skill.

Authorizations

Authorization
string
header
required

API key with the vd_sk_ prefix, as Authorization: Bearer vd_sk_.... Create keys in Settings → API Keys.

Headers

Idempotency-Key
string

Any unique string (such as your order id). Resending the same request with the same key within 24 hours returns the first answer (with Idempotent-Replayed: true) and does nothing twice; the same key with a different request is a 422 idempotency_key_reused.

Required string length: 1 - 255

Path Parameters

slug
string
required

Body

application/json

What to change, in plain English, the way you would coach a person doing the task.

mode
enum<string>
default:fix

fix: fill fields the skill misses, from a hint about where the data is (the default). add_fields: capture NEW fields described in plain English. relearn_details: rebuild how the skill clicks into each result (its per-row detail steps) — for a site that changed or detail fields that come back empty.

Available options:
fix,
add_fields,
relearn_details
feedback
string
default:""

fix: what the skill gets wrong and where the data really is, e.g. 'The phone is on the details page — click the place name, the panel opens, the number is next to the phone icon.' add_fields: the new fields, e.g. 'also capture the star rating and the review count'. relearn_details: an optional note, e.g. 'the details now open in a side panel'. Required (3+ characters) for fix, and for add_fields unless fields names them.

Maximum string length: 2000
fields
string[] | null

fix: the output fields the hint is about (e.g. ["phone"]); omit to use the fields the last run came back without, or the ones the hint names. add_fields: the new fields' names, when you know them. relearn_details: only re-learn these detail fields.

example_input
Example Input · object | null

Inputs for the check run (max 5 rows) that proves the improvement. Omit to use the skill's recorded example.

browser_type
string | null

The browser to learn and check on: remote (cloud browser) | extension (your Chrome). Omit to use the browser the skill normally runs on (its saved browser mode, else remote). A skill that runs in your Chrome needs the extension connected.

Response

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

Where an improvement is: queued → working → validating → done | failed.

done with improved: true means the new recipe version is live; done with improved: false means the attempt was kept as a candidate version (not live) and outcome says why. failed means the engine could not run (error). result says the same in one word.

improvement_id
string
required
status
string
required
status_url
string
required
skill_id
string
required
feedback
string
required
slug
string | null
mode
enum<string>
default:fix
Available options:
fix,
add_fields,
relearn_details
source
string
default:api

Who asked: api | mcp | assistant (Igris) | web | brain (workflow Brain) | imported (from the old Refine history)

result
enum<string>
default:running

running | improved (new version live) | kept_old (not better — the old version stays, the attempt is candidate_version) | no_change (nothing to learn or nothing changed) | failed (could not run) | applied (imported: applied without a check run)

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

An entry imported from the old Refine / Re-learn history

started_by
string | null

The id of the account that asked for it

started_by_name
string | null
details
ImprovementDetails · object

What the engine made of the words: for add_fields, the request diffed against the skill's contract (genuinely new fields, re-worded duplicates merged into an existing field, ones it could not place, asked back as a question); and what the learn pass did.

strategy
string | null

fields (re-learn where the fields live) | rerecord (re-do the steps)

target_fields
string[]
diagnosis
Diagnosis · object | null

The diagnosis the improvement started from

diagnosis_after
Diagnosis · object | null

The check run's diagnosis, when it still came back short

fields_before
Fields Before · object
fields_after
Fields After · object
changes
FieldChange · object[]

Target fields, before → after

improved
boolean | null
recipe_version_before
integer | null
recipe_version
integer | null

The live recipe version once done

candidate_version
integer | null

Set when the attempt was kept as a candidate, not made live

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