> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valendata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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}`](/api-reference/skill-improvements/get) 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](/api-reference/skill-improvements/list). See [Improve a skill](/guides/web-to-api#5-improve-a-skill) for full examples.


## OpenAPI

````yaml POST /v1/skills/{slug}/improve
openapi: 3.0.3
info:
  title: Valendata REST API
  version: 1.0.0
  description: >-
    Trigger Skills, manage Workflows, retrieve Runs, and stream structured
    results from any language using JSON over HTTPS.
servers:
  - url: https://api.valendata.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Skills
    description: Execute and inspect published Skills.
  - name: Workflows
    description: Trigger multi-step Workflows and list them.
  - name: Runs
    description: Start async Skill runs and read Skill and Workflow run results.
  - name: Skill creation
    description: Create a Skill from a plain-language task.
  - name: Skill improvement
    description: >-
      Fix a Skill, add fields to it or re-learn its detail steps, poll the
      result, and read its change history.
  - name: Versions
    description: List, diff, restore, and pin a Skill's recipe versions.
  - name: Webhooks
    description: Signed delivery of finished async runs.
paths:
  /v1/skills/{slug}/improve:
    post:
      tags:
        - Skill improvement
      summary: Improve a Skill
      description: >-
        Change a Skill in one of three modes. `fix` (default): relearn it from a
        plain-English hint about where the data is. `add_fields`: capture new
        fields you describe in plain English; the request is first compared with
        the Skill's fields, so a re-worded duplicate is merged into the existing
        field and an unclear one comes back as a question. `relearn_details`:
        rebuild how the Skill opens each result (its per-row detail steps), for
        when the site changed or detail fields come back empty. Every mode runs
        on a cloud browser, saves a new recipe version and checks it with a
        short run (up to 5 rows). The new version stays live only if it is
        better; otherwise it is kept as a candidate and the previous recipe
        stays live. Owner or workspace editor only; drafts allowed. One
        improvement at a time per account and per Skill, up to 6 an hour, at
        least 10 credits to start. Charged to the caller.
      operationId: improveSkill
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          example: austin-dentists
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Retry-safe key. The same key from the same account returns what it
            already started.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImproveSkillRequest'
      responses:
        '202':
          description: >-
            Improvement started (or the existing one, for a repeated
            Idempotency-Key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillImprovementStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The Skill is already being improved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ImproveSkillRequest:
      type: object
      properties:
        mode:
          type: string
          enum:
            - fix
            - add_fields
            - relearn_details
          default: fix
          example: fix
          description: >-
            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.
        feedback:
          type: string
          minLength: 3
          maxLength: 2000
          example: >-
            The phone is on the details page — click the place name, the panel
            opens, the number is next to the phone icon.
          description: >-
            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`.
        fields:
          type: array
          items:
            type: string
          nullable: true
          example:
            - phone
          description: >-
            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`.
          maxItems: 10
        example_input:
          type: object
          nullable: true
          additionalProperties: true
          description: Inputs for the check run. Omit to use the recorded example.
    SkillImprovementStatus:
      type: object
      properties:
        improvement_id:
          type: string
          example: imp_3f9a1c2b7d4e5f60
        status:
          type: string
          enum:
            - queued
            - working
            - validating
            - done
            - failed
        status_url:
          type: string
          example: /v1/skill-improvements/imp_3f9a1c2b7d4e5f60
        skill_id:
          type: string
        slug:
          type: string
          nullable: true
        mode:
          type: string
          enum:
            - fix
            - add_fields
            - relearn_details
          description: The mode it ran in.
        source:
          type: string
          enum:
            - api
            - mcp
            - assistant
            - web
            - brain
            - imported
          description: >-
            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).
        started_by_name:
          type: string
          nullable: true
          description: The name of the person who started it.
        feedback:
          type: string
          nullable: true
        strategy:
          type: string
          nullable: true
          enum:
            - fields
            - rerecord
          description: '`fields`: relearn where the fields live. `rerecord`: redo the steps.'
        target_fields:
          type: array
          items:
            type: string
        diagnosis:
          allOf:
            - $ref: '#/components/schemas/Diagnosis'
          nullable: true
          description: The diagnosis it started from.
        diagnosis_after:
          allOf:
            - $ref: '#/components/schemas/Diagnosis'
          nullable: true
          description: The check run's diagnosis, when fields are still missing.
        fields_before:
          type: object
          additionalProperties:
            type: object
            properties:
              filled:
                type: integer
              total:
                type: integer
              rate:
                type: number
        fields_after:
          type: object
          additionalProperties:
            type: object
            properties:
              filled:
                type: integer
              total:
                type: integer
              rate:
                type: number
        changes:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              before:
                type: string
                example: 0/5
              after:
                type: string
                example: 5/5
              improved:
                type: boolean
        improved:
          type: boolean
          nullable: true
          description: >-
            True: the new version is live. False: kept as a candidate, the old
            recipe restored.
        result:
          type: string
          enum:
            - running
            - improved
            - kept_old
            - no_change
            - failed
            - applied
          description: >-
            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.
        imported:
          type: boolean
          description: True for a past Refine or Re-learn entry imported into this history.
        details:
          type: object
          nullable: true
          description: What the engine decided.
          properties:
            new_fields:
              type: array
              items:
                type: string
              description: Fields added (`add_fields`).
            merged:
              type: array
              description: >-
                Requested fields that were re-worded duplicates of existing
                ones, merged into them.
              items:
                type: object
                properties:
                  proposed:
                    type: string
                  into:
                    type: string
                  note:
                    type: string
            ambiguous:
              type: array
              description: >-
                Requested fields that were unclear and were not learned. Answer
                `question` and send a new request.
              items:
                type: object
                properties:
                  proposed:
                    type: string
                  candidates:
                    type: array
                    items:
                      type: string
                  question:
                    type: string
            diff_summary:
              type: string
              nullable: true
              description: One line on what changed in the recipe.
            engine_note:
              type: string
              nullable: true
              description: Any extra note from the engine.
        recipe_version_before:
          type: integer
          nullable: true
        recipe_version:
          type: integer
          nullable: true
          description: The live version when it ended.
        candidate_version:
          type: integer
          nullable: true
          description: The version kept but not made live.
        outcome:
          type: string
          nullable: true
        error:
          type: string
          nullable: true
        credits_charged:
          type: integer
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        idempotent_replay:
          type: boolean
    Error:
      type: object
      properties:
        detail:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            Error message. Usually a plain string; may be a structured object
            for some errors.
      example:
        detail: Invalid or expired API key
    Diagnosis:
      type: object
      description: >-
        Why a run, validation or creation came back short, and hints that could
        fix it with `POST /v1/skills/{slug}/improve`.
      properties:
        rows:
          type: integer
        missing_fields:
          type: array
          items:
            type: string
          description: Fields fewer than half the rows came back with.
        per_field:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldDiagnosis'
        triage_kind:
          type: string
          nullable: true
          example: missing_fields
        what_we_tried:
          type: array
          items:
            type: string
        suggested_hint_examples:
          type: array
          items:
            type: string
        error:
          type: string
          nullable: true
        summary:
          type: string
          example: 'phone: found on 0/5 rows — tried the result cards'
    FieldDiagnosis:
      type: object
      properties:
        filled:
          type: string
          example: 0/5
          description: Rows that had the field.
        filled_count:
          type: integer
        total:
          type: integer
        where_tried:
          type: array
          items:
            type: string
          example:
            - the result cards
            - each row's details page
        evidence:
          type: string
          example: blank on all 5 rows
  responses:
    Unauthorized:
      description: >-
        Unauthorized. The Authorization header is missing, malformed, or the
        credential is invalid or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: >-
        Not enough credits to start. `detail` includes `current_balance` and
        `required`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        Forbidden. You may not run or change this Skill, or it is not published
        or active.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found in your Workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unprocessable:
      description: >-
        Invalid request. For bad inputs, `detail` is `{message, errors,
        allowed_inputs}`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        Too many requests for this API key, too many runs in progress, or too
        many recordings in progress. Check the `Retry-After` header when
        present.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: vd_sk_...
      description: >-
        API key with the `vd_sk_` prefix. Create keys from Settings, API Keys in
        the dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.