-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathapi-access.html
More file actions
178 lines (176 loc) · 9.71 KB
/
api-access.html
File metadata and controls
178 lines (176 loc) · 9.71 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="preload" href="/nipcode-logo.png" as="image" />
<link rel="stylesheet" href="/_next/static/chunks/0pwsw40vfluf4.css" />
<link rel="icon" href="/nipcode-logo.png" type="image/png" />
<title>API reference · Nipcode docs</title>
<meta name="description" content="Four endpoints, one auth header, read-only by design." />
<link rel="canonical" href="https://nipcode.xyz/api-access" />
<script src="/scramble.js" defer></script>
</head>
<body>
<a class="skip-link" href="#main">Skip to content</a>
<header class="topbar" aria-label="Primary">
<a class="brand" aria-label="Nipcode home" href="/">
<span class="nipcode-mark" aria-hidden="true" style="--mark-size: 54px"><img alt="" height="54" src="/nipcode-logo.png" width="54" /></span>
<span class="brand-word" aria-hidden="true">Nipcode</span>
</a>
<div class="brand-socials" aria-label="Nipcode links">
<a class="brand-docs-link" href="/docs">Docs</a>
<a class="brand-login-link" href="/account">Login</a>
<a class="brand-icon-button" href="https://github.com/trynipcode/nipcode" target="_blank" rel="noreferrer" title="GitHub" aria-label="GitHub"><img alt="" height="18" src="/github-logo.svg" width="18"/></a>
<a class="brand-icon-button" href="https://x.com/trynipcode" target="_blank" rel="noreferrer" title="X" aria-label="X"><svg aria-hidden="true" viewBox="0 0 24 24" width="18" height="18"><path d="M18.24 2.25h3.31l-7.23 8.26 8.5 11.24h-6.66l-5.21-6.82-5.97 6.82H1.67l7.73-8.84L1.25 2.25h6.83l4.71 6.23 5.45-6.23Zm-1.16 17.52h1.83L7.08 4.13H5.11l11.97 15.64Z" fill="currentColor"/></svg></a>
</div>
</header>
<main class="docs-shell" id="main">
<aside class="docs-sidebar" aria-label="Documentation">
<a class="docs-sidebar-title" href="/docs">Nipcode docs</a>
<nav class="docs-sidebar-nav">
<div class="docs-sidebar-group">
<p>Get started</p>
<div>
<a href="/docs">Overview</a>
<a href="/quickstart">Quickstart</a>
</div>
</div>
<div class="docs-sidebar-group">
<p>API</p>
<div>
<a class="docs-sidebar-active" aria-current="page" href="/api-access">API reference</a>
<a href="/agents">Agents</a>
<a href="/examples">Examples</a>
</div>
</div>
<div class="docs-sidebar-group">
<p>How it works</p>
<div>
<a href="/sources">Sources</a>
<a href="/trust">Trust model</a>
<a href="/architecture">Architecture</a>
<a href="/security">Security</a>
</div>
</div>
</nav>
</aside>
<article class="docs-main">
<header class="docs-hero">
<p class="docs-eyebrow" data-scramble-text data-scramble-duration="600">API reference</p>
<h1>Read-only package intelligence. Four endpoints, one auth header.</h1>
<p>Everything is GET, returns JSON, requires <code>x-nipcode-api-key</code>. Rate limit: 60 requests per minute per key.</p>
</header>
<section class="docs-section" id="search">
<div class="docs-section-head"><h2>GET /api/search</h2></div>
<div class="docs-prose">
<p>Fan-out search across selected source registries. Returns a ranked candidate list with source-owned metadata. Ephemeral by default.</p>
<h3>Parameters</h3>
<table>
<thead><tr><th>name</th><th>type</th><th>required</th><th>default</th><th>notes</th></tr></thead>
<tbody>
<tr><td><code>q</code></td><td>string</td><td>yes</td><td>,</td><td>free-text query</td></tr>
<tr><td><code>sources</code></td><td>string</td><td>no</td><td><code>npm,pypi,crates,github</code></td><td>comma-separated</td></tr>
<tr><td><code>limit</code></td><td>integer</td><td>no</td><td><code>5</code></td><td>1-20</td></tr>
</tbody>
</table>
<pre><code>curl -H "x-nipcode-api-key: $KEY" \
"https://nipcode.xyz/api/search?q=http+client&sources=npm,pypi&limit=5"</code></pre>
</div>
</section>
<section class="docs-section" id="decision">
<div class="docs-section-head"><h2>GET /api/decision</h2></div>
<div class="docs-prose">
<p>Search plus LLM-ranked recommendation. One call gives an agent everything it needs to ask the user for approval.</p>
<p>Parameters are the same as <code>/api/search</code>. Returns a <code>best</code> object with <code>decision_score</code>, <code>trust_score</code>, <code>risk_level</code>, <code>recommended</code>, a <code>proof</code> id, and 11 structured blocks (recommendation, why, risk, advisory, license, source_evidence, dependency_risk, malware_patterns, publisher, install_boundary, alternative).</p>
<pre><code>{
"best": {
"source": "npm",
"name": "fast-xml-parser",
"version": "5.8.0",
"decision_score": 90,
"trust_score": 85,
"risk_level": "low",
"recommended": true,
"proof": "c191e6c5ab30",
"blocks": {
"recommendation": "fast-xml-parser (npm) is the best starting point for this task.",
"why": "trust 85/100.",
"risk": "low. The selected source did not return readable license metadata.",
"license": "MIT (verified).",
"install_boundary": "npm install fast-xml-parser. Do not run it until the plan and local approval/sandbox check are accepted.",
"alternative": "date-format (npm, 80/100)."
}
},
"candidates": [...],
"note": "nipcode never installs, clones, or runs."
}</code></pre>
</div>
</section>
<section class="docs-section" id="inspect">
<div class="docs-section-head"><h2>GET /api/inspect</h2></div>
<div class="docs-prose">
<p>Refresh one exact source-owned record. Returns full license, maintainers, deprecation status, age, dependency tree depth, install-script presence, and a list of trust flags.</p>
<h3>Parameters</h3>
<table>
<thead><tr><th>name</th><th>type</th><th>required</th></tr></thead>
<tbody>
<tr><td><code>source</code></td><td>string</td><td>yes. One of npm, pypi, crates, github</td></tr>
<tr><td><code>name</code></td><td>string</td><td>yes</td></tr>
</tbody>
</table>
<pre><code>curl -H "x-nipcode-api-key: $KEY" \
"https://nipcode.xyz/api/inspect?source=npm&name=undici"</code></pre>
</div>
</section>
<section class="docs-section" id="install-plan">
<div class="docs-section-head"><h2>GET /api/install-plan</h2></div>
<div class="docs-prose">
<p>Lighter than <code>decision</code>. Returns the install command for a specific package, with warnings about install-script execution and unpinned versions.</p>
<pre><code>curl -H "x-nipcode-api-key: $KEY" \
"https://nipcode.xyz/api/install-plan?source=npm&name=undici&version=8.3.0"</code></pre>
</div>
</section>
<section class="docs-section" id="keys">
<div class="docs-section-head"><h2>Account & key management</h2></div>
<div class="docs-prose">
<p>These endpoints use the session cookie set by the email-OTP login (not the <code>x-nipcode-api-key</code> header). Sign in at <a href="/">nipcode.xyz</a> first.</p>
<h3>GET /api/keys</h3>
<p>List active keys for the signed-in account. Returns key value <strong>masked</strong> (<code>nip_8chars…last4</code>). Pass <code>?project=<name></code> to filter.</p>
<h3>POST /api/keys</h3>
<p>Body: <code>{"label": "production-cli", "project": "production"}</code>. <code>project</code> is normalized to lowercase slug (a-z, 0-9, <code>-</code>, <code>_</code>, max 30 chars), defaults to <code>default</code>. Returns the new key in plaintext. Copy now, you won't see it unmasked again.</p>
<p>Hard limit: <strong>25 active keys per account</strong> across all projects. Revoke unused keys first if you hit it.</p>
<h3>DELETE /api/keys?id=<uuid></h3>
<p>Soft-revoke: sets <code>revoked_at = now()</code>. The key stops working immediately on subsequent requests.</p>
<h3>GET /api/projects</h3>
<p>Aggregate view of all your project namespaces: <code>name</code>, <code>key_count</code>, <code>latest_created_at</code>, <code>latest_used_at</code>. <code>default</code> always appears, even if empty. Projects are organizational only; keys in any project have identical permissions and the same rate limit.</p>
</div>
</section>
<section class="docs-section" id="errors">
<div class="docs-section-head"><h2>Errors</h2></div>
<div class="docs-prose">
<table>
<thead><tr><th>HTTP</th><th>Code</th><th>Meaning</th></tr></thead>
<tbody>
<tr><td>400</td><td><code>missing parameter</code></td><td>Required parameter missing</td></tr>
<tr><td>401</td><td><code>missing_api_key</code> / <code>invalid_api_key</code></td><td>Send key in <code>x-nipcode-api-key</code></td></tr>
<tr><td>429</td><td><code>rate_limit_exceeded</code></td><td>60 req/min/key; retry after window</td></tr>
<tr><td>502</td><td><code>upstream search failed</code></td><td>Source registry temporarily down</td></tr>
<tr><td>503</td><td><code>supabase_not_configured</code></td><td>Server-side env missing</td></tr>
</tbody>
</table>
</div>
</section>
</article>
</main>
<footer class="site-footer" aria-label="Site footer">
<p class="site-footer-copy">Nipcode © 2026</p>
<nav class="site-footer-links" aria-label="Legal">
<a href="/changelog">Changelog</a>
<a href="/privacy">Privacy</a>
<a href="/terms">Terms</a>
<a href="/faq">FAQ</a>
</nav>
</footer>
</body>
</html>