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

# Update a skill

> Change a skill's name, description, inputs, output fields, run settings, saved login, or sharing.

Send only what you want to change. You get back the skill as [Get a skill](/api-reference/skills/get) returns it, plus `changes` (what changed, in words), `warnings`, and `login`.

| Key | What it changes |
| - | - |
| `name`, `description` | The skill's name and description. |
| `inputs` | `add` new inputs, `update` existing ones (`rename`, `type`, `default`, `required`, `description`), or `remove` some. |
| `outputs` | `update` output fields (`rename`, `description`, `type`) or `remove` them. |
| `default_max_results` | Rows a run returns when the caller does not say. `0` means all. |
| `browser_type`, `proxy_config`, `profile_id`, `scrape_mode` | How it runs by default. See [Run settings](/guides/run-a-skill#run-settings). |
| `data_retention_days` | How long run rows are kept, 1–90. |
| `login_id` | The [saved login](/concepts/logins-and-browser-profiles#saved-logins) it signs in with. `null` or `""` removes it. Needs `logins:write`. |
| `visibility`, `workspace_id` | `private` (only you) or `workspace` (shared with a team workspace; name it with `workspace_id` if you are in several). |

**Inputs and output fields.** Renaming one renames it in the skill's steps too. Removing an input the steps still use returns `422` naming the step. A new input with `recorded_value` (the value the recording typed or opened) replaces that value on each run; without it the input is added but changes nothing yet. A change to the steps becomes a new [version](/concepts/keeping-skills-working#versions).

To **add** output fields, use [Improve a skill](/api-reference/improvements/improve) with `mode: "add_fields"`: the skill has to learn where they are.

**Who.** The owner or a workspace editor. `login_id` and `visibility` are owner only, and a login is only used on the owner's own runs. Needs `skills:write`.

MCP tool: `update_skill`.


## OpenAPI

````yaml PATCH /v1/skills/{slug}
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}:
    patch:
      tags:
        - Skills
      summary: Update a skill
      description: >-
        Change a skill's name, description, inputs, output fields, run settings,
        saved login, or sharing. Only what you send changes. Answers with the
        skill as `GET /v1/skills/{slug}` returns it, plus `changes`, `warnings`,
        and `login`. Owner or workspace editor; `login_id` and `visibility` are
        owner only. Needs `skills:write` (and `logins:write` for `login_id`).
      operationId: update_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/SkillPatch'
      responses:
        '200':
          description: The skill after the change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillEditResult'
          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'
        '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:
    SkillPatch:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          title: Name
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Description
        inputs:
          anyOf:
            - $ref: '#/components/schemas/InputsPatch'
            - type: 'null'
        outputs:
          anyOf:
            - $ref: '#/components/schemas/OutputsPatch'
            - type: 'null'
        default_max_results:
          anyOf:
            - type: integer
              maximum: 500
              minimum: 0
            - type: 'null'
          title: Default Max Results
          description: Rows a run returns when the caller does not say; 0 = all
        browser_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Type
          description: '''remote'' | ''extension'' | ''none''; '''' clears it'
        proxy_config:
          anyOf:
            - type: string
            - type: 'null'
          title: Proxy Config
          description: >-
            'identity', 'residential', 'residential:<cc>', a country code,
            'random' or 'none'; null, '' or 'automatic' = automatic
        profile_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Profile Id
          description: The owner's browser profile id; '' removes it
        scrape_mode:
          anyOf:
            - type: string
            - type: 'null'
          title: Scrape Mode
          description: '''deep'' | ''flash''; '''' clears it'
        data_retention_days:
          anyOf:
            - type: integer
              maximum: 90
              minimum: 1
            - type: 'null'
          title: Data Retention Days
        login_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Login Id
          description: >-
            The owner's saved login; null or '' removes it (needs the
            logins:write scope)
        visibility:
          anyOf:
            - type: string
              enum:
                - private
                - workspace
            - type: 'null'
          title: Visibility
          description: >-
            private: only you. workspace: shared with a team workspace (owner
            only)
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
          description: >-
            With visibility=workspace: which team workspace (needed when you are
            in several)
      type: object
      title: SkillPatch
      description: >-
        Every key is optional; an absent key leaves that setting as it is. To
        ADD output

        fields, use POST /v1/skills/{slug}/improve with mode add_fields (the
        skill has to learn

        where they are).
    SkillEditResult:
      properties:
        id:
          type: string
          title: Id
        owner_id:
          type: string
          title: Owner Id
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
        name:
          type: string
          title: Name
        slug:
          type: string
          title: Slug
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        version:
          type: string
          title: Version
        visibility:
          $ref: '#/components/schemas/SkillVisibility'
        status:
          $ref: '#/components/schemas/SkillStatus'
        validation_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Validation Status
        validation_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Validation Reason
        validation_diagnosis:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Validation Diagnosis
        validated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Validated At
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        target_domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Domain
        parameters:
          items:
            $ref: '#/components/schemas/SkillParameter'
          type: array
          title: Parameters
        output_schema:
          additionalProperties: true
          type: object
          title: Output Schema
        sample_output:
          anyOf:
            - additionalProperties: true
              type: object
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Sample Output
        start_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Start Url
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
        tags:
          items:
            type: string
          type: array
          title: Tags
        rating:
          anyOf:
            - type: number
            - type: 'null'
          title: Rating
        user_rating:
          anyOf:
            - type: number
            - type: 'null'
          title: User Rating
        has_cloned:
          type: boolean
          title: Has Cloned
          default: false
        user_cloned_skill_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Cloned Skill Id
        total_runs:
          type: integer
          title: Total Runs
        total_clones:
          type: integer
          title: Total Clones
        is_official:
          type: boolean
          title: Is Official
        created_at:
          type: string
          format: date-time
          title: Created At
        published_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Published At
        update_frequency:
          type: string
          title: Update Frequency
          default: manual
        data_retention_days:
          type: integer
          title: Data Retention Days
          default: 90
        last_run_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Run At
        next_run_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Next Run At
        health_status:
          type: string
          title: Health Status
          default: unknown
        success_rate:
          type: number
          title: Success Rate
          default: 0
        last_run:
          anyOf:
            - $ref: '#/components/schemas/RunSummary'
            - type: 'null'
        running_run_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Running Run Id
        smart_suggestions:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Smart Suggestions
        enriched_fields:
          items:
            type: string
          type: array
          title: Enriched Fields
        expected_shapes:
          additionalProperties: true
          type: object
          title: Expected Shapes
        default_max_results:
          anyOf:
            - type: integer
            - type: 'null'
          title: Default Max Results
        default_max_pages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Default Max Pages
        browser_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Type
        profile_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Profile Id
        login_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Login Id
        skill_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Skill Type
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        proxy_config:
          anyOf:
            - type: string
            - type: 'null'
          title: Proxy Config
        scrape_mode:
          anyOf:
            - type: string
            - type: 'null'
          title: Scrape Mode
        scrape_mode_applies:
          type: boolean
          title: Scrape Mode Applies
          default: false
        creator_id:
          type: string
          title: Creator Id
        creator_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Creator Name
        creator_avatar_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Creator Avatar Url
        cloned_from_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Cloned From Id
        cloned_from_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Cloned From Name
        is_monetized:
          type: boolean
          title: Is Monetized
          default: false
        base_run_cost:
          type: integer
          title: Base Run Cost
          default: 0
        avg_duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Avg Duration Seconds
        clones_this_week:
          type: integer
          title: Clones This Week
          default: 0
        uses_remote_browser:
          type: boolean
          title: Uses Remote Browser
          default: false
        llm_model:
          type: string
          title: Llm Model
          default: GEMINI 3.5 FLASH
        total_ratings:
          type: integer
          title: Total Ratings
          default: 0
        rating_breakdown:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Rating Breakdown
        reviews:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Reviews
        api_endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Api Endpoint
        config_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Config Id
        health:
          anyOf:
            - $ref: '#/components/schemas/SkillHealth'
            - type: 'null'
        input_schema:
          additionalProperties: true
          type: object
          title: Input Schema
        output_json_schema:
          additionalProperties: true
          type: object
          title: Output Json Schema
        reliability:
          $ref: '#/components/schemas/SkillReliability'
        runs_endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Runs Endpoint
        recipe_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Recipe Version
        pinned_recipe_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Pinned Recipe Version
        versions_endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Versions Endpoint
        fast_path:
          anyOf:
            - type: string
            - type: 'null'
          title: Fast Path
        tiers:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Tiers
        login:
          anyOf:
            - $ref: '#/components/schemas/LoginOut'
            - type: 'null'
        changes:
          items:
            type: string
          type: array
          title: Changes
        warnings:
          items:
            type: string
          type: array
          title: Warnings
      type: object
      required:
        - id
        - owner_id
        - name
        - slug
        - description
        - version
        - visibility
        - status
        - parameters
        - output_schema
        - category
        - tags
        - total_runs
        - total_clones
        - is_official
        - created_at
        - published_at
        - creator_id
      title: SkillEditResult
      description: >-
        The skill after the edit (the GET /v1/skills/{slug} shape), and what
        changed.
    InputsPatch:
      properties:
        add:
          items:
            $ref: '#/components/schemas/InputAdd'
          type: array
          title: Add
        update:
          items:
            $ref: '#/components/schemas/InputUpdate'
          type: array
          title: Update
        remove:
          items:
            type: string
          type: array
          title: Remove
          description: Names to remove; refused while the recipe uses one
      type: object
      title: InputsPatch
    OutputsPatch:
      properties:
        update:
          items:
            $ref: '#/components/schemas/OutputUpdate'
          type: array
          title: Update
        remove:
          items:
            type: string
          type: array
          title: Remove
          description: Fields to stop returning
      type: object
      title: OutputsPatch
    SkillVisibility:
      type: string
      enum:
        - private
        - public
      title: SkillVisibility
      description: Skill visibility settings.
    SkillStatus:
      type: string
      enum:
        - draft
        - active
        - published
        - deprecated
      title: SkillStatus
      description: Skill lifecycle status.
    SkillParameter:
      properties:
        name:
          type: string
          title: Name
          description: Parameter name (used in URL/body)
        type:
          $ref: '#/components/schemas/ParameterType'
          default: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
          default: true
        default:
          anyOf:
            - {}
            - type: 'null'
          title: Default
        original_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Original Value
          description: >-
            The value recorded for this input; replay swaps this out for the
            caller's value
        is_auto_detected:
          type: boolean
          title: Is Auto Detected
          description: Whether this parameter was auto-detected from history
          default: false
      type: object
      required:
        - name
      title: SkillParameter
      description: A parameter that users can pass when executing the skill.
    RunSummary:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
      type: object
      required:
        - id
        - status
      title: RunSummary
      description: The last finished run of a skill or workflow, as a list row shows it.
    SkillHealth:
      properties:
        success_rate_20:
          anyOf:
            - type: number
            - type: 'null'
          title: Success Rate 20
        heals_20:
          type: integer
          title: Heals 20
          default: 0
        last_success_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Success At
        last_failure_kind:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Failure Kind
        recipe_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Recipe Version
        fast_path:
          anyOf:
            - $ref: '#/components/schemas/FastPath'
            - type: 'null'
        tiers:
          additionalProperties:
            $ref: '#/components/schemas/TierHealth'
          type: object
          title: Tiers
      type: object
      title: SkillHealth
    SkillReliability:
      properties:
        success_rate:
          type: number
          title: Success Rate
          default: 0
        health_status:
          type: string
          title: Health Status
          default: unknown
        total_runs:
          type: integer
          title: Total Runs
          default: 0
        last_run_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Run At
        success_rate_20:
          anyOf:
            - type: number
            - type: 'null'
          title: Success Rate 20
        heals_20:
          type: integer
          title: Heals 20
          default: 0
        last_success_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Success At
        last_failure_kind:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Failure Kind
      type: object
      title: SkillReliability
      description: >-
        Lifetime aggregates kept on the skill row (updated by every terminal
        run), plus the

        rolling window over the last 20 runs
        (app/published_skills/reliability.py).
    LoginOut:
      properties:
        id:
          type: string
          title: Id
        site:
          anyOf:
            - type: string
            - type: 'null'
          title: Site
        username_hint:
          type: string
          title: Username Hint
        label:
          type: string
          title: Label
        notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Notes
        has_totp:
          type: boolean
          title: Has Totp
          default: false
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - username_hint
        - label
        - created_at
        - updated_at
      title: LoginOut
      description: >-
        A saved login as every caller sees it: never the password, seed or a
        code.
    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.
    InputAdd:
      properties:
        name:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$
          title: Name
        type:
          type: string
          enum:
            - string
            - number
            - integer
            - boolean
          title: Type
          default: string
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Description
        default:
          title: Default
        required:
          type: boolean
          title: Required
          default: true
        recorded_value:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Recorded Value
          description: >-
            The value the recording typed or opened that this input replaces on
            each run. It must appear in the recipe. Without it the input is
            added but changes nothing yet.
      type: object
      required:
        - name
      title: InputAdd
    InputUpdate:
      properties:
        name:
          type: string
          title: Name
          description: The input's current name
        rename:
          anyOf:
            - type: string
              pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$
            - type: 'null'
          title: Rename
          description: New name; every use in the recipe is renamed too
        type:
          anyOf:
            - type: string
              enum:
                - string
                - number
                - integer
                - boolean
            - type: 'null'
          title: Type
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Description
        default:
          title: Default
          description: New default; null clears it (the input becomes required)
        required:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Required
      type: object
      required:
        - name
      title: InputUpdate
    OutputUpdate:
      properties:
        name:
          type: string
          title: Name
          description: The output field's current name
        rename:
          anyOf:
            - type: string
              pattern: ^[A-Za-z_][A-Za-z0-9_ \-]{0,63}$
            - type: 'null'
          title: Rename
          description: New name; its key is renamed in the recipe too
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Description
        type:
          anyOf:
            - type: string
              enum:
                - string
                - number
                - integer
                - boolean
                - array
                - object
            - type: 'null'
          title: Type
      type: object
      required:
        - name
      title: OutputUpdate
    ParameterType:
      type: string
      enum:
        - string
        - number
        - integer
        - boolean
      title: ParameterType
      description: Supported parameter types for skill inputs.
    FastPath:
      properties:
        tier:
          type: string
          title: Tier
        status:
          type: string
          title: Status
          default: healthy
        median_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Median Seconds
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - tier
      title: FastPath
    TierHealth:
      properties:
        attempts:
          type: integer
          title: Attempts
          default: 0
        ok:
          type: integer
          title: Ok
          default: 0
        success_rate:
          anyOf:
            - type: number
            - type: 'null'
          title: Success Rate
        median_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Median Seconds
        status:
          type: string
          title: Status
          default: healthy
      type: object
      title: TierHealth
  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
    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.