openapi: 3.2.0
info:
  title: Browser Use Public API v2 Skills Marketplace API
  summary: Browser Use API for running web agents (v2)
  version: 2.0.0
servers:
- url: https://api.browser-use.com/api/v2
  description: Production server
tags:
- name: Skills Marketplace
paths:
  /marketplace/skills:
    get:
      tags:
      - Skills Marketplace
      summary: List Skills
      description: List all public skills available in the marketplace with optional filtering.
      operationId: list_skills_marketplace_skills_get
      parameters:
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 10
          title: Pagesize
      - name: pageNumber
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Pagenumber
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Query
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SkillCategory'
          - type: 'null'
          title: Category
      - name: fromDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Fromdate
      - name: toDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Todate
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketplaceSkillListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /marketplace/skills/{skill_slug}:
    get:
      tags:
      - Skills Marketplace
      summary: Get Skill
      description: Get details of a specific public skill from the marketplace.
      operationId: get_skill_marketplace_skills__skill_slug__get
      parameters:
      - name: skill_slug
        in: path
        required: true
        schema:
          type: string
          title: Skill Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketplaceSkillResponse'
        '404':
          description: Skill not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillNotFoundError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /marketplace/skills/{skill_id}/clone:
    post:
      tags:
      - Skills Marketplace
      summary: Clone Skill
      description: Clone a public marketplace skill to the user's project.
      operationId: clone_skill_marketplace_skills__skill_id__clone_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: skill_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Skill Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillResponse'
        '404':
          description: Skill not found or no finished generation available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillNotFoundError'
        '400':
          description: Skill has no finished generation to clone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillNotFinishedError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /marketplace/skills/{skill_id}/execute:
    post:
      tags:
      - Skills Marketplace
      summary: Execute Skill
      description: Execute a skill with the provided parameters.
      operationId: execute_skill_marketplace_skills__skill_id__execute_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: skill_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Skill Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteSkillRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteSkillResponse'
        '404':
          description: Skill not found, no code available, or project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillNotFoundError'
        '400':
          description: Skill is not finished or not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillNotFinishedError'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ExecuteSkillRequest:
      properties:
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
          description: Parameters to pass to the skill handler
        sessionId:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Sessionid
          description: Optional session ID (UUID) for IP persistence.
      type: object
      title: ExecuteSkillRequest
      description: Request to execute a skill.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SkillNotFinishedError:
      properties:
        detail:
          type: string
          title: Detail
          default: Skill is not finished
      type: object
      title: SkillNotFinishedError
      description: Error response when skill is not finished
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SkillCategory:
      type: string
      enum:
      - search
      - e_commerce
      - financial
      - news
      - real_estate
      - social_media
      - travel
      - marketplace
      - lead_generation
      - seo
      - jobs
      - developer
      - media
      - automation
      - integration
      - other
      title: SkillCategory
      description: Skill category.
    ExecuteSkillResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the skill execution was successful
        result:
          anyOf:
          - {}
          - type: 'null'
          title: Result
          description: Output of the skill execution
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if the skill execution failed
        stderr:
          anyOf:
          - type: string
          - type: 'null'
          title: Stderr
          description: Standard error output of the skill execution
        latencyMs:
          anyOf:
          - type: integer
          - type: 'null'
          title: Latency in ms
          description: Latency of the skill execution in milliseconds
      type: object
      required:
      - success
      title: ExecuteSkillResponse
      description: Response from executing a skill.
    SkillResponse:
      properties:
        id:
          type: string
          format: uuid
          title: ID
          description: Unique identifier for the skill
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
          description: URL-friendly slug for the skill
        title:
          type: string
          title: Title
          description: Title of the skill (shows up in the public view)
        description:
          type: string
          title: Description
          description: Description of the skill (shows up in the public view)
        categories:
          items:
            $ref: '#/components/schemas/SkillCategory'
          type: array
          title: Categories
          description: Categories of the skill
        domains:
          items:
            type: string
          type: array
          title: Domains
          description: Domains/websites this skill interacts with
        goal:
          anyOf:
          - type: string
          - type: 'null'
          title: Goal
          description: Goal of the skill (not shown in the public view)
        agentPrompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Prompt
          description: Prompt for the agent to use when generating the skill automatically (not shown in the public view)
        status:
          $ref: '#/components/schemas/SkillsGenerationStatus'
          title: Status
          description: Status of the skill
        parameters:
          items:
            $ref: '#/components/schemas/ParameterSchema'
          type: array
          title: Parameters
          description: Input parameters of the skill
        outputSchema:
          additionalProperties: true
          type: object
          title: Output Schema
          description: Output schema of the skill
        isEnabled:
          type: boolean
          title: Enabled
          description: Whether the skill is enabled
        isPublic:
          type: boolean
          title: Is Public
          description: Whether the skill is publicly available
        iconUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon URL
          description: URL of the custom skill icon
        firstPublishedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: First Published At
          description: When the skill was first published
        lastPublishedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Published At
          description: When the skill was last published
        currentVersion:
          anyOf:
          - type: integer
          - type: 'null'
          title: Current Version
          description: Current version of the skill
        currentVersionStartedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Current Version Started At
          description: When the current version started generating
        currentVersionFinishedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Current Version Finished At
          description: When the current version finished generating
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code (base64 encoded) - ENTERPRISE ONLY
          description: Base64 encoded generated code (contact support@browser-use.com to get access) - ENTERPRISE ONLY
        clonedFromSkillId:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Cloned From Skill ID
          description: Unique identifier for the skill this skill was cloned from
        createdAt:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp
      type: object
      required:
      - id
      - title
      - description
      - categories
      - domains
      - status
      - parameters
      - outputSchema
      - isEnabled
      - isPublic
      - currentVersion
      - createdAt
      - updatedAt
      title: SkillResponse
      description: Skill information returned by the API.
    MarketplaceSkillResponse:
      properties:
        id:
          type: string
          format: uuid
          title: ID
          description: Unique identifier for the skill
        slug:
          type: string
          title: Slug
          description: URL-friendly slug for the skill
        title:
          type: string
          title: Title
          description: Title of the skill (shows up in the public view)
        description:
          type: string
          title: Description
          description: Description of the skill (shows up in the public view)
        categories:
          items:
            $ref: '#/components/schemas/SkillCategory'
          type: array
          title: Categories
          description: Categories of the skill
        domains:
          items:
            type: string
          type: array
          title: Domains
          description: Domains/websites this skill interacts with
        parameters:
          items:
            $ref: '#/components/schemas/ParameterSchema'
          type: array
          title: Parameters
          description: Input parameters of the skill
        outputSchema:
          additionalProperties: true
          type: object
          title: Output Schema
          description: Output schema of the skill
        currentVersion:
          anyOf:
          - type: integer
          - type: 'null'
          title: Current Version
          description: Current version of the skill
        isOfficial:
          type: boolean
          title: Is Official
          description: Whether the skill is official (verified by Browser Use)
        cloneCount:
          type: integer
          title: Clone Count
          description: Number of times this skill has been cloned
        iconUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon URL
          description: URL of the custom skill icon
        firstPublishedAt:
          type: string
          format: date-time
          title: First Published At
          description: When the skill was first published
        lastPublishedAt:
          type: string
          format: date-time
          title: Last Published At
          description: When the skill was last published
        createdAt:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp
      type: object
      required:
      - id
      - slug
      - title
      - description
      - categories
      - domains
      - parameters
      - outputSchema
      - currentVersion
      - isOfficial
      - cloneCount
      - firstPublishedAt
      - lastPublishedAt
      - createdAt
      - updatedAt
      title: MarketplaceSkillResponse
      description: Skill information returned by the API.
    ParameterSchema:
      properties:
        name:
          type: string
          title: Name
        type:
          $ref: '#/components/schemas/ParameterType'
        required:
          type: boolean
          title: Required
          default: true
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        default:
          anyOf:
          - {}
          - type: 'null'
          title: Default
        cookieDomain:
          anyOf:
          - type: string
          - type: 'null'
          title: Cookiedomain
      type: object
      required:
      - name
      - type
      title: ParameterSchema
      description: Schema for a skill parameter.
    InsufficientCreditsError:
      properties:
        detail:
          type: string
          title: Detail
          default: Insufficient credits
      type: object
      title: InsufficientCreditsError
      description: Error response when there are insufficient credits
    ParameterType:
      type: string
      enum:
      - string
      - number
      - boolean
      - object
      - array
      - cookie
      title: ParameterType
      description: Type of a skill parameter.
    MarketplaceSkillListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/MarketplaceSkillResponse'
          type: array
          title: Items
          description: List of skills
        totalItems:
          type: integer
          title: Total Items
          description: Total number of items in the list
        pageNumber:
          type: integer
          title: Page Number
          description: Page number
        pageSize:
          type: integer
          title: Page Size
          description: Number of items per page
      type: object
      required:
      - items
      - totalItems
      - pageNumber
      - pageSize
      title: MarketplaceSkillListResponse
      description: Response for listing skills.
    SkillsGenerationStatus:
      type: string
      enum:
      - recording
      - generating
      - failed
      - finished
      - cancelled
      - timed_out
      title: SkillsGenerationStatus
      description: Status of skill generation.
    SkillNotFoundError:
      properties:
        detail:
          type: string
          title: Detail
          default: Skill not found
      type: object
      title: SkillNotFoundError
      description: Error response when a skill is not found
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-Browser-Use-API-Key