Devnpm search · npm Registry

npm.search

Search the public npm registry without a provider API key. Supports npm text filters including keywords:, scope: and maintainer:. Pagination uses size (up to 250) and from. details retrieves full package metadata, version history and README when available.

POST/v1/capabilities/npm.search/execute

Charge returned per callStable

operationId: executeNpmSearch
Source: npm Registry
Typical credits: 0 (free source)
Search deadline: 15 s server-side
Paging: offset
Availability: ConfiguredChecked 2026-11-03 15:20 UTC

Cost basis

Free public npm API; no provider API key required. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request body

Body of POST /v1/capabilities/npm.search/execute, JSON, validated against the NpmSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of npm.search
Field	Description
textstringREQUIRED	npm search text; supports keywords:validation, scope:babel and maintainer:username.min length 1 · max length 1000
sizeinteger	Default `10`.min 1 · max 250
frominteger	Default `0`.min 0

Unknown keys are rejected with 400 invalid_request.

Examples

React tables

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/npm.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"react table","size":10,"from":0}'

Validation packages

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/npm.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"keywords:validation","size":5}'

Record fields

Each item in results[] carries record_id and title (contract, always present) and usually url and snippet. The other keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the NpmSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. Anything else comes from the provider and may change; see stability tiers.

Record keys of npm.search
Key	Note
record_idstringALWAYS	Use it with record actions on `POST /v1/follow-up`.
titlestringALWAYS	Contract key.
urlstring	Contract key; usually present.
snippetstring	Contract key; usually present.
packagestringALWAYS	On every record.
versionstring	When the source has it.
keywordsstring[]	When the source has it.
maintainersobject[]	When the source has it.
repositorystring	When the source has it.
linksobject	When the source has it.
scoreobject	When the source has it.
search_scorenumber	When the source has it.
published_atstring	When the source has it.

Caveats

Search filters are passed through in text. Full metadata details are subject to the 8 MiB upstream response limit.

Follow-ups

Paging: Provider offset; more fetches the next slice from the source.

moreNext page of the same search. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.

updateRe-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (NpmSearchUpdateParams).

detailsFull package metadata, all version manifests and README when available.

Detail behaviour: First details call fetches from the provider (billed as stated); repeats are cached and free. details is a free npm registry lookup.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/npm.search/execute", {
  body: {
    "text": "react table",
    "size": 10,
    "from": 0
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);

Recorded responseproduction · 27 Sep

Request

POST /v1/capabilities/npm.search/execute

{
  "text": "react table",
  "size": 10,
  "from": 0
}