> ## 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. # List a skill's change history > Every fix, added field, and re-learn of a skill, by anyone who can edit it and from any channel, plus past Refine and Re-learn changes. Newest first. ## OpenAPI ````yaml GET /v1/skills/{slug}/improvements 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}/improvements: get: tags: - Skill improvement summary: List a Skill's change history description: >- The Skill's full change history, newest first: every fix, added field and re-learn by anyone allowed to edit it (the owner or a workspace editor), from any channel (`source`), plus past Refine and Re-learn entries imported from before (`imported: true`, `result: applied`). operationId: listSkillImprovements parameters: - name: slug in: path required: true schema: type: string example: austin-dentists - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 50 default: 5 description: How many to return, 1–50. responses: '200': description: The Skill's change history, newest first. content: application/json: schema: type: object properties: improvements: type: array items: $ref: '#/components/schemas/SkillImprovementStatus' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - ApiKeyAuth: [] components: schemas: 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 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' 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 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' 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' 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.