openapi: 3.1.0
info:
  title: JFrog Access REST Access Tokens Packages API
  description: API for managing users, groups, permissions, projects, and access tokens across the JFrog Platform. JFrog Access handles identity management, role-based access control, federated identity, and scoped token creation for authentication and authorization across all JFrog services.
  version: 2.x
  contact:
    name: JFrog
    url: https://jfrog.com
  license:
    name: Proprietary
    url: https://jfrog.com/terms-of-service/
  termsOfService: https://jfrog.com/terms-of-service/
servers:
- url: https://{server}.jfrog.io/access
  description: JFrog Cloud
  variables:
    server:
      default: myserver
      description: Your JFrog server name
- url: https://{host}/access
  description: Self-hosted JFrog instance
  variables:
    host:
      default: localhost:8082
      description: Your self-hosted JFrog server host
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Packages
  description: Package metadata search and retrieval
paths:
  /packages/search:
    post:
      operationId: searchPackages
      summary: JFrog Search Packages
      description: Searches for packages across the catalog using various filter criteria including name, type, version, and labels.
      tags:
      - Packages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageSearchRequest'
      responses:
        '200':
          description: Search results retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageSearchResponse'
        '400':
          description: Invalid search criteria
  /packages/{packageType}/{packageName}:
    get:
      operationId: getPackage
      summary: JFrog Get Package Details
      description: Returns detailed metadata for a specific package, including versions, licenses, vulnerabilities, and custom labels.
      tags:
      - Packages
      parameters:
      - name: packageType
        in: path
        required: true
        schema:
          type: string
          enum:
          - npm
          - maven
          - pypi
          - docker
          - go
          - nuget
          - gems
          - cargo
          - conda
          - composer
          - helm
          - cocoapods
          - pub
          - swift
          - rpm
          - debian
          - conan
        description: Package ecosystem type
      - name: packageName
        in: path
        required: true
        schema:
          type: string
        description: Package name (URL-encoded if contains special characters)
      responses:
        '200':
          description: Package details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageDetail'
        '404':
          description: Package not found
  /packages/{packageType}/{packageName}/versions:
    get:
      operationId: getPackageVersions
      summary: JFrog Get Package Versions
      description: Returns all known versions of a specific package with their associated metadata, vulnerability counts, and license information.
      tags:
      - Packages
      parameters:
      - name: packageType
        in: path
        required: true
        schema:
          type: string
        description: Package ecosystem type
      - name: packageName
        in: path
        required: true
        schema:
          type: string
        description: Package name
      - name: limit
        in: query
        schema:
          type: integer
          default: 25
        description: Maximum number of results
      - name: offset
        in: query
        schema:
          type: integer
        description: Pagination offset
      responses:
        '200':
          description: Package versions retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    items:
                      $ref: '#/components/schemas/PackageVersion'
                  total_count:
                    type: integer
  /packages/{packageType}/{packageName}/versions/{version}/vulnerabilities:
    get:
      operationId: getVersionVulnerabilities
      summary: JFrog Get Version Vulnerabilities
      description: Returns all known CVEs affecting a specific package version, including both direct (non-transitive) and transitive vulnerabilities.
      tags:
      - Packages
      parameters:
      - name: packageType
        in: path
        required: true
        schema:
          type: string
        description: Package ecosystem type
      - name: packageName
        in: path
        required: true
        schema:
          type: string
        description: Package name
      - name: version
        in: path
        required: true
        schema:
          type: string
        description: Package version
      - name: severity
        in: query
        schema:
          type: string
          enum:
          - Low
          - Medium
          - High
          - Critical
        description: Filter by minimum severity
      responses:
        '200':
          description: Vulnerabilities retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  vulnerabilities:
                    type: array
                    items:
                      $ref: '#/components/schemas/CatalogVulnerability'
                  total_count:
                    type: integer
components:
  schemas:
    PackageSummary:
      type: object
      properties:
        package_type:
          type: string
        package_name:
          type: string
        latest_version:
          type: string
        versions_count:
          type: integer
        vulnerabilities_count:
          type: integer
        labels:
          type: array
          items:
            type: string
        license:
          type: string
    PackageVersion:
      type: object
      properties:
        version:
          type: string
        published:
          type: string
          format: date-time
        licenses:
          type: array
          items:
            type: string
        vulnerabilities_count:
          type: integer
        direct_vulnerabilities_count:
          type: integer
          description: Non-transitive vulnerabilities affecting this version
        transitive_vulnerabilities_count:
          type: integer
          description: Transitive vulnerabilities from dependencies
        labels:
          type: array
          items:
            type: string
    PackageSearchRequest:
      type: object
      properties:
        query:
          type: string
          description: Text search query for package name
        package_type:
          type: string
          description: Filter by package type
        labels:
          type: array
          items:
            type: string
          description: Filter by applied labels
        has_vulnerabilities:
          type: boolean
          description: Filter packages with known vulnerabilities
        min_severity:
          type: string
          enum:
          - Low
          - Medium
          - High
          - Critical
          description: Minimum vulnerability severity filter
        limit:
          type: integer
          default: 25
        offset:
          type: integer
    CatalogVulnerability:
      type: object
      properties:
        cve:
          type: string
          description: CVE identifier
        severity:
          type: string
          enum:
          - Low
          - Medium
          - High
          - Critical
        cvss_v3_score:
          type: number
        summary:
          type: string
        is_transitive:
          type: boolean
          description: Whether this is a transitive vulnerability from a dependency
        fixed_versions:
          type: array
          items:
            type: string
        published:
          type: string
          format: date-time
        jfrog_research_severity:
          type: string
          description: JFrog Security Research team severity assessment
        jfrog_research_summary:
          type: string
          description: JFrog Security Research enrichment summary
    PackageDetail:
      type: object
      properties:
        package_type:
          type: string
        package_name:
          type: string
        description:
          type: string
        latest_version:
          type: string
        versions_count:
          type: integer
        licenses:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              full_name:
                type: string
              url:
                type: string
                format: uri
        vulnerabilities_summary:
          type: object
          properties:
            critical:
              type: integer
            high:
              type: integer
            medium:
              type: integer
            low:
              type: integer
            total:
              type: integer
        labels:
          type: array
          items:
            type: string
        repository_url:
          type: string
          format: uri
        homepage:
          type: string
          format: uri
    PackageSearchResponse:
      type: object
      properties:
        packages:
          type: array
          items:
            $ref: '#/components/schemas/PackageSummary'
        total_count:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access token authentication
    basicAuth:
      type: http
      scheme: basic
      description: Basic username/password authentication
externalDocs:
  description: JFrog Access REST API Documentation
  url: https://jfrog.com/help/r/jfrog-platform-administration-documentation/access-token-rest-api