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:

bash

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

Authorization Header

Alternatively, use the Bearer token format:

bash

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:

json

{
    "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:

json

{
    "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.

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:

json

{
    "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:

json

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

Response:

json

{
    "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.

Upload a Package Version

Publishes a zip archive as a version of an existing uploaded package. Requires a token with publishing allowed; personal tokens also require their owner to be an owner or admin of the organization.

POST /{organization}/api/packages/upload

Request (multipart/form-data):

Field	Description
`archive`	The `.zip` to publish, with `composer.json` at its root or in a single top-level directory.
`version`	Optional. The version to publish; defaults to `version` in `composer.json`.

bash

curl -H "Authorization: Bearer YOUR_TOKEN" \
  -F archive=@package.zip \
  -F version=1.4.0 \
  https://pricore.yourcompany.com/{organization}/api/packages/upload

Response (201 Created, or 200 OK when the identical archive was already published as this version):

json

{
    "result": "added",
    "package": "acme/moodle-plugin",
    "version": "1.4.0",
    "version_normalized": "1.4.0.0",
    "dist": {
        "url": "https://pricore.yourcompany.com/acme/dists/acme/moodle-plugin/1.4.0/3f7a...e1.zip",
        "shasum": "3f7a...e1",
        "size": 48213
    }
}

result is added, replaced (a dev version was overwritten) or unchanged.

Errors are returned as JSON with a message:

Status	Reason
`403`	The token can't publish
`404`	The package doesn't exist yet; create it by uploading its first version in the web app
`409`	The package is synced from a repository or mirror, or the release already exists with a different archive
`422`	The archive is invalid: not a zip, no or invalid `composer.json`, unsafe paths, a missing or invalid version, or too large
`429`	Too many uploads with this token; the default limit is 30 per minute

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

json

{
    "message": "Sync dispatched."
}

Configuring Composer

Add Pricore as a Composer repository:

bash

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

Then authenticate:

bash

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

Error Responses

All errors return a consistent format:

json

{
    "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

API Reference ​

Authentication ​

HTTP Basic Auth ​

Authorization Header ​

Composer Repository API ​

Get Package List ​

Get Package Metadata (Stable) ​

Get Package Metadata (Dev) ​

Notify Batch (Download Tracking) ​

Security Advisories ​

Upload a Package Version ​

Webhooks ​

GitHub Webhook ​

GitLab Webhook ​

Bitbucket Webhook ​

Generic Git Webhook ​

Configuring Composer ​

Error Responses ​

HTTP Status Codes ​

API Reference

Authentication

HTTP Basic Auth

Authorization Header

Composer Repository API

Get Package List

Get Package Metadata (Stable)

Get Package Metadata (Dev)

Notify Batch (Download Tracking)

Security Advisories

Upload a Package Version

Webhooks

GitHub Webhook

GitLab Webhook

Bitbucket Webhook

Generic Git Webhook

Configuring Composer

Error Responses

HTTP Status Codes