---
title: Pkgst package API reference
description: Public package metadata, exact-version resolution, batches, authorization and private preferences.
canonical: https://pkg.st/docs/api.md
last-updated: 2026-11-11
---

# Pkgst package API reference

Use **[elide.help](https://elide.help/)** as the primary documentation portal. Its [developer resources](https://elide.help/developers) describe documentation search and agent access. This page is the version-matched HTTP reference for the deployed Pkgst package API.

The base URL is `https://api.pkg.st`. Use HTTPS directly for every request, including the first request carrying authorization. Public package lookups need no API key or account. The structured API covers npm, PyPI and Maven; other supported ecosystems retain their native package-manager protocols. These calls retrieve metadata and artifact URLs without installing or executing packages.

## Quickstart: a public request

Discover the available platforms and capabilities:

```sh
curl --fail-with-body --silent --show-error \
  https://api.pkg.st/v1/platforms
```

The response contains a `platforms` array. Read a package's version list, then resolve an exact version:

```sh
curl --fail-with-body --silent --show-error \
  'https://api.pkg.st/v1/packages/npm/is-number?pageSize=20'

curl --fail-with-body --silent --show-error \
  https://api.pkg.st/v1/packages/npm/is-number/versions/7.0.0
```

The package response has `package` and `nextPageToken` fields. The version response has a `version` object with artifact URLs, available integrity information and platform-specific metadata. Inspect the [OpenAPI response schemas](https://pkg.st/openapi.json) before generating a client.

PyPI names are normalized according to that registry's naming rules. Maven coordinates use `groupId:artifactId`. Encode a complete package name as one URL segment; a scoped npm name such as `@scope/package` becomes `%40scope%2Fpackage`.

```sh
curl --fail-with-body --silent --show-error \
  https://api.pkg.st/v1/packages/pypi/six/versions/1.16.0

curl --fail-with-body --silent --show-error \
  https://api.pkg.st/v1/packages/maven/org.apache.commons%3Acommons-lang3/versions/3.17.0
```

`latest` selects the registry's advertised latest release. It is mutable: retain the returned exact version for reproducible work. Arbitrary semver, PEP 440 and Maven ranges are not resolved by this API. Transitive dependency solving, wheel selection and platform compatibility remain the client's responsibility. Maven version metadata describes the POM; native Maven clients continue resolving their artifacts through the Maven proxy.

## Pagination

`GET /v1/packages/{platform}/{name}` accepts `pageSize` from 1 to 200, defaulting to 100. A nonempty `nextPageToken` identifies the next page of the same version-list snapshot. Pass the token unchanged, URL-encoded, and stop when the returned token is empty:

```sh
curl --fail-with-body --silent --show-error --get \
  https://api.pkg.st/v1/packages/npm/is-number \
  --data-urlencode 'pageSize=20' \
  --data-urlencode "pageToken=${PKGST_PAGE_TOKEN:?Set PKGST_PAGE_TOKEN from the previous response}"
```

A registry update can invalidate a cursor. On HTTP 409 with `stale_page_token`, restart from the first page; do not splice pages from different snapshots together.

## Batch resolution

Resolve exact versions or `latest` for multiple packages in one request:

```sh
curl --fail-with-body --silent --show-error \
  https://api.pkg.st/v1/resolve:batch \
  --header 'Content-Type: application/json' \
  --data '{"requests":[{"platform":"npm","name":"is-number","version":"7.0.0"},{"platform":"pypi","name":"six","version":"1.16.0"}]}'
```

The response's `results` array preserves input order. Each result contains its `request` and either a `version` or an `error`. An HTTP 200 batch can contain failed items, so inspect every result and retain successful ones. Set `platform` explicitly when the same request must behave identically for anonymous and authorized callers; an authorized user's default-registry preference can otherwise fill an omitted platform.

Batches accept 1–32 items, run at most four upstream lookups concurrently and share repeated package lookups. The request body is limited to 64 KiB, aggregate metadata to 16 MiB and serialized results to 4 MiB. Split requests after `metadata_budget_exceeded` or `response_budget_exceeded`; blindly retrying the same oversized batch will not help. A batch is a read operation and creates no background job or package installation.

## Authentication and scoped preferences

Public reads need no credentials. Existing Elide access tokens can select authorized limits and access private preferences; Pkgst does not issue tokens or introduce a new sign-in flow. Obtain credentials through the existing Elide user or API-key flow described in the [authorization guide](https://pkg.st/docs/authorization.md).

Keep an existing token in `PKGST_TOKEN` through your approved secret-handling mechanism. Send it only in the `Authorization` header, never in a URL. Inspect effective permissions before customizing:

```sh
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${PKGST_TOKEN:?Set PKGST_TOKEN to an existing Elide access token}" \
  https://api.pkg.st/v1/me

curl --fail-with-body --silent --show-error --include \
  --header "Authorization: Bearer ${PKGST_TOKEN:?Set PKGST_TOKEN to an existing Elide access token}" \
  https://api.pkg.st/v1/preferences
```

`packages:read` permits authorized package access and preference reads. Updates additionally require `packages:preferences:write` and effective customization permission. Issued scopes and current authorization are both checked; a User-Agent or capability header never grants access. Older credentials do not gain newly introduced scopes retroactively.

The preference response includes `preferences` and `etag`, with the same quoted ETag in the response header. Set `PKGST_ETAG` to that exact quoted value. The following example **replaces the entire preference document**, clearing omitted optional fields:

```sh
curl --fail-with-body --silent --show-error --request PUT \
  --header "Authorization: Bearer ${PKGST_TOKEN:?Set PKGST_TOKEN to an existing Elide access token}" \
  --header 'Content-Type: application/json' \
  --header "If-Match: ${PKGST_ETAG:?Set PKGST_ETAG to the quoted ETag from GET preferences}" \
  --data '{"preferences":{"schemaVersion":1,"defaultRegistry":"npm"}}' \
  https://api.pkg.st/v1/preferences
```

Missing preconditions return 428. A concurrent update returns 412: read the new document, reconcile the intended change and submit its current ETag. Do not overwrite a conflict by retrying an old document. Identity, preferences and personalized responses use `private, no-store`; public immutable artifact identities are shared and contain no credentials.

## Errors, retries and request correlation

REST failures return JSON with `code`, `message` and numeric `status`, for example:

```json
{ "code": "stale_page_token", "message": "Package metadata changed; restart pagination.", "status": 409 }
```

| Status          | Client action                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| 400 / 415       | Correct the request fields, encoded coordinates or JSON content type.                                                               |
| 401 / 403       | Check the credential and effective scopes; do not retry unchanged credentials indefinitely.                                         |
| 404             | Check the package name, platform and version.                                                                                       |
| 409             | Restart pagination after the version-list snapshot changes.                                                                         |
| 412 / 428       | Read preferences and use their current ETag before a replacement.                                                                   |
| 429             | Honor `Retry-After` when present and reduce concurrency.                                                                            |
| 502 / 503 / 504 | Retry transient upstream or service failures with bounded exponential backoff and jitter; split batches for explicit budget errors. |

Inspect batch errors separately from the HTTP status. Preserve the response's request-correlation headers when reporting a failure, but exclude credentials and private preference content. Rate limits protect availability from abusive traffic; authorized limits depend on verified permissions.

Enforced package/API responses advertise their known quota policy in `RateLimit-Policy`. In shadow mode, `X-Pkgst-RateLimit-Mode: shadow` and `X-Pkgst-RateLimit-Policy` describe observation without enforcement. When limiting is off, no quota is advertised. Static documentation is exempt. Cloudflare's limiter provides an approximate per-location decision, not an exact global counter, so Pkgst does not invent remaining-quota or reset values. Honor `Retry-After` on a 429 and use bounded concurrency.

## Connect JSON and generated clients

Canonical messages and the service are Protocol Buffers, validated and published through [Buf](https://buf.build/elide/pkgst). OpenAPI schemas derive from the same descriptor with explicit HTTP mappings. REST JSON uses Proto JSON field names.

Equivalent unary Connect JSON methods use `/elide.cloud.v1.PkgstService/<Method>`:

```sh
curl --fail-with-body --silent --show-error \
  https://api.pkg.st/elide.cloud.v1.PkgstService/GetVersion \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{"platform":"npm","name":"is-number","version":"7.0.0"}'
```

Existing package and preference methods use JSON transport. The descriptor methods described below also support binary protobuf. gRPC, MCP and A2A package tools are not implemented by this service. The documentation MCP server at elide.help is a separate documentation interface.

## Versioning and deprecation policy

REST uses `/v1/`; the Protobuf package is `elide.cloud.v1`. Buf configuration declares a FILE-level compatibility policy; maintainers must verify proposed schemas against the published version before release. That configuration alone is not an automated CI gate. Incompatible wire changes require a new API/package version. Clients should ignore unknown additive response fields and use the published schema for known fields.

No v1 sunset is currently announced. Before retiring a version, publish its replacement, migration instructions and dated deprecation notice in this reference; advertise the retirement through `Deprecation` and `Sunset` headers. An unannounced disappearance or silent change to an existing artifact identity is not a versioning mechanism. Pin exact package versions independently of API versions.

## Contract discovery

| Resource               | Public URL                                                                             |
| ---------------------- | -------------------------------------------------------------------------------------- |
| API catalog            | [/.well-known/api-catalog](https://pkg.st/.well-known/api-catalog)                     |
| Capabilities           | [/.well-known/pkgst.json](https://api.pkg.st/.well-known/pkgst.json)                   |
| OpenAPI 3.1            | [/openapi.json](https://pkg.st/openapi.json)                                           |
| Protobuf source        | [/schemas/pkgst/v1/pkgst.proto](https://pkg.st/schemas/pkgst/v1/pkgst.proto)           |
| Descriptor set         | [/schemas/pkgst/v1/descriptor.bin](https://pkg.st/schemas/pkgst/v1/descriptor.bin)     |
| Buf publication record | [/schemas/pkgst/v1/publication.json](https://pkg.st/schemas/pkgst/v1/publication.json) |
| Documentation catalog  | [/docs/index.json](https://pkg.st/docs/index.json)                                     |
| Agent instructions     | [/llms.txt](https://pkg.st/llms.txt)                                                   |

HTTP `Link` headers advertise contracts and documentation. HEAD and ETags support inexpensive discovery and conditional retrieval. The descriptor contains public Pkgst types and required imports, never staff/admin service definitions. Every published descriptor set also stays available at `/schemas/pkgst/v1/<sha256>.bin` with an immutable cache policy; `schemas.descriptorImmutable` in the capability document names the current one. Use it to generate decoders; descriptor behavior is negotiated by [protocol version](#descriptor-protocol-versions), not by schema hash. Hashes and sizes identify decoded bytes; decompress HTTP content encodings before checking them. Check the publication record for the Buf commit and descriptor hash matching the deployed contract.

## Versioned package descriptors

`GET /v1/descriptors/{ecosystem}/{name}/versions/{version}` returns a `descriptor` wrapper around `elide.pkgst.v1.PackageDescriptor`. The request supplies package/repository identity; the descriptor supplies source integrity and declared package-resolution inputs. Maven uses `elide.pkgst.maven.v1.Pom`. npm and PyPI descriptor payloads are not implemented.

The initial implementation supports `ecosystem=maven`, `repository=maven` (default) or `repository=gradle`, and exact immutable release versions. It rejects snapshots, `latest`, and version expressions. Public descriptors use the same authorization/abuse boundary as downloads, and contain no caller-specific preferences.

```sh
curl --fail-with-body --silent --show-error \
  --header 'Accept: application/json' \
  'https://api.pkg.st/v1/descriptors/maven/org.apache.commons%3Acommons-lang3/versions/3.17.0?repository=maven'
```

Use `Accept: application/protobuf` for `elide.cloud.v1.PkgstServiceGetDescriptorResponse`. JSON follows protobuf JSON mapping: digest bytes are base64 and `uint64` sizes are decimal strings. The default contains only declared resolver inputs and SHA-256 integrity information. `includeMetadata=true` opts into `descriptor.mavenPom.metadata` (name, description, URL) and supplementary SHA-512 provenance. XML is retrieved from the canonical URL derived from the request using normal zstd/br/gzip/dcz negotiation; descriptors never embed XML bytes or trees. ETags identify the selected encoded representation. `X-Pkgst-Descriptor-Schema` identifies the deployed compiler descriptor.

The GET request or batch index supplies requested identity; it is not repeated in the descriptor. Construct XML URLs as `https://{repository}.pkg.st/{groupId.replaceAll(".", "/")}/{artifactId}/{encodeURIComponent(version)}/{artifactId}-{encodeURIComponent(version)}.pom`. `source.url`, when present, is a noncanonical override. `includeMetadata` also includes source size, media type and origin. Declared model coordinates retain their original expressions and presence independently from request identity. A batch result contains `index` and its descriptor/error, without another copy of the request reference.

`descriptor.mavenPom.projection` retains coordinates, parent, properties, dependencies and exclusions, dependency management, resolution-relevant profiles and activation, repositories and policies, and relocation. Build/publication configuration is omitted. Profiles with no resolution inputs are omitted unless their ID/activation is needed to suppress a default profile. Expressions and explicit defaults remain unchanged: an unused-looking property can override an inherited dependency, and an explicit scope can override management. Clients perform inheritance, interpolation, activation and mediation. When `sourceRequiredReasons` is nonempty, `projection` is absent; retrieve canonical XML before resolution. A missing projection never means an empty dependency list.

This API consumes published packages. Build extensions alone do not require XML; retained expressions that reference omitted source fields do. No raw scope/profile filtering is applied to shared models. Build-specific filtering requires effective inheritance/management and explicitly keyed build context.

The parser accepts UTF-8, ISO-8859-1 and XML-detected UTF-16, rejects DTDs/external entities, and bounds input to 512 KiB, depth to 40, nodes/attributes to 10,000 each and attributes per element to 128. A 2 MiB expansion budget bounds parsing. Unsupported or oversized structured input does not alter the retained POM. Derivative caches are scoped by schema fingerprint, parser behavior, metadata selection, repository, coordinates and source digests.

### Descriptor protocol versions

Descriptor endpoints negotiate behavior with an explicit integer version, not by schema hash. Send `X-Pkgst-Descriptor-Version: <n>` on descriptor requests, including `POST /v1/descriptors:batch` in every response mode and the `/v1/descriptors:stream` upgrade. WebSocket clients that cannot set upgrade headers may use `?descriptor_version=<n>`; the header wins when both are present. A missing version selects `1`.

| Version | Behavior |
| ------- | -------- |
| `1` | Default. `expandDepth` is ignored and no result carries `expanded`. |
| `2` | Batch expansion (`expandDepth`) is honored. |

An unknown, non-integer or out-of-range value is rejected before any work (and before a WebSocket upgrade) with HTTP 400, code `unsupported_descriptor_version`, and `X-Pkgst-Descriptor-Versions: 1, 2`. Successful descriptor responses, including the 101 upgrade, echo `X-Pkgst-Descriptor-Version` (the version used) and `X-Pkgst-Descriptor-Versions`. Descriptor responses vary on `X-Pkgst-Descriptor-Version`. `X-Pkgst-Descriptor-Schema` and the content-addressed schema assets remain for decoder generation; do not negotiate on them.

### Descriptor batches and framing

`POST /v1/descriptors:batch` accepts JSON or `application/protobuf` encoded `PkgstServiceBatchGetDescriptorsRequest`:

```json
{
  "requests": [{ "name": "org.apache.commons:commons-lang3", "version": "3.17.0" }],
  "unordered": true
}
```

Select one response format with `Accept`:

- `application/json`: `PkgstServiceBatchGetDescriptorsResponse`, with ordered `results`.
- `application/protobuf`: the same protobuf response message.
- `application/vnd.pkgst.descriptor-stream+protobuf`: a sequence of **unsigned varint32 byte length followed by one `elide.pkgst.v1.DescriptorResult`**. This is not gRPC or Connect framing. Each result carries its original zero-based index and a descriptor or code/status error. There is exactly one record per item. Order defaults to request order; `unordered=true` emits completed results immediately. `X-Pkgst-Descriptor-Count` advertises the expected count. Validate unique indexes and total count; a truncated transport is incomplete.

Omitted `ecosystem` and `repository` default to `maven`; explicit unsupported values fail. `includeMetadata` and `unordered` default to false and cost no protobuf bytes when omitted. Submit unresolved references from multiple roots together. Buffered responses always retain request order; `unordered` affects streaming delivery only. Item errors omit repeated generic diagnostic text.

With descriptor protocol version 2, set `expandDepth` (1 or 2; 0, the default, disables it and larger values clamp to 2) to also receive the descriptors that successful POM results lead to: the parent, imported BOMs and direct compile/runtime, non-optional dependencies with literal release versions, at most eight per POM. Expansion is breadth-first in the root request's repository and stops at the requested depth or after 64 extra results. Each expansion result carries `expanded` (the coordinate it describes) and the `index` of the request it was reached from. Expansion results are only successful descriptors (source-required descriptors included); failures are omitted. No expansion result repeats a requested reference or another expansion result. Requested items always take load slots first. Framed streams interleave expansion records in completion order whatever `unordered` says; `X-Pkgst-Descriptor-Count` and the one-record-per-request rule count requested records only, and the stream ends at normal EOF. Buffered responses append expansion results after every requested result. Expansion results use at most 2 MiB of the response budget and are dropped, never errors, when they do not fit.

Batches are limited to 32 items, four concurrent loads, a 64 KiB request and an 8 MiB aggregate response. Batch bodies are private/noncacheable; individual parsed derivatives remain shared because their content is public and repository-scoped. When a batch exhausts its response budget, remaining records contain `descriptor_batch_budget_exceeded`; split that batch. Bound each descriptor to 2 MiB and each framed result to 2 MiB + 4 KiB. Streams must bound each varint/frame and validate expected count/index before considering the request complete.

HTTP descriptor responses negotiate `zstd`, `br`, `gzip` or identity through `Accept-Encoding`. Client quality values take precedence; dynamic responses prefer Zstandard, then Brotli, then gzip at equal quality. Buffered compressed responses use encoded-byte ETags and `Vary: Accept, Accept-Encoding, X-Pkgst-Accept-Encoding`. Small unary responses can use identity when compression increases size and identity is acceptable. Streaming batches compress incrementally. Clients must decompress before reading protobuf frame lengths.

### WebSocket descriptor stream

`GET /v1/descriptors:stream` upgrades to a WebSocket. Send binary `elide.pkgst.v1.DescriptorStreamRequest` messages and decode binary `DescriptorStreamResponse` messages, one protobuf message per WebSocket message. No gRPC envelope or varint outer framing is used. A request has an increasing nonzero `requestId` and one command: `batch` (references, optional `includeMetadata`, `unordered` and `expandDepth`), cumulative `ack` (`nextIndex` is the number of received results, not an original item index), or `cancel`.

One batch is active at a time. The server allows four outstanding results and advances when acknowledgments release credits. Results retain request order by default; `unordered=true` lets ready results arrive immediately. Each result has its original index; item errors count as results. Validate every index exactly once and accept completion only after `complete.count` equals the expected count and `complete.cancelled` is false. A disconnect, truncated result, cancellation, or protocol error cannot be accepted as a resolved batch. A socket can accept additional batches after completion. With `expandDepth`, expansion results arrive in completion order as described for HTTP batches; acknowledgements, the four-result credit window and `complete.count` all include them.

Limits: 64 KiB input messages; 32 references and 8 MiB output per batch; 128 references, 128 expansion loads and 32 MiB output per connection (expansion silently stops once its connection budget is spent); five-minute maximum lifetime and 60-second idle timeout. Reconnect for further work. Authorization is validated during upgrade; use an authorization header rather than a query token. WebSocket messages are uncompressed protobuf unless the client negotiates dictionary frames, described next. This endpoint streams declared resolver inputs, not an effective model or complete resolved graph.

#### Negotiated dictionary frames

Compression is selected in the handshake with a WebSocket subprotocol, so the first server message can already use it. Two tokens exist:

| `Sec-WebSocket-Protocol` token | Messages |
| --- | --- |
| `pkgst.descriptors.protobuf` | One protobuf message per WebSocket message, as above |
| `pkgst.descriptors.protobuf.zstd-dict.2b1121008dc6d9eb9a5b8b128b3925743acb5367b4426a25d8dcc16a502c0a28` | The same protobuf messages, each behind a one-byte tag |

The suffix is the full lowercase SHA-256 of the dictionary bytes, so a token names exactly one dictionary and a retrained dictionary is a different token. Offer tokens in preference order; the server selects the first one it supports and returns exactly that token in the 101 response. Read the echoed token to learn the framing: never assume compression because it was offered.

```http
GET /v1/descriptors:stream HTTP/1.1
Host: pkg.st
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: <nonce>
Sec-WebSocket-Protocol: pkgst.descriptors.protobuf.zstd-dict.2b1121008dc6d9eb9a5b8b128b3925743acb5367b4426a25d8dcc16a502c0a28, pkgst.descriptors.protobuf

HTTP/1.1 101 Switching Protocols
Sec-WebSocket-Protocol: pkgst.descriptors.protobuf.zstd-dict.2b1121008dc6d9eb9a5b8b128b3925743acb5367b4426a25d8dcc16a502c0a28
```

Fallback rules: a dictionary token this server does not have is skipped, so offering it together with `pkgst.descriptors.protobuf` yields an uncompressed session with the bare token echoed. Offering only unsupported tokens returns HTTP 400 `unsupported_descriptor_stream_protocol`. Sending no `Sec-WebSocket-Protocol` header, or the bare token alone, gives the unchanged uncompressed protocol. Tokens are compared exactly and case-sensitively.

Under the dictionary token every binary message in both directions is `tag || payload`:

| Tag byte | Payload |
| --- | --- |
| `0x00` | The protobuf message itself |
| `0x01` | One Zstandard frame (RFC 8878) whose content is the protobuf message, compressed with the negotiated dictionary |

Any other tag, an empty message or a text message is a protocol error. The server sends tag 1 only when the frame is smaller than the protobuf message, so a message never grows by more than the tag byte; completions and other tiny messages normally arrive with tag 0. A decoder must handle either tag on every message. Clients may send either tag; requests are small, and tag 0 needs no encoder.

Each tag-1 payload is a single standard frame that carries the dictionary's ID (`1248671774`) and its exact content size, with no trailing bytes; any stock Zstandard decoder loaded with the dictionary decodes it. Frames are independent: there is no compression state between messages. The server refuses client frames that omit the content size or dictionary ID, name another dictionary, contain more than one frame, or declare more than 64 KiB; the declared size is checked before decoding and output is capped at it. A client should bound server frames the same way, at 2,101,248 decoded bytes.

All limits keep their meaning and count the **decoded protobuf message**, never wire bytes: 64 KiB per request, 8 MiB per batch and 32 MiB per connection are identical for both protocols, so the same batch yields the same results and budget errors either way. The wire form of a request may be one byte longer than 64 KiB to hold the tag. Framing violations send a final `DescriptorStreamResponse.error` (itself tagged) and close with code 1008; the codes are `invalid_descriptor_frame_tag`, `invalid_descriptor_frame_compression` and `descriptor_request_too_large`.

The dictionary is `descriptor-stream-v1`: 32,768 bytes, a full Zstandard dictionary (not raw content), SHA-256 `2b1121008dc6d9eb9a5b8b128b3925743acb5367b4426a25d8dcc16a502c0a28`, immutable at [`/_/dictionaries/2b1121008dc6d9eb9a5b8b128b3925743acb5367b4426a25d8dcc16a502c0a28.dict`](https://pkg.st/_/dictionaries/2b1121008dc6d9eb9a5b8b128b3925743acb5367b4426a25d8dcc16a502c0a28.dict). The [dictionary catalog](https://pkg.st/.well-known/pkgst-dictionaries.json) lists it with `artifactType: "descriptor-stream"`, its `subprotocol` token, size, hash and URL. Fetch it at build time, verify the SHA-256 and bundle it; derive the token from the bytes you bundled. There is no moving alias. [Measured sizes and encoder cost](https://pkg.st/docs/compression.md#websocket-dictionary-frames).

The same methods are available as unary `GetDescriptor` and `BatchGetDescriptors` RPCs under `/elide.cloud.v1.PkgstService/`, with `Connect-Protocol-Version: 1`. They accept/return Connect `application/json` or `application/proto` according to request content type. The length-delimited stream format is REST-only. Existing RPCs remain unary Connect JSON; gRPC is not implemented.

## Maven POM and Javadoc views

`GET https://maven.pkg.st/{group/path}/{artifact}/{version}/{artifact}-{version}.pom.json` returns `application/json`:

```json
{
  "coordinate": { "groupId": "org.example", "artifactId": "demo", "version": "1.2.3" },
  "source": { "url": "https://maven.pkg.st/org/example/demo/1.2.3/demo-1.2.3.pom", "sha256": "…", "sha1": "…", "size": 2826 },
  "pom": { "projection": { "parent": {}, "properties": [], "dependencyManagement": [], "dependencies": [] }, "metadata": { "name": "Demo" }, "sourceRequiredReasons": [] }
}
```

`pom` is the protobuf JSON form of `elide.pkgst.maven.v1.Pom`. The same document is selected on the `.pom` URL by an `Accept` header that names `application/json` with a higher quality than any XML or wildcard range; `Accept: */*`, an absent header and `application/json, */*` all select XML. A POM larger than 512 KiB returns `413`, and one that is not a Maven project returns `422 unsupported_pom_document`. Snapshot versions are not served. The `Link` header names the canonical XML.

`GET https://api.pkg.st/v1/javadoc/maven/{groupId}/{artifactId}/{version}/` returns a `text/markdown` index of the release's `-javadoc.jar`; `GET …/{entry}.md` (or `.html`) returns that archive page converted to Markdown. Only the archive directory and the requested entry are read. A page is limited to 2 MiB of HTML. Errors are JSON: `400 invalid_javadoc_request`, `404 javadoc_not_found`, `404 javadoc_page_not_found`, `413 javadoc_entry_too_large` or `javadoc_archive_too_large`, and `502 javadoc_archive_invalid` or `javadoc_entry_corrupt` for a damaged archive.

Both views honor `Accept-Encoding`, `If-None-Match` and `HEAD`, and are cacheable for one day.

## Maven index snapshots

`GET /v1/index/maven` reports the published Maven Central index generation,
`snapshotAsOf`, repository, complete snapshot package/variant counts, and source
archive provenance. A snapshot is an inventory as of its reported date. It is
**not authoritative for latest versions**; `sourcePartial` and
`authoritativeForLatest` are both explicitly `false`. An unpublished or incomplete
index returns `503`, never an empty inventory presented as success.

`GET /v1/index/maven/org.slf4j%3Aslf4j-api?pageSize=100` returns literal indexed
variants for `groupId:artifactId`. Variants retain the version, source identity,
classifier, extension, packaging, optional source SHA-1, byte size, modification
time, and original flags. Flags use bits `1` for sources, `2` for javadoc, and `4`
for signatures; unknown bits remain in `sourceFlags`. A source SHA-1 is an index
claim, not verification of artifact bytes. Archive SHA-256 values in status prove
which index inputs were imported and are not artifact SHA-256 values. Absent
optional fields remain absent; protobuf JSON encodes 64-bit integers as decimal
strings and digest bytes as base64. Historical index checksum values that are
not exactly 40 hexadecimal characters, such as `SHA1`, are preserved verbatim in
optional `sourceSha1Text`; `sourceSha1` is absent for those variants. This raw
text is not a digest and must never be used for artifact integrity checks.
Valid SHA-1 values retain the existing `sourceSha1` bytes representation.

Pages default to 100 variants and allow up to 200. Follow `nextPageToken` without
interpreting it; an empty token ends the listing. Cursors bind both package and
index generation. A newly published generation returns `409
index_generation_changed` for an old cursor; restart without `pageToken`. Variants
follow source-identity order, with no semantic version ordering or latest-version
claim. A `404 package_not_in_index` means the package is absent from this snapshot,
**not that it is absent upstream**. No registry fetch is triggered by an index miss.
The index projection does not contain effective POMs or resolved dependency graphs;
use the descriptor API for declared POM data.

The corresponding unary Connect JSON methods are `GetIndexStatus` (request `{}`)
and `GetIndexPackage` (request `{"name":"org.slf4j:slf4j-api","pageSize":100}`).
Both require the usual `Connect-Protocol-Version: 1` and `Content-Type:
application/json` headers. Their shared versioned model is
[`elide.pkgst.maven.index.v1`](../schemas/pkgst/v1/elide/pkgst/maven/index/v1/index.proto),
published with the public Buf module and OpenAPI contract. GET/HEAD responses have
content-derived ETags and a 60-second cache lifetime. Connect calls and errors use
`private, no-store`. Authorization is checked before reading an index, including
when its internal objects are already cached.

Serving reads only R2 and the edge Cache API. An active generation points to a
hash-verified manifest, manifest page, and lookup shard. Each object is bounded to
2 MiB. Packages exceeding a shard use authenticated overflow pages of at most
1 MiB and 1,000 rows, preserving their complete inventory. A request reads only
its overlapping pages, with at most 16 overflow reads and 8 MiB of overflow input.
Mutable publication is cached for at most 60 seconds, and immutable objects are
cached by generation and digest. Missing or corrupted referenced objects fail
closed with `503`; serving never repairs a snapshot by writing objects or calling
an upstream provider.

## Repository catalog

The catalog provides browsable inventory with background synchronization and release observations. Native package fetching never waits for catalog writes. Successful immutable Maven and npm tarball requests queue hints through a private service binding, including warm-cache requests; hints are deduplicated briefly in each isolate. Queue consumers record the observation and hydrate package inventory. npm and Yarn share npm coordinates. Gradle remains a separate repository; Gradle observations and ambiguous PyPI filename observation are not enabled yet.

```sh
curl --fail-with-body 'https://api.pkg.st/v1/catalog/status'
curl --fail-with-body 'https://api.pkg.st/v1/catalog/groups?ecosystem=maven&prefix=org.apache.'
curl --fail-with-body 'https://api.pkg.st/v1/catalog/packages?ecosystem=maven&namespace=org.apache.commons'
curl --fail-with-body 'https://api.pkg.st/v1/catalog/versions?ecosystem=maven&namespace=org.apache.commons&name=commons-lang3'
curl --fail-with-body 'https://api.pkg.st/v1/catalog/artifacts?ecosystem=maven&namespace=org.apache.commons&name=commons-lang3&version=3.17.0'
```

`ecosystem` defaults to `maven`; `repository` defaults to the ecosystem. Initially `maven/maven` and `npm/npm` are supported. Maven namespace is the literal group ID; npm namespace is its scope without `@`, or empty for an unscoped package. Directory `prefix` filters namespaces for groups and names for packages. Listing results use `items`, `nextCursor` and `sequence`. Supply the next cursor unchanged as `cursor`, and use `limit` from 1 to 500 (default 100). A cursor is consistent within one catalog object's revision, not a global transaction across every catalog object. HTTP 409 means that object changed; restart its pagination.

HTTP 202 with `catalog_hydrating` and `Retry-After` means the initial inventory is queued or being loaded. It must not be interpreted as an empty result. The catalog uses lazy package/version hydration and incremental synchronization; group/package directories may still be filling. Status distinguishes source freshness, the last successful synchronization and an in-progress or failed refresh. The source index can lag publication, and a catalog miss never proves upstream absence. Use existing exact/latest APIs and native registries for authoritative resolution.

Version and artifact pages include `state` with hydration and source/observation freshness. Source-index artifact metadata is separate from `observedArtifacts`, which records paths actually served through the proxy without inventing checksums or sizes. The latter is a page with its own `nextCursor`; pass it as `observedCursor` to paginate observations independently. `observedOnly` versions have no canonical indexed artifacts yet. Sequence values, byte lengths and millisecond timestamps are protobuf JSON decimal strings; optional source fields remain absent when unknown. Observation times use Unix epoch milliseconds, whereas `sourceAsOf` is an ISO timestamp. A negative source size sentinel is preserved as supplied.

Artifact `sha1` is present only for a source checksum of exactly 40 hexadecimal characters. Malformed literal source values are retained as optional `sourceSha1Text` instead, without rejecting the rest of the package inventory. Treat that field as opaque provenance text, never as a usable checksum or integrity claim. Missing checksum fields remain absent.

REST supports GET and HEAD; successful reads may be cached for 30 seconds. The matching unary Connect JSON methods are `GetCatalogStatus`, `ListCatalogGroups`, `ListCatalogPackages`, `ListCatalogVersions` and `ListCatalogArtifacts`. Connect maps hydration to retryable `unavailable` (HTTP 503) instead of a successful response. The Buf source model is `elide.pkgst.catalog.v1`; OpenAPI and `/.well-known/pkgst.json` advertise all routes. `/v1/index/maven` remains available for the previous published snapshot API.


## Gradle Module Metadata

POM descriptors expose optional `gradleModuleMetadata`: `true` when the source XML contains the `do_not_remove: published-with-gradle-metadata` comment, `false` when it does not, and absent for older descriptors whose state is unknown. The hint survives unsupported POM projections and `includeMetadata=false`. The updated schema hash and model revision 5 invalidate older stored projections. No upstream `.module` probe is needed for POM-only publications.

Use `ecosystem: "gradle"`, a Maven `group:artifact` name, and an exact release version to request a `.module` descriptor. Repository defaults to `maven`; select `gradle` for the Plugin Portal or `gmaven` for Google Maven. This ecosystem selects the metadata format; the repository independently selects its source. Unary, batch, length-delimited and WebSocket transports return `gradleModule.json` (the protobuf `model` oneof), the exact UTF-8 source bytes (base64 in ProtoJSON). Clients retain variant selection and `available-at` handling. Unknown JSON fields are preserved. SHA-256 identifies the original bytes, shared with ordinary artifact downloads and offline retention. Descriptor source limits remain 512 KiB; larger module files remain available through native artifact URLs.

Native release `.module` requests use the immutable artifact cache, asynchronous R2 retention and content-addressed prepared zstd, Brotli, gzip and `dcz` variants. Cold requests stream source bytes (with ordinary streaming compression when accepted) and enqueue preparation. Clients refusing identity receive 406 until a permitted variant is prepared. Quality values, ranges, HEAD and representation validators follow the POM rules. Maven Central aliases are shared only after an observed Plugin Portal redirect; hosted Plugin Portal modules keep distinct identities. Mutable snapshot modules retain metadata freshness rules.

Bundle `/_/dictionaries/gradle.dict` at build time, follow its 307 redirect, and pin SHA-256 `ea1b2d7946e70abbb4c878f2f2787df098d44e0aa752446846e0cefe0d541afa`. HTTP `dcz` requires its hash in `Available-Dictionary` and an installed dictionary-aware decoder. WebSockets negotiate `pkgst.descriptors.protobuf.zstd-dict.` plus that hash and use the same tag 0/tag 1 framing and decoded limits as descriptor streams. Each connection uses exactly the dictionary named by its selected subprotocol, including mixed POM/module batches. Offer `pkgst.descriptors.protobuf` as fallback.

The dated Maven index is upstream inventory, not a proof of `.module` absence. Successful Maven Central module fetches enter the existing catalog observation pipeline; they do not fabricate entries in a published index snapshot.
