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

# Create a skill from a task

> Record a plain-language task in a cloud browser and publish it as a typed, versioned skill. Answers at once with a creation id to poll.

Recording usually takes a few minutes. Poll [`GET /v1/skill-creations/{creation_id}`](/api-reference/skill-creations/get) until `status` is `ready` or `failed`. See [Create a skill from a task](/guides/web-to-api#1-create-a-skill-from-a-task) for a full example.


## OpenAPI

````yaml POST /v1/skills
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:
    post:
      tags:
        - Skill creation
      summary: Create a Skill from a task
      description: >-
        Record `task` in a cloud browser from `start_url` and publish it as a
        Skill. Answers at once with a creation id; poll `GET
        /v1/skill-creations/{creation_id}`. Up to 2 recordings in progress per
        account; needs at least 10 credits. Recordings cannot sign in to
        websites.
      operationId: createSkillFromTask
      parameters:
        - 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/CreateSkillRequest'
      responses:
        '202':
          description: >-
            Creation started (or the existing one, for a repeated
            Idempotency-Key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillCreationStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateSkillRequest:
      type: object
      required:
        - task
        - start_url
      properties:
        task:
          type: string
          minLength: 3
          maxLength: 2000
          description: What the skill does, in plain words.
          example: Search for dentists in Austin and list them
        start_url:
          type: string
          maxLength: 2000
          description: The http(s) page the skill starts on.
          example: https://www.google.com/maps
        name:
          type: string
          maxLength: 100
          description: Skill name. Derived from the task when omitted.
        inputs:
          type: object
          additionalProperties:
            type: string
          maxProperties: 5
          description: >-
            Up to 5 inputs, each mapped to the example value the recording uses.
            Each value must appear in what the browser types or opens. Inferred
            when omitted.
          example:
            city: Austin
        output_fields:
          oneOf:
            - type: object
              additionalProperties:
                type: string
            - type: array
              items:
                type: string
          description: >-
            Up to 25 columns, as `{name: description}` or a list of names.
            Inferred when omitted.
          example:
            name: business name
            rating: star rating
            phone: phone number
        visibility:
          type: string
          enum:
            - private
            - public
          default: private
    SkillCreationStatus:
      type: object
      properties:
        creation_id:
          type: string
          example: sc_3f9a1c2b7d4e5f60
        status:
          type: string
          enum:
            - queued
            - recording
            - validating
            - ready
            - failed
        status_url:
          type: string
          example: /v1/skill-creations/sc_3f9a1c2b7d4e5f60
        skill_id:
          type: string
          nullable: true
          description: Set once the recording is saved.
        slug:
          type: string
          nullable: true
          description: Set once the recording is saved.
        skill_url:
          type: string
          nullable: true
          description: '`/v1/skills/{slug}` once saved.'
        run_url:
          type: string
          nullable: true
          description: '`/v1/skills/{slug}/run` once ready.'
        error:
          type: string
          nullable: true
          description: Why it failed.
        inputs:
          type: object
          nullable: true
          additionalProperties:
            type: string
        output_fields:
          type: object
          nullable: true
          additionalProperties:
            type: string
        credits_charged:
          type: integer
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
        idempotent_replay:
          type: boolean
          description: True when an Idempotency-Key matched an existing creation.
        diagnosis:
          allOf:
            - $ref: '#/components/schemas/Diagnosis'
          nullable: true
          description: 'On failure: what was tried and example hints.'
    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'
    PaymentRequired:
      description: >-
        Not enough credits to start. `detail` includes `current_balance` and
        `required`.
      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.