API Reference

Pricore provides a Composer-compatible API for package distribution and webhook endpoints for automatic syncing.

Authentication

The Composer API requires authentication via access token. Two methods are supported:

HTTP Basic Auth

Use token as the username and your access token as the password:

curl -u "token:YOUR_ACCESS_TOKEN" https://pricore.yourcompany.com/your-org/packages.json

Authorization Header

Alternatively, use the Bearer token format:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://pricore.yourcompany.com/your-org/packages.json

Composer Repository API

These endpoints implement the Composer v2 Repository specification.

Get Package List

Returns the root configuration for an organization's Composer repository.

GET /{organization}/packages.json

Response:

{
    "metadata-url": "https://pricore.yourcompany.com/your-org/p2/%package%.json",
    "available-packages": ["acme/billing", "acme/utils"],
    "notify-batch": "https://pricore.yourcompany.com/your-org/notify-batch"
}

Field	Description
metadata-url	URL template Composer uses to resolve individual package metadata
available-packages	Exhaustive list of packages in this repository — lets Composer skip unnecessary metadata lookups for packages that don't exist here
notify-batch	URL where Composer sends download notifications after installing packages

Responses include caching headers (Cache-Control, ETag, Last-Modified). Clients can send If-None-Match with a previously received ETag to receive a 304 Not Modified response when content hasn't changed.

Get Package Metadata (Stable)

Returns metadata for all stable versions of a specific package.

GET /{organization}/p2/{vendor}/{package}.json

Response:

{
    "packages": {
        "vendor/package-name": [
            {
                "name": "vendor/package-name",
                "version": "1.0.0",
                "version_normalized": "1.0.0.0",
                "type": "library",
                "require": {
                    "php": "^8.2"
                },
                "autoload": {
                    "psr-4": {
                        "Vendor\\Package\\": "src/"
                    }
                }
            }
        ]
    },
    "minified": "composer/2.0"
}

Responses use minified metadata ("minified": "composer/2.0") per the Composer 2 spec — only the first version entry contains all keys; subsequent entries omit keys whose values match the previous entry, reducing payload size.

Responses include caching headers (Cache-Control, ETag, Last-Modified). Clients can send If-None-Match with a previously received ETag to receive a 304 Not Modified response when content hasn't changed.

Get Package Metadata (Dev)

Returns metadata for dev versions only.

GET /{organization}/p2/{vendor}/{package}~dev.json

Same response format and caching behavior as the stable endpoint, filtered to dev versions (e.g., dev-main).

Notify Batch (Download Tracking)

Receives download notifications from Composer after packages are installed.

POST /{organization}/notify-batch

Request body:

{
    "downloads": [
        { "name": "vendor/package", "version": "1.0.0" },
        { "name": "vendor/other-package", "version": "2.3.1" }
    ]
}

Response: 204 No Content

Composer calls this endpoint automatically when the notify-batch URL is present in the root packages.json. Download counts are tracked per package version.

Security Advisories

Returns known security advisories for the requested packages. This endpoint is compatible with composer audit.

POST /{organization}/api/security-advisories

Request body:

{
    "packages": ["monolog/monolog", "symfony/http-kernel"]
}

Response:

{
    "advisories": {
        "monolog/monolog": [
            {
                "advisoryId": "PKSA-abcd-1234",
                "packageName": "monolog/monolog",
                "title": "Remote code execution via log injection",
                "link": "https://github.com/advisories/GHSA-xxxx",
                "cve": "CVE-2024-12345",
                "affectedVersions": ">=1.0,<1.5.2",
                "sources": [
                    { "name": "GitHub", "remoteId": "GHSA-xxxx-yyyy-zzzz" }
                ],
                "reportedAt": "2024-01-15T00:00:00+00:00",
                "composerRepository": "https://packagist.org",
                "severity": "high"
            }
        ]
    }
}

Field	Description
advisoryId	Unique identifier from the advisory source
packageName	Composer package name
title	Short description of the vulnerability
link	URL to the full advisory disclosure
cve	CVE identifier, if assigned
affectedVersions	Composer version constraint describing affected versions
sources	List of advisory sources with their remote identifiers
reportedAt	ISO 8601 timestamp of when the advisory was reported
composerRepository	The registry the advisory originates from
severity	One of critical, high, medium, low, or unknown

Packages with advisories are included in the response with their advisory list. Packages without advisories are omitted. If no requested packages have advisories, advisories is an empty object.

Webhooks

GitHub Webhook

POST /webhooks/github/{repository-uuid}

Receives push, release, and ping events from GitHub. Triggers an automatic repository sync when new commits or tags are pushed.

Requires webhook signature verification via the X-Hub-Signature-256 header.

Supported events:

Event	Action
ping	Returns 200 OK
push	Triggers repository sync
release	Triggers repository sync

GitLab Webhook

POST /webhooks/gitlab/{repository-uuid}

Receives push and tag push events from GitLab. Triggers an automatic repository sync when new commits or tags are pushed.

Requires webhook token verification via the X-Gitlab-Token header (plain text comparison).

Supported events:

Event	Action
Push Hook	Triggers repository sync
Tag Push Hook	Triggers repository sync

Bitbucket Webhook

POST /webhooks/bitbucket/{repository-uuid}

Receives push and ref change events from Bitbucket. Triggers an automatic repository sync when new commits or tags are pushed.

Requires webhook signature verification via the X-Hub-Signature header (HMAC-SHA256).

Supported events:

Event	Action
repo:push	Triggers repository sync
repo:refs_changed	Triggers repository sync

Generic Git Webhook

POST /webhooks/git/{repository-uuid}

Triggers a repository sync for Generic Git repositories. Unlike GitHub and GitLab webhooks, this endpoint must be configured manually on your Git server.

Activate the webhook from the repository page in Pricore to get the URL and secret, then configure your Git server to POST to this URL on push events.

Authentication — include the secret using one of these methods:

Method	Header / Parameter
Bearer token	Authorization: Bearer YOUR_SECRET
Custom header	X-Webhook-Token: YOUR_SECRET
Query parameter	?token=YOUR_SECRET

Response: 200 OK

{
    "message": "Sync dispatched."
}

Configuring Composer

Add Pricore as a Composer repository:

composer config repositories.your-org composer https://pricore.yourcompany.com/your-org

Then authenticate:

composer config --global --auth http-basic.pricore.yourcompany.com token YOUR_ACCESS_TOKEN

Error Responses

All errors return a consistent format:

{
    "message": "Error description"
}

HTTP Status Codes

Code	Description
200	Success
204	No Content — notify-batch accepted
304	Not Modified — content unchanged (conditional request)
401	Unauthorized — invalid or missing token
403	Forbidden — token lacks access to this organization
404	Not found
500	Server error