openapi: 3.0.3
info:
  title: Packagist Metadata Packages API
  description: 'The Packagist API exposes the PHP Composer package registry. Use it to list, search,

    and inspect packages; retrieve Composer v2 metadata for resolvers; track changes;

    fetch download statistics; query the security advisory database; and create or

    update package entries (authenticated).

    '
  version: '1.0'
  contact:
    name: Packagist
    url: https://packagist.org
  license:
    name: MIT
    url: https://github.com/composer/packagist/blob/main/LICENSE
servers:
- url: https://packagist.org
  description: Packagist Application API
- url: https://repo.packagist.org
  description: Composer v2 Static Metadata Mirror
tags:
- name: Packages
  description: Discover and manage Composer packages.
paths:
  /packages/list.json:
    get:
      operationId: listPackages
      summary: List Packages
      description: List all packages, optionally filtered by vendor or type.
      tags:
      - Packages
      parameters:
      - name: vendor
        in: query
        description: Filter by vendor name.
        schema:
          type: string
      - name: type
        in: query
        description: Filter by Composer package type (library, project, metapackage, composer-plugin).
        schema:
          type: string
      - name: fields[]
        in: query
        description: Extra fields to include for each package.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: A list of package names.
          content:
            application/json:
              schema:
                type: object
                properties:
                  packageNames:
                    type: array
                    items:
                      type: string
  /explore/popular.json:
    get:
      operationId: getPopularPackages
      summary: Get Popular Packages
      description: Get the most popular packages ranked by recent weekly downloads.
      tags:
      - Packages
      parameters:
      - name: per_page
        in: query
        schema:
          type: integer
          default: 15
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: A page of popular packages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  packages:
                    type: array
                    items:
                      $ref: '#/components/schemas/PackageSummary'
  /packages/{vendor}/{package}.json:
    get:
      operationId: getPackage
      summary: Get Package
      description: Retrieve full package data including all versions, maintainers, downloads, and dependents. Cached for 12 hours.
      tags:
      - Packages
      parameters:
      - name: vendor
        in: path
        required: true
        schema:
          type: string
      - name: package
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Full package payload.
          content:
            application/json:
              schema:
                type: object
                properties:
                  package:
                    $ref: '#/components/schemas/Package'
  /api/create-package:
    post:
      operationId: createPackage
      summary: Create Package
      description: Submit a new package by its source repository URL.
      tags:
      - Packages
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - repository
              properties:
                repository:
                  type: object
                  required:
                  - url
                  properties:
                    url:
                      type: string
                      format: uri
      responses:
        '202':
          description: Package accepted for indexing.
        '401':
          description: Unauthorized.
  /api/packages/{package}:
    put:
      operationId: editPackage
      summary: Edit Package URL
      description: Update the source repository URL of an existing package.
      tags:
      - Packages
      security:
      - bearerAuth: []
      parameters:
      - name: package
        in: path
        required: true
        description: Full package name (vendor/package).
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - repository
              properties:
                repository:
                  type: object
                  required:
                  - url
                  properties:
                    url:
                      type: string
                      format: uri
      responses:
        '200':
          description: Package URL updated.
  /api/update-package:
    post:
      operationId: updatePackage
      summary: Update Package Metadata
      description: Trigger a re-crawl of a package's repository to refresh its metadata. SAFE token sufficient.
      tags:
      - Packages
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - repository
              properties:
                repository:
                  type: object
                  required:
                  - url
                  properties:
                    url:
                      type: string
                      format: uri
      responses:
        '202':
          description: Update queued.
components:
  schemas:
    DownloadStats:
      type: object
      properties:
        total:
          type: integer
        monthly:
          type: integer
        daily:
          type: integer
    PackageVersion:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        keywords:
          type: array
          items:
            type: string
        homepage:
          type: string
        version:
          type: string
        version_normalized:
          type: string
        license:
          type: array
          items:
            type: string
        authors:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              email:
                type: string
              homepage:
                type: string
              role:
                type: string
        source:
          type: object
          properties:
            type:
              type: string
            url:
              type: string
            reference:
              type: string
        dist:
          type: object
          properties:
            type:
              type: string
            url:
              type: string
            reference:
              type: string
            shasum:
              type: string
        type:
          type: string
        time:
          type: string
          format: date-time
        autoload:
          type: object
        require:
          type: object
          additionalProperties:
            type: string
        require-dev:
          type: object
          additionalProperties:
            type: string
    Package:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        time:
          type: string
          format: date-time
        maintainers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              avatar_url:
                type: string
                format: uri
        versions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PackageVersion'
        type:
          type: string
        repository:
          type: string
          format: uri
        github_stars:
          type: integer
        github_watchers:
          type: integer
        github_forks:
          type: integer
        github_open_issues:
          type: integer
        language:
          type: string
        downloads:
          $ref: '#/components/schemas/DownloadStats'
        favers:
          type: integer
        dependents:
          type: integer
        suggesters:
          type: integer
    PackageSummary:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        repository:
          type: string
          format: uri
        downloads:
          type: integer
        favers:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: username:apiToken