API

One package API for agents.

Agents call Nipmod before choosing dependencies, models or MCP tools. The API returns source context, trust signals and install plans. It does not install anything by itself.

OpenAPI
3.1
Public beta
free, rate limited
Hosted writes
0

Use it in one prompt

Use Nipmod before choosing a package.
Search for candidates, inspect the selected record, then show me the install plan before changing the workspace.

Agent-readable entrypoints

The human page explains the beta surface, access rules and safety boundary. Agents should read the machine surfaces first, then call the API only after they understand the flow.

/llms.txt gives agents the workflow and safety rules without layout copy. The discovery manifest describes the public surfaces. /api/openapi is the contract for generated clients, tests and agent tools.

Read these first:
https://nipmod.com/llms.txt
https://nipmod.com/.well-known/nipmod.json
https://nipmod.com/api/openapi

Three calls

  1. 1

    Search

    Find candidates across supported public sources. Search returns a shortlist, not install permission.

  2. 2

    Inspect

    Read one exact package record with source links, version, license, warnings and trust factors.

  3. 3

    Install Plan

    Return commands and risk context for user review. Hosted API calls never execute commands.

curl 'https://nipmod.com/api/search?q=http%20client&limit=3'
curl 'https://nipmod.com/api/inspect?source=npm&name=undici'
curl 'https://nipmod.com/api/install-plan?source=npm&name=undici'

Endpoints

Search
GET /api/search?q=<query>&sources=<sources>&limit=5
Ranked candidates from npm, PyPI, GitHub, Hugging Face and MCP.
Inspect
GET /api/inspect?source=npm&name=undici
One exact record with source, trust, license, metrics and warnings.
Install Plan
GET /api/install-plan?source=npm&name=undici
Commands for review. The hosted API does not write to the workspace.
Archive Prepare
GET /api/archive/prepare?source=npm&name=undici
Preview a reusable archive record after useful discovery.
Source Health
GET /api/sources/health
Configured source capabilities and bounded source checks.
Usage Stats
GET /api/usage/stats?hours=24
Admin-only aggregate route, source, traffic-origin, trust, install-plan and archive metrics.
Beta Key
POST /api/keys/beta
Self-service beta API key. The raw key is returned once and stored only as a keyed hash.
MCP
POST /api/mcp
Read-only MCP JSON-RPC surface over the same hosted API.
OpenAPI
GET /api/openapi
Contract for generated clients, tests and agent tool schemas.

Access and API keys

Public beta
No API key is required today.
Every public request is rate limited.
Free beta keys
POST /api/keys/beta
Issued directly by the API for higher shared beta limits. They do not unlock private sources.
Partner keys
Authorization: Bearer <key>
Higher limits for integrations and agent hosts. Usage is grouped by key id.
Admin keys
GET /api/usage/stats
Operational metrics only: routes, sources, traffic origins, trust decisions, install plans and archive writes.
Key storage
Raw keys are not stored.
Issued keys are verified against server-side hashes and exposed only as a key id in usage events.
Private data
Do not send secrets in labels.
The self-service endpoint stores a non-private label, tier, key id, hash and expiry only.
curl 'https://nipmod.com/api/search?q=http%20client&limit=3' \
  -H 'x-nipmod-api-key: <key>'

curl 'https://nipmod.com/api/usage/stats?hours=24' \
  -H 'authorization: Bearer <admin-key>'

Self-service beta keys

Agents can issue a beta key without a human handoff. The endpoint is public and rate limited. It returns the raw key once, then Nipmod keeps only a keyed hash for verification.

curl -s -X POST 'https://nipmod.com/api/keys/beta' \
  -H 'content-type: application/json'

curl 'https://nipmod.com/api/search?q=http%20client&limit=3' \
  -H 'x-nipmod-api-key: <returned-key>'
Read https://nipmod.com/api/openapi.
If you need a higher beta limit, POST https://nipmod.com/api/keys/beta.
Store the returned key in local secrets and use it as x-nipmod-api-key.
Do not send prompts, user data, API keys or workspace paths.

Usage and statistics

Without a key
Nipmod counts requests by a privacy-safe client hash.
Useful for public beta traffic and source usage.
With a key
Usage is grouped by API key id and access tier.
Useful for counting beta callers, projects and agent hosts.
Stored fields
Route, status, source, traffic origin, result count, duration, trust decision, install-plan boundary and archive outcome.
Queries and package names are hashed before storage.
Metrics endpoint
Admin key required.
Returns aggregate counts for routes, sources, access tiers, traffic origins, install plans, archive writes and trust outcomes.
Not stored
No raw API keys, raw IPs, raw queries, package names or user-agent fingerprints.
The analytics layer is intentionally privacy limited.

Response shape

Search

Candidate record

{
  "id": "npm:undici",
  "source": "npm",
  "name": "undici",
  "version": "8.3.0",
  "trust": {
    "score": 100,
    "decision": "recommended",
    "risk": "low"
  },
  "archive": {
    "persistence": "ephemeral"
  }
}
Install Plan

Approval boundary

{
  "commands": ["npm install undici"],
  "requiresApprovalBeforeWrite": true,
  "hostedApiExecutes": false,
  "metadataIsInstruction": false,
  "boundary": "manual-after-user-approval",
  "risk": "low"
}

Trust fields agents should read

score
A numeric review signal from source metadata, security evidence, warnings and plan risk.
Not install permission.
decision
recommended
May still require user approval before any workspace write.
risk
low
Risk level for the selected record and install-plan context.
warnings
Human-readable warnings for lifecycle scripts, weak metadata, remote-code risk or degraded source data.
Agents should show these before recommending the package.
archive.persistence
ephemeral
Search alone does not create a verified Nipmod package.

Errors

Errors are structured data. Agents should not retry blindly or hide the cause from the user. Common cases include invalid source, missing package name, upstream timeout, source unavailable, rate limit and malformed MCP request.

{
  "error": {
    "code": "invalid_source",
    "message": "Unsupported source.",
    "requestId": "req_...",
    "retryable": false
  }
}

Rate limits and versions

Public beta
No key is required. Requests are rate limited to keep the shared API reliable.
Higher limits can be added later without changing the core API flow.
API version
The public OpenAPI contract is the stable builder reference during beta.
GET /api/openapi
Breaking changes
Search, Inspect and Install Plan should remain the core flow. New fields should be additive where possible.
Agents should ignore fields they do not understand.
Hosted boundary
Hosted calls can search, inspect and plan. They cannot execute commands or read local files.
Workspace writes belong to the user's local host after approval.

Client examples

Use the TypeScript and Python examples for agent hosts that call Nipmod through HTTPS. Use the MCP endpoint when the host prefers JSON-RPC tools over direct HTTP calls. Both paths keep the same safety boundary.

node --experimental-strip-types examples/http-api/agent-flow.ts "http client"
python3 examples/http-api/agent_flow.py "http client"
curl 'https://nipmod.com/api/openapi'
curl -s https://nipmod.com/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'