> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygroundai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Package search API

> GET/POST /packages/search — search public npm or PyPI package source without pre-indexing.

# Package search API

Search the **source code** of a public **npm** or **PyPI** package on demand. Results include file paths and line ranges. Responses are cached for a period; repeated queries may be faster.

Authentication and search quota apply (same family as `/search`).

## Endpoints

```
GET /packages/search
POST /packages/search
```

## Parameters

<ParamField query="query" type="string" required>
  Search string (1–500 characters)
</ParamField>

<ParamField query="package_name" type="string" required>
  Package name (e.g. `express`, `requests`)
</ParamField>

<ParamField query="ecosystem" type="string" required>
  `npm` or `pypi`
</ParamField>

<ParamField query="version" type="string">
  Optional exact version
</ParamField>

<ParamField query="top_k" type="integer" default="10">
  Max results (1–50)
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.trygroundai.com/packages/search?query=Router&package_name=express&ecosystem=npm&top_k=10" \
    -H "Authorization: Bearer gnd_your_api_key"
  ```

  ```bash theme={null}
  curl -X POST https://api.trygroundai.com/packages/search \
    -H "Authorization: Bearer gnd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Router",
      "package_name": "express",
      "ecosystem": "npm",
      "top_k": 10
    }'
  ```
</RequestExample>

## Error codes (common)

| Code  | Meaning                      |
| ----- | ---------------------------- |
| `404` | Package/version not found    |
| `502` | Registry unavailable         |
| `413` | Package too large to process |
| `504` | Fetch timeout                |