Deps Dev

deps.dev (Skill Router)

This file is intentionally introductory.

Open the right note under references/ based on what you need.

Start here (fast)

• Need the latest/default version of a known package? Read: references/latest-version.md.
• Handling huge version lists or truncated responses? Read: references/large-responses.md.
• Not sure how to format/normalize package names per ecosystem? Read: references/naming-and-encoding.md.
• Need endpoint shapes and fields to parse? Read: references/api.md.

Primary recipe (one request)

Goal: given {system, packageName}, return the default/latest version.

• Call GetPackage: GET https://api.deps.dev/v3/systems/{SYSTEM}/packages/{PACKAGE}
• Parse versions[] and select the item with isDefault=true.

If isDefault is missing for all versions, stop and ask for an explicit selection rule (e.g., include pre-releases or not) instead of guessing.

Critical prohibitions

• Do not guess the “latest” version by string sorting.
• Do not output placeholder or “approximate” versions; always wait for API data.
• Do not parse large JSON via grep or manual truncation; use a JSON parser (jq/Python/Node).
• Do not silently fall back when isDefault is missing; ask for the desired rule.
• Do not paste large verbatim chunks from docs; summarize.
• Do not assume auth or rate limits; treat them as unspecified unless you have evidence.

Links

• Documentation
• GitHub

deps.dev API v3: endpoints you’ll use

Base: https://api.deps.dev/v3

GetPackage (best for “latest/default version”)

GET /systems/{system}/packages/{name}

Key response fields:

• packageKey.system, packageKey.name (may be canonicalized)
• versions[] (available versions)
• versions[].versionKey.version (string)
• versions[].publishedAt (optional)
• versions[].isDefault (boolean; marks the default version)

GetVersion (details for a specific version)

GET /systems/{system}/packages/{name}/versions/{version}

Useful when you need licenses/advisories/links:

• licenses[] (SPDX expressions or "non-standard")
• advisoryKeys[] (OSV IDs)
• links[]
• attestations[]

Query (lookup by version key or content hash)

GET /query?...

Supports:

• versionKey.system, versionKey.name, versionKey.version
• hash.type, hash.value

Notes:

• Up to 1000 results.
• Use Query when you already know the version and want “GetVersion-like” details in batch-ish form.

Large responses: safe extraction of the default version

Problem

GetPackage can return hundreds of versions. Tooling that truncates output or relies on text search (grep) will often miss isDefault=true and lead to guessed versions.

Rule

Always parse JSON with a proper parser and extract only the isDefault=true entry.

Minimal patterns (safe)

Python (stdin JSON)

• Load JSON
• Find versions[] item with isDefault true
• Return versionKey.version

Node.js (stdin JSON)

• Load JSON
• versions.find(v => v.isDefault)
• Return versionKey.version

If output is truncated

• Re-run the request and parse the JSON directly in-process.
• Do not rely on terminal output capture.
• Do not extract version numbers from partial output.

Anti-patterns

• Guessing versions from memory
• Sorting version strings without explicit rule
• Grep-ing for "version" or "isDefault" in a truncated response

Get the latest/default version (deps.dev API v3)

Use this when

• You have {system, packageName} and want a single-request answer.

Inputs

• SYSTEM: one of GO, RUBYGEMS, NPM, CARGO, MAVEN, PYPI, NUGET
• packageName: ecosystem-specific identifier

Procedure (minimal)

1. Percent-encode the package name for use in a path segment (e.g. use encodeURIComponent in JS). 2. Call:

• GET https://api.deps.dev/v3/systems/{SYSTEM}/packages/{ENCODED_PACKAGE_NAME}

3. Parse JSON with a real JSON parser (not grep) and locate versions[]. 4. Select the item where isDefault is true. 5. Return versions[i].versionKey.version.

Expected failure modes (handle explicitly)

• HTTP 404: package not found (double-check ecosystem + name normalization).
• No versions[]: treat as an error; do not assume “no versions”.
• No version has isDefault=true: stop and ask for a selection rule.
• deps.dev describes isDefault as system-specific, commonly “greatest version number ignoring pre-releases”.
• If you need a different rule (e.g. include pre-releases, or pick by publishedAt), state it explicitly.

Large responses (common)

The versions[] list can be very large. Do not truncate, stream to text, or parse via grep.

Use a JSON parser and extract only the default version:

• Python (stdin):
• read JSON, then next(v for v in versions if v.get("isDefault"))
• Node.js (stdin):
• parse JSON, then versions.find(v => v.isDefault)

If your toolchain truncates output, re-run the request and parse the JSON directly in-process.

Examples

npm scoped package

• System: NPM
• Name: @colors/colors
• Request path uses URL-encoding: %40colors%2Fcolors

Maven package

• System: MAVEN
• Name format: <groupId>:<artifactId> (must be encoded when placed in the URL path)

Output contract (suggested)

Return a small JSON object:

• system
• package (canonicalized name from response, if different)
• version (the selected default/latest)
• publishedAt (if present for the selected version)

Package naming + URL encoding (deps.dev API v3)

Systems (ecosystems)

Use these exact identifiers in the URL:

• GO, RUBYGEMS, NPM, CARGO, MAVEN, PYPI, NUGET

Naming gotchas

• Maven package names use the form <groupId>:<artifactId>.
• PyPI names are normalized per PEP 503 (the API may canonicalize the name).
• NuGet names are normalized by lowercasing, per NuGet Package Content API naming rules; versions are normalized per NuGet 3.4+ rules.

URL encoding rules (practical)

The package name is part of the URL path, so you must percent-encode it as a path segment:

• npm scoped names contain @ and / (encode both)
• Maven names contain : (encode it)

Implementation guidance:

• JavaScript: use encodeURIComponent(packageName)
• Python: use urllib.parse.quote(packageName, safe="")

Do not partially encode or hand-roll encoding.

Sources (for maintainers)

• deps.dev API v3 docs: https://docs.deps.dev/api/v3/
• API versions overview: https://docs.deps.dev/api/
• Blog note on v3 stability & deprecation policy: https://blog.deps.dev/api-v3/

Notes:

• Authentication and rate limits were not described in the retrieved sources; avoid making claims without evidence.