> ## 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 fields, or re-learn how a skill opens each result. It goes live only if a check run shows it is better.

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](/api-reference/improvements/get) 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](/guides/improve-a-skill).

MCP tool: `improve_skill`.


## OpenAPI

````yaml POST /v1/skills/{slug}/improve
openapi: 3.1.0
info:
  title: Valendata REST API
  version: 1.0.0
  description: >-
    Create, run, schedule, and improve skills and workflows over JSON and HTTPS.
    Every route is under `/v1`; changes inside v1 are additive only (new routes,
    new optional parameters, new response fields). A route that will go away is
    marked `deprecated` here and answers with `Deprecation`, `Sunset` and a
    `Link` to its replacement for at least six months before it is removed.
    Errors, limits, pagination and idempotency:
    https://docs.valendata.com/api-reference/errors.
  license:
    name: Proprietary
    url: https://www.valendata.com/terms-and-conditions
servers:
  - url: https://api.valendata.com
    description: Production
security:
  - ApiKeyAuth: []
  - ApiKeyHeader: []
tags:
  - name: Skills
    description: List, create, read, update, and delete skills.
  - name: Runs
    description: Run skills and workflows, read any run, and cancel one.
  - name: Skill versions
    description: List, compare, restore, and pin a skill's versions.
  - name: Improvements
    description: >-
      Fix a skill, add fields, or re-learn its detail steps, and read its change
      history.
  - name: Schedules
    description: Run a skill or workflow on a fixed cadence.
  - name: Workflows
    description: List, create, read, update, and delete workflows.
  - name: Logins
    description: Saved website logins a skill can sign in with.
  - name: Account and usage
    description: Your plan, credit balance, and usage.
  - name: Webhooks
    description: The secret that signs webhook deliveries.
paths:
  /v1/skills/{slug}/improve:
    post:
      tags:
        - Improvements
      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: improve_skill
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            title: Slug
          example: austin-dentists
        - $ref: '#/components/parameters/IdempotencyKey'
      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'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - ApiKeyAuth: []
        - ApiKeyHeader: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 255
      description: >-
        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`.
      example: order-1234
  schemas:
    ImproveSkillRequest:
      properties:
        mode:
          type: string
          enum:
            - fix
            - add_fields
            - relearn_details
          title: Mode
          description: >-
            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.
          default: fix
        feedback:
          type: string
          maxLength: 2000
          title: Feedback
          description: >-
            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.
          default: ''
        fields:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Fields
          description: >-
            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:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Example Input
          description: >-
            Inputs for the check run (max 5 rows) that proves the improvement.
            Omit to use the skill's recorded example.
        browser_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Type
          description: >-
            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.
      type: object
      title: ImproveSkillRequest
      description: >-
        What to change, in plain English, the way you would coach a person doing
        the task.
    SkillImprovementStatus:
      properties:
        improvement_id:
          type: string
          title: Improvement Id
        status:
          type: string
          title: Status
        status_url:
          type: string
          title: Status Url
        skill_id:
          type: string
          title: Skill Id
        slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Slug
        mode:
          type: string
          enum:
            - fix
            - add_fields
            - relearn_details
          title: Mode
          default: fix
        source:
          type: string
          title: Source
          description: >-
            Who asked: api | mcp | assistant (Igris) | web | brain (workflow
            Brain) | imported (from the old Refine history)
          default: api
        result:
          type: string
          enum:
            - running
            - improved
            - kept_old
            - no_change
            - failed
            - applied
          title: Result
          description: >-
            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)
          default: running
        imported:
          type: boolean
          title: Imported
          description: An entry imported from the old Refine / Re-learn history
          default: false
        started_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Started By
          description: The id of the account that asked for it
        started_by_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Started By Name
        feedback:
          type: string
          title: Feedback
        details:
          $ref: '#/components/schemas/ImprovementDetails'
        strategy:
          anyOf:
            - type: string
            - type: 'null'
          title: Strategy
          description: fields (re-learn where the fields live) | rerecord (re-do the steps)
        target_fields:
          items:
            type: string
          type: array
          title: Target Fields
        diagnosis:
          anyOf:
            - $ref: '#/components/schemas/Diagnosis'
            - type: 'null'
          description: The diagnosis the improvement started from
        diagnosis_after:
          anyOf:
            - $ref: '#/components/schemas/Diagnosis'
            - type: 'null'
          description: The check run's diagnosis, when it still came back short
        fields_before:
          additionalProperties:
            $ref: '#/components/schemas/FieldFill'
          type: object
          title: Fields Before
        fields_after:
          additionalProperties:
            $ref: '#/components/schemas/FieldFill'
          type: object
          title: Fields After
        changes:
          items:
            $ref: '#/components/schemas/FieldChange'
          type: array
          title: Changes
          description: Target fields, before → after
        improved:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Improved
        recipe_version_before:
          anyOf:
            - type: integer
            - type: 'null'
          title: Recipe Version Before
        recipe_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Recipe Version
          description: The live recipe version once done
        candidate_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Candidate Version
          description: Set when the attempt was kept as a candidate, not made live
        outcome:
          anyOf:
            - type: string
            - type: 'null'
          title: Outcome
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        credits_charged:
          type: integer
          title: Credits Charged
          default: 0
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
        idempotent_replay:
          type: boolean
          title: Idempotent Replay
          default: false
      type: object
      required:
        - improvement_id
        - status
        - status_url
        - skill_id
        - feedback
      title: SkillImprovementStatus
      description: >-
        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.
    ImprovementDetails:
      properties:
        new_fields:
          items:
            type: string
          type: array
          title: New Fields
        merged:
          items:
            $ref: '#/components/schemas/MergedField'
          type: array
          title: Merged
        ambiguous:
          items:
            $ref: '#/components/schemas/AmbiguousField'
          type: array
          title: Ambiguous
        diff_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Diff Summary
        engine_note:
          anyOf:
            - type: string
            - type: 'null'
          title: Engine Note
        browser_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Type
          description: 'The browser it learned and checked on: remote | extension'
      type: object
      title: ImprovementDetails
      description: >-
        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.
    Diagnosis:
      properties:
        rows:
          type: integer
          title: Rows
          default: 0
        missing_fields:
          items:
            type: string
          type: array
          title: Missing Fields
          description: Contract fields fewer than half the rows came back with.
        partial_fields:
          items:
            type: string
          type: array
          title: Partial Fields
          description: >-
            Fields filled on at least half the rows but not all, whose blank
            rows the page capture explained (see per_field severity/note).
        per_field:
          additionalProperties:
            $ref: '#/components/schemas/FieldDiagnosis'
          type: object
          title: Per Field
          description: 'Every field some rows lacked: fill, where it was tried, evidence.'
        triage_kind:
          anyOf:
            - type: string
            - type: 'null'
          title: Triage Kind
          description: >-
            missing_fields | partial_fields | not_shown | suspect_rows |
            element_changed | extraction_drift | blocked | logged_out |
            login_failed | site_down | page_not_loaded | recording_failed |
            unknown
        what_we_tried:
          items:
            type: string
          type: array
          title: What We Tried
        suggested_hint_examples:
          items:
            type: string
          type: array
          title: Suggested Hint Examples
          description: Example plain-English hints for improve_skill.
        quality_flags:
          items:
            $ref: '#/components/schemas/QualityFlag'
          type: array
          title: Quality Flags
          description: >-
            Single-run row checks that fired: repeated rows, pages repeating
            earlier pages, placeholder values.
        no_real_rows:
          type: boolean
          title: No Real Rows
          description: >-
            Rows came back but every field was empty on every one — the run
            never reached the results.
          default: false
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        summary:
          type: string
          title: Summary
          description: >-
            One readable line, e.g. 'phone: found on 0/5 rows — tried the result
            cards'.
          default: ''
      type: object
      title: Diagnosis
      description: >-
        Why the run came back short, and what a hint could say to fix it (POST
        /v1/skills/{slug}/improve).
    FieldFill:
      properties:
        filled:
          type: integer
          title: Filled
          default: 0
        total:
          type: integer
          title: Total
          default: 0
        rate:
          type: number
          title: Rate
          default: 0
      type: object
      title: FieldFill
    FieldChange:
      properties:
        field:
          type: string
          title: Field
        before:
          type: string
          title: Before
          description: e.g. '0/5'
        after:
          type: string
          title: After
          description: e.g. '5/5'
        improved:
          type: boolean
          title: Improved
          default: false
      type: object
      required:
        - field
        - before
        - after
      title: FieldChange
    Error:
      type: object
      required:
        - detail
        - code
        - type
        - request_id
      properties:
        detail:
          description: What went wrong. A string, or an object for errors with more to say.
          oneOf:
            - type: string
            - additionalProperties: true
              type: object
        code:
          type: string
          description: >-
            Stable machine-readable code. Known values: `bad_request`,
            `invalid_json`, `invalid_cursor`, `invalid_idempotency_key`,
            `unauthorized`, `payment_required`, `permission_denied`,
            `not_found`, `method_not_allowed`, `conflict`,
            `idempotency_key_in_use`, `idempotent_replay_unavailable`,
            `payload_too_large`, `unsupported_media_type`, `validation_error`,
            `idempotency_key_reused`, `rate_limited`, `internal_error`,
            `upstream_error`, `service_unavailable`.
          example: not_found
        type:
          type: string
          enum:
            - invalid_request_error
            - authentication_error
            - billing_error
            - permission_error
            - conflict_error
            - idempotency_error
            - rate_limit_error
            - api_error
          description: The broad category of the error.
        request_id:
          type: string
          description: Also in the `X-Request-ID` header.
          example: 3f9a1c2b7d4e
        param:
          type: string
          description: >-
            The field at fault, on validation errors (dotted path, e.g.
            `inputs.city`).
        errors:
          type: array
          items:
            additionalProperties: true
            type: object
          description: Every validation problem, on a 422 from request validation.
    MergedField:
      properties:
        proposed:
          type: string
          title: Proposed
        into:
          type: string
          title: Into
        note:
          anyOf:
            - type: string
            - type: 'null'
          title: Note
      type: object
      required:
        - proposed
        - into
      title: MergedField
    AmbiguousField:
      properties:
        proposed:
          type: string
          title: Proposed
        candidates:
          items:
            type: string
          type: array
          title: Candidates
        question:
          type: string
          title: Question
      type: object
      required:
        - proposed
        - question
      title: AmbiguousField
    FieldDiagnosis:
      properties:
        filled:
          type: string
          title: Filled
          description: Rows that got the field, e.g. '0/5'.
        filled_count:
          type: integer
          title: Filled Count
          default: 0
        total:
          type: integer
          title: Total
          default: 0
        where_tried:
          items:
            type: string
          type: array
          title: Where Tried
          description: >-
            Where the recipe looked, e.g. 'the result cards', "each row's
            details page".
        evidence:
          type: string
          title: Evidence
          default: ''
        not_shown:
          anyOf:
            - type: integer
            - type: 'null'
          title: Not Shown
          description: >-
            Blank rows whose result card shows no value for the field at all
            (e.g. a sponsored card) — not a read the skill missed. Null when it
            could not be told.
        shown_unread:
          anyOf:
            - type: integer
            - type: 'null'
          title: Shown Unread
          description: >-
            Blank rows whose result card DOES show a value — a read the skill
            missed. Set on partial fields (filled on at least half the rows) the
            page capture could speak for.
        severity:
          anyOf:
            - type: string
            - type: 'null'
          title: Severity
          description: >-
            Partial fields only: warn (on the card but not read on some rows — a
            hint can fix it) | info (the blank rows' cards show no value —
            nothing to fix).
        note:
          anyOf:
            - type: string
            - type: 'null'
          title: Note
          description: >-
            Partial fields only, e.g. 'filled on 3/5 — on the card but not read
            on 2' or 'filled on 3/5 — not shown on 2 rows' cards'.
      type: object
      required:
        - filled
      title: FieldDiagnosis
    QualityFlag:
      properties:
        kind:
          type: string
          title: Kind
          description: repeated_rows | pagination_overlap | placeholder_values
        severity:
          type: string
          title: Severity
          description: fail (the output is not data; a validation rejects it) | warn
          default: warn
        message:
          type: string
          title: Message
          default: ''
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
      type: object
      required:
        - kind
      title: QualityFlag
      description: A single-run row check that fired (row_checks.py).
  headers:
    X-Request-ID:
      description: >-
        This request's id (yours, if you sent a valid `X-Request-ID`). Quote it
        to support.
      schema:
        type: string
    X-RateLimit-Limit:
      description: Requests a minute this API key may make.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current minute.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix time (seconds) the current window ends.
      schema:
        type: integer
    Idempotent-Replayed:
      description: >-
        `true` when this is the stored answer to an earlier request with the
        same Idempotency-Key.
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    BadRequest:
      description: >-
        The request is malformed: the body is not JSON, the cursor or
        Idempotency-Key is not valid.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              The request is malformed: the body is not JSON, the cursor or
              Idempotency-Key is not valid.
            code: invalid_json
            type: invalid_request_error
            request_id: 3f9a1c2b7d4e
    Unauthorized:
      description: The API key is missing, malformed, revoked, or expired.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: The API key is missing, malformed, revoked, or expired.
            code: unauthorized
            type: authentication_error
            request_id: 3f9a1c2b7d4e
    PaymentRequired:
      description: >-
        Not enough credits to start. `detail` includes `current_balance` and
        `required`.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              Not enough credits to start. `detail` includes `current_balance`
              and `required`.
            code: payment_required
            type: billing_error
            request_id: 3f9a1c2b7d4e
    Forbidden:
      description: >-
        The key lacks a scope, is limited to other skills or workflows, or you
        may not do this.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              The key lacks a scope, is limited to other skills or workflows, or
              you may not do this.
            code: permission_denied
            type: permission_error
            request_id: 3f9a1c2b7d4e
    NotFound:
      description: It does not exist, or it is not yours to see.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: It does not exist, or it is not yours to see.
            code: not_found
            type: invalid_request_error
            request_id: 3f9a1c2b7d4e
    Conflict:
      description: >-
        A conflict with the current state, or a request with this
        Idempotency-Key is still running.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              A conflict with the current state, or a request with this
              Idempotency-Key is still running.
            code: conflict
            type: conflict_error
            request_id: 3f9a1c2b7d4e
    Unprocessable:
      description: >-
        A field is invalid (`param` names it), or the Idempotency-Key was used
        with a different request.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: 'Invalid request — name: Field required'
            code: validation_error
            type: invalid_request_error
            request_id: 3f9a1c2b7d4e
            param: name
            errors:
              - type: missing
                loc:
                  - body
                  - name
                msg: Field required
    RateLimited:
      description: >-
        Too many requests for this key, or too many runs in progress. Wait
        `Retry-After` seconds.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              Too many requests for this key, or too many runs in progress. Wait
              `Retry-After` seconds.
            code: rate_limited
            type: rate_limit_error
            request_id: 3f9a1c2b7d4e
    InternalError:
      description: >-
        Something broke on our side. Retry; runs that fail on our side are
        refunded.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              Something broke on our side. Retry; runs that fail on our side are
              refunded.
            code: internal_error
            type: api_error
            request_id: 3f9a1c2b7d4e
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: vd_sk_...
      description: >-
        API key with the `vd_sk_` prefix, as `Authorization: Bearer vd_sk_...`.
        Create keys in Settings → API Keys.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: The same API key in the `x-api-key` header.

````

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