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.