Skip to content

public-api.md

Latest commit

 

History

History
89 lines (51 loc) · 2.45 KB

public-api.md

File metadata and controls

89 lines (51 loc) · 2.45 KB

Public API spec

OpenAPI-style summary of all public endpoints. Full live OpenAPI document is planned.

Base URL

https://nipcode.xyz

Auth

All /api/* endpoints accept an API key via the x-nipcode-api-key header. Auth endpoints (/api/auth*) do not require an API key.

Endpoints

GET /api/search

Search across source registries.

Query parameters:

name type required default notes
q string yes , free-text query
sources string no npm,pypi,crates,github comma-separated
limit int no 5 1-20

Returns: 200 with candidate list. See search-inspect-install-plan.md for shape.

GET /api/decision

Search + LLM-ranked recommendation.

Query parameters: same as search.

Returns: 200 with best candidate, full candidate list, and note reminder. See search-inspect-install-plan.md.

POST /api/auth

Send email OTP code.

Body: { "email": "..." }

Returns:

  • 200 { ok: true, step: "verify", email } when OTP sent
  • 400 if email invalid
  • 429 if rate limit exceeded (Supabase 4/hour on built-in SMTP)

POST /api/auth/verify

Verify the OTP code and create a session.

Body: { "email": "...", "code": "123456" }

Returns:

  • 200 { ok: true, email, apiKey, userId, via } + sets nipcode_session cookie
  • 401 on invalid or expired code
  • 503 if Supabase not configured

GET /auth/sign-out

Clears the session cookie. Returns 303 redirect to /.

Error format

{ "error": "machine-readable code" }

Common codes: invalid_email, email rate limit exceeded, invalid_code, upstream search failed, supabase_not_configured.

CORS

All /api/* endpoints set:

  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Methods: GET, POST, OPTIONS
  • Access-Control-Allow-Headers: Content-Type, x-nipcode-api-key

Public read API is intentionally CORS-open. Auth endpoints rely on session cookies, which are SameSite=Lax and not exposed to cross-origin XHR.

Caching

/api/search and /api/decision responses are cached at the Vercel edge for max-age=60, s-maxage=300. Auth endpoints send Cache-Control: no-store.

Rate limits

Beta: 60 requests / minute per API key. The auth send-OTP endpoint is additionally bound by Supabase's built-in SMTP limit (currently 4 emails / hour / project).