BinShieldDemo

Reference

API Reference

All public REST endpoints for the BinShield platform. Base URL: https://binshieldapi-production.up.railway.app

OpenAPI spec

Packages

GET/health

Service health check and configuration.

curl "https://binshieldapi-production.up.railway.app/health"

GET/packages/search?q={query}

Search the public package database by name or keyword.

curl "https://binshieldapi-production.up.railway.app/packages/search?q=bcrypt"

GET/packages/:ecosystem/:name

List all analyzed versions of a package.

curl "https://binshieldapi-production.up.railway.app/packages/npm/bcrypt"

GET/packages/:ecosystem/:name/versions/:version

Retrieve full analysis for a specific version of a package.

curl "https://binshieldapi-production.up.railway.app/packages/npm/bcrypt/versions/5.1.1"

GET/packages/:ecosystem/:name/versions/:version/sbom

Export a CycloneDX 1.5 SBOM for a specific package version.

curl "https://binshieldapi-production.up.railway.app/packages/npm/bcrypt/versions/5.1.1/sbom"

GET/packages/:ecosystem/:name/diff?from={v1}&to={v2}

Binary behavior diff between two versions of a package.

curl "https://binshieldapi-production.up.railway.app/packages/npm/bcrypt/diff?from=5.1.0&to=5.1.1"

Advisories

GET/packages/:ecosystem/:name/advisories

Get known vulnerability advisories for a package (OSV, NVD, GitHub).

curl "https://binshieldapi-production.up.railway.app/packages/npm/bcrypt/advisories"

GET/advisories/recent

List recently published advisories across all packages.

curl "https://binshieldapi-production.up.railway.app/advisories/recent?limit=20"

POST/advisories/sync

Trigger advisory sync for a specific package from upstream sources.

curl -X POST "https://binshieldapi-production.up.railway.app/advisories/sync" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"ecosystem":"npm","packageName":"bcrypt"}'

Feed

GET/feed/events

Live stream of ecosystem analysis events (new packages, version updates, risk changes).

curl "https://binshieldapi-production.up.railway.app/feed/events?limit=50"

GET/feed/stats

Feed processing statistics — packages processed, native packages found.

curl "https://binshieldapi-production.up.railway.app/feed/stats"

Scans

POST/scans/packages

Submit a package for binary analysis. Returns a job ID for polling.

curl -X POST "https://binshieldapi-production.up.railway.app/scans/packages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"ecosystem":"npm","packageName":"bcrypt","version":"5.1.1"}'

GET/scans/:id

Poll scan job status and results. Status: queued → processing → complete.

curl "https://binshieldapi-production.up.railway.app/scans/scan_abc123" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY"

Lockfile Scanning

POST/scans/lockfile

Submit a lockfile for dependency-level risk scanning (package-lock.json, yarn.lock, pnpm-lock.yaml).

curl -X POST "https://binshieldapi-production.up.railway.app/scans/lockfile" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"filename":"package-lock.json","content":"..."}'

Organizations

GET/orgs/:orgId

Retrieve organization profile and usage summary.

curl "https://binshieldapi-production.up.railway.app/orgs/org_abc123" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY"

GET/orgs/:orgId/repos

List monitored repositories for an organization.

curl "https://binshieldapi-production.up.railway.app/orgs/org_abc123/repos" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY"

POST/orgs/:orgId/repos

Add a repository to the organization for monitoring.

curl -X POST "https://binshieldapi-production.up.railway.app/orgs/org_abc123/repos" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"githubRepo":"owner/repo"}'

GET/orgs/:orgId/watchlists

List watchlists for version-change alerts.

curl "https://binshieldapi-production.up.railway.app/orgs/org_abc123/watchlists" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY"

POST/orgs/:orgId/watchlists

Create a new watchlist with notification channel.

curl -X POST "https://binshieldapi-production.up.railway.app/orgs/org_abc123/watchlists" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"name":"Critical deps","channel":"slack","destination":"#security"}'

POST/orgs/:orgId/watchlists/:watchlistId/packages

Add a package to a watchlist.

curl -X POST "https://binshieldapi-production.up.railway.app/orgs/org_abc123/watchlists/wl_123/packages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"ecosystem":"npm","packageName":"sharp"}'

GET/orgs/:orgId/subscription

Get subscription details and plan limits.

curl "https://binshieldapi-production.up.railway.app/orgs/org_abc123/subscription" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY"

POST/orgs/:orgId/subscription

Update subscription plan and status.

curl -X POST "https://binshieldapi-production.up.railway.app/orgs/org_abc123/subscription" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"plan":"pro","status":"active"}'

GET/orgs/:orgId/api-keys

List API keys for the organization.

curl "https://binshieldapi-production.up.railway.app/orgs/org_abc123/api-keys" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY"

POST/orgs/:orgId/api-keys

Create a new API key.

curl -X POST "https://binshieldapi-production.up.railway.app/orgs/org_abc123/api-keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"label":"CI pipeline"}'

Compliance Reports

POST/orgs/:orgId/reports

Generate a compliance report (SOC 2, ISO 27001, or EU CRA).

curl -X POST "https://binshieldapi-production.up.railway.app/orgs/org_abc123/reports" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"reportType":"soc2"}'

GET/orgs/:orgId/reports

List previously generated compliance reports.

curl "https://binshieldapi-production.up.railway.app/orgs/org_abc123/reports" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY"

Invitations

POST/orgs/:orgId/invitations

Invite a user to join the organization.

curl -X POST "https://binshieldapi-production.up.railway.app/orgs/org_abc123/invitations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"email":"user@example.com","role":"member"}'

GET/orgs/:orgId/invitations

List pending invitations for the organization.

curl "https://binshieldapi-production.up.railway.app/orgs/org_abc123/invitations" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY"

POST/invitations/:token/accept

Accept an organization invitation using the invitation token.

curl -X POST "https://binshieldapi-production.up.railway.app/invitations/inv_token_abc/accept" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user_123"}'

Billing

POST/billing/checkout

Create a Stripe checkout session for plan upgrade.

curl -X POST "https://binshieldapi-production.up.railway.app/billing/checkout" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BINSHIELD_API_KEY" \
  -d '{"plan":"pro"}'

POST/billing/webhook

Stripe webhook handler for subscription lifecycle events.

# Handled automatically by Stripe