openapi: 3.0.3
info:
  title: Packagist 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
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 }
  /search.json:
    get:
      operationId: searchPackages
      summary: Search Packages
      description: Search Packagist by name, tag, or type. Results are paginated.
      tags: [Search]
      parameters:
      - name: q
        in: query
        description: Free-text search query.
        schema: { type: string }
      - name: tags
        in: query
        description: Filter results by tag.
        schema: { type: string }
      - name: type
        in: query
        description: Filter results by Composer package type.
        schema: { type: string }
      - name: per_page
        in: query
        description: Results per page (default 15, max 100).
        schema: { type: integer, default: 15, maximum: 100 }
      - name: page
        in: query
        description: Page number.
        schema: { type: integer, default: 1 }
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items: { $ref: '#/components/schemas/PackageSummary' }
                  total: { type: integer }
                  next: { 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' }
  /p2/{vendor}/{package}.json:
    get:
      operationId: getPackageMetadataV2
      summary: Get Package Metadata (Composer v2)
      description: |
        Static Composer v2 metadata. Preferred endpoint for dependency resolvers — served
        from repo.packagist.org with long-lived caching.
      tags: [Metadata]
      parameters:
      - { name: vendor, in: path, required: true, schema: { type: string } }
      - { name: package, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Composer v2 package metadata.
  /p2/{vendor}/{package}~dev.json:
    get:
      operationId: getPackageMetadataV2Dev
      summary: Get Package Dev Metadata (Composer v2)
      description: Composer v2 metadata for dev branches (development releases).
      tags: [Metadata]
      parameters:
      - { name: vendor, in: path, required: true, schema: { type: string } }
      - { name: package, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Composer v2 dev metadata.
  /packages/{vendor}/{package}/stats.json:
    get:
      operationId: getPackageStats
      summary: Get Package Download Statistics
      description: Get per-version and aggregate download statistics for a package.
      tags: [Statistics]
      parameters:
      - { name: vendor, in: path, required: true, schema: { type: string } }
      - { name: package, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Download statistics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  downloads: { $ref: '#/components/schemas/DownloadStats' }
                  versions:
                    type: object
                    additionalProperties: { type: integer }
  /metadata/changes.json:
    get:
      operationId: getMetadataChanges
      summary: Get Metadata Changes
      description: Stream package metadata changes since a given timestamp. Retained for 24 hours only.
      tags: [Metadata]
      parameters:
      - name: since
        in: query
        description: Unix timestamp (milliseconds) to fetch changes since.
        schema: { type: integer, format: int64 }
      responses:
        '200':
          description: List of metadata changes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  actions:
                    type: array
                    items:
                      type: object
                      properties:
                        type: { type: string, enum: [update, delete] }
                        package: { type: string }
                        time: { type: integer, format: int64 }
                  timestamp: { type: integer, format: int64 }
  /statistics.json:
    get:
      operationId: getStatistics
      summary: Get Global Statistics
      description: Aggregate Packagist statistics — total packages, total versions, total installs.
      tags: [Statistics]
      responses:
        '200':
          description: Global statistics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totals:
                    type: object
                    properties:
                      packages: { type: integer }
                      versions: { type: integer }
                      installs: { type: integer, format: int64 }
  /api/security-advisories/:
    get:
      operationId: getSecurityAdvisories
      summary: Get Security Advisories
      description: Look up security advisories that apply to one or more packages.
      tags: [Security]
      parameters:
      - name: packages[]
        in: query
        description: One or more package names to check.
        schema:
          type: array
          items: { type: string }
      - name: updatedSince
        in: query
        description: Only return advisories updated since this Unix timestamp.
        schema: { type: integer, format: int64 }
      responses:
        '200':
          description: Security advisories for the given packages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  advisories:
                    type: object
                    additionalProperties:
                      type: array
                      items: { $ref: '#/components/schemas/SecurityAdvisory' }
  /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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: "username:apiToken"
  schemas:
    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 }
    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 }
    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 }
    DownloadStats:
      type: object
      properties:
        total: { type: integer }
        monthly: { type: integer }
        daily: { type: integer }
    SecurityAdvisory:
      type: object
      properties:
        advisoryId: { type: string }
        packageName: { type: string }
        remoteId: { type: string }
        title: { type: string }
        link: { type: string, format: uri }
        cve: { type: string }
        affectedVersions: { type: string }
        source: { type: string }
        reportedAt: { type: string, format: date-time }
        composerRepository: { type: string }
        severity: { type: string }
tags:
- name: Packages
  description: Discover and manage Composer packages.
- name: Metadata
  description: Composer v2 static metadata and change tracking.
- name: Search
  description: Search the Packagist registry.
- name: Statistics
  description: Download and registry statistics.
- name: Security
  description: PHP security advisory database.