---
title: "List published versions for a package by PURL"
method: GET
path: "/v1/orgs/{org_slug}/purl/versions/{purl}"
tags: ["packages"]
---

# List published versions for a package by PURL

`GET /v1/orgs/{org_slug}/purl/versions/{purl}`

## Request

- The document declares no server URL.
- Auth: HTTP bearer

Given a package URL (PURL) *without* a version, returns every version
Socket knows about for that package along with its publish date, sorted
newest-first by publish date.

This lets you enforce version policies such as "N-1" (allow the previous
release, block the newest) without querying a package registry directly.
Versions with no known publish date are listed last.

**Ordering includes prereleases.** Sorting is by publish date only, so
index 0 is the most recently *published* version, not necessarily the
newest stable release. On npm in particular the newest publishes are
often canaries or release candidates, so a consumer that reads index 1
as "N-1" can land on a prerelease. Each entry carries a `prerelease`
flag for this: filter out entries where `prerelease` is `true` before
applying an N-1 rule. `prerelease` is `null` when the ecosystem's
version grammar has no canonical prerelease parser, or when the version
string itself does not parse — treat null according to your own policy
rather than as an error.

Pass `limit` to cap how many entries come back; it is applied after
sorting, so `limit=2` is all the N-1 use case needs. A `limit` that
is not a positive integer is rejected with a 400 rather than clamped.

The PURL must be percent-encoded as a single path segment
(`encodeURIComponent`); an unencoded `/` will not match this route.
Any version on the PURL is ignored — the full history always comes back.
The HuggingFace `type` qualifier (model, dataset, or space) is honored.

A well-formed PURL for an ecosystem that does not support version
listing returns a 400 rather than a server error.

Authentication: Organization API token, OAuth2, or NextAuth session.
Required token scope: `packages:list`. Costs 100 quota units.

## Path parameters

- `org_slug` string, required
- `purl` string, required

## Query parameters

- `limit` integer

## Response `200`

Default Response

- object
  - `purl` string, required: The PURL as received, echoed back.
  - `versions` object[], required: Known versions, newest-first by publish date. Ordering includes prereleases, so index 0 is the most recent publish rather than the newest stable release.
    - `version` string, required: The version string as the ecosystem reports it.
    - `publishedAt` string, nullable, required: ISO-8601 publish date, or null when the ecosystem reports none. Undated versions are listed last.
    - `prerelease` boolean, nullable, required: True when this version is a prerelease (canary, release candidate, dev, beta) according to the ecosystem's own version grammar. Null means unknown — either the ecosystem has no canonical prerelease parser, or this version string does not parse. Null is not an error.

## Other responses

- `400`: Default Response
- `401`: Default Response
- `403`: Default Response
- `404`: Default Response
- `429`: Default Response

---

[API](https://skmtc.dev/socket-dev/apis/socket-api-v1.md) - [All operations](https://skmtc.dev/socket-dev/apis/socket-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/socket-dev/apis/socket-api-v1/revisions/e88284728ffb?raw)