canonical: https://jentic.com/apis/codesearch.debian.net/codesearch-debian

# Codesearch Debian Debian Code Search

Debian Code Search is a regex-capable search engine indexing the source code of every package in the Debian archive - billions of lines across tens of thousands of upstream projects. The public API exposes 2 endpoints over codesearch.debian.net/api/v1: /search returns matching source lines and /searchperpackage aggregates the same results per Debian source package. Authentication is an x-dcs-apikey header issued to registered users. The service is operated by the Debian project and primarily used by maintainers, security researchers, and license auditors investigating how a symbol or pattern appears across upstream code.

## For AI agents

Search the source of every Debian package by regex and get matches per file or aggregated per source package using an x-dcs-apikey header.

## Scope

Does not handle binary package metadata, bug tracking, or Debian build infrastructure - use for regex search across Debian source code only.

## Capabilities

- Search across the full Debian source archive for a regular expression via GET /search
- Aggregate the same regex search per source package using GET /searchperpackage to get unique-package results
- Use Debian Code Search query operators (path:, package:, lang:) to scope a search by language or package
- Paginate through long result sets via standard query parameters
- Identify which upstream packages still contain a deprecated symbol or vulnerable pattern

## Use cases

### Cross-Package Vulnerability Sweep

Security teams use Debian Code Search to find every package that contains a vulnerable code pattern - for example a known-bad regex or an unsafe API call. The agent issues a GET /searchperpackage query with the regex, collects the affected packages, and feeds them into a downstream advisory or patch workflow. Replaces grep against a local checkout of the entire archive.

Example prompt: Call GET /searchperpackage with a regex matching a known-bad strncpy pattern and return the list of affected source packages

### Symbol Usage Discovery for Maintainers

Upstream maintainers need to know who depends on a function before they remove or rename it. Debian Code Search answers 'which Debian packages call my function?' in a single GET /search call with a regex pinned to the function name. The agent forwards the result into deprecation notices to give downstream maintainers a heads-up.

Example prompt: Search /search for the regex 'my_old_function\\(' and produce a list of packages that still call it

### License and Copyright Auditing

License auditors inspect Debian packages for boilerplate copyright headers and unusual licence statements. The agent calls /search with regexes matching specific licence text and feeds matches into a compliance workflow. Catches packages that ship without expected GPL or BSD notices much faster than manual grep.

Example prompt: Call /search with a regex for a custom proprietary licence statement and report any matching package and file paths

### Agent-Driven Code Search via Jentic

An AI agent connected to Jentic can answer 'where in Debian is X used?' without holding the raw API key. Jentic stores the x-dcs-apikey in its vault, executes /search or /searchperpackage on the agent's behalf, and returns parsed matches. The agent only specifies the query; everything from auth to pagination is abstracted away.

Example prompt: Search Jentic for 'search Debian source code', load the GET /search schema, execute it with query=^OPENSSL_init and return the first 10 matches

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/search` | Run a regex search across Debian source code |
| GET | `/searchperpackage` | Aggregate regex matches per source package |

## Key resources

- **Search** — Run a regex search across the entire Debian source archive and read line-level matches
- **Search per package** — Run the same regex search but aggregate matches per source package for unique-package output

## Why Jentic

- **Setup:** Wiring Debian Code Search by hand means sending its x-dcs-apikey header, targeting codesearch.debian.net/api/v1, and assembling regex query parameters yourself. Through Jentic you install once, import Debian Code Search from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Debian Code Search passes the query in request parameters rather than a resource id in the URL path, so scope the agent by operations: limit it to the operations it needs, such as running a regex search or a per-package search. Both are read-only, so the operations you allow are the only ones that run.
- **Credential handling:** Your x-dcs-apikey value is stored once, encrypted, by your own Jentic One instance and injected at execution time as the x-dcs-apikey header. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search Debian source code' or 'group code search results per package', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **GitHub API** — GitHub's code search covers public GitHub repositories rather than the Debian archive
- **GitLab API** — GitLab's search API covers projects hosted on GitLab.com or self-managed GitLab instances
- **Snyk API** — Use Snyk for known-CVE matching; pair with Debian Code Search to find packages still carrying a vulnerable pattern even before a CVE is filed

## FAQ

### What authentication does the Debian Code Search use?

Debian Code Search uses an API key supplied in the x-dcs-apikey HTTP header. Keys are issued by the Debian Code Search service to registered users. Through Jentic the key is stored in the vault and never enters agent context.

### Can I run a regex search across all Debian source code?

Yes. GET /search accepts an RE2 regex via the q parameter and searches every indexed Debian source file. For deduplicated package-level results, call /searchperpackage with the same query so the response groups matches by source package.

### What are the rate limits for the Debian Code Search?

Debian Code Search does not publish a fixed public rate limit, but the service is operated by volunteers and enforces fair-use throttling. Back off on HTTP 429 responses and avoid running unbounded queries with very broad patterns.

### How do I aggregate matches per package through Jentic?

Search Jentic for 'aggregate Debian code search matches per package', load the GET /searchperpackage schema, and execute it with the regex query. Jentic injects the x-dcs-apikey from the vault and returns one result per source package.

### Does the Debian Code Search support full-text searches without regex?

All searches are RE2 regex queries. To match literal text, escape regex metacharacters before submitting the query - for example `strncpy\\(` to find calls to strncpy. The query language also supports filters such as path:, package:, and lang: to narrow the scope.

### Can I limit what my agent is allowed to do with the Debian Code Search API?

Yes. Because you self-host Jentic One, your own rules decide which Debian Code Search operations and credentials the agent may use, so you can grant it just the regex search on GET /search, just the per-package aggregation on GET /searchperpackage, or both. Debian Code Search passes the query in request parameters rather than a resource id in the URL path, so you scope the agent by operation rather than by target, and it can only call the operations you allow. Both endpoints are read-only, so the operations you permit are the only ones that ever run.