Documentation

Integrate CodeRecon into your CI pipeline, AI coding agent, or GitHub Actions workflow.

REST API

One endpoint. Submit 1–500 packages and get back risk scores for each. The full OpenAPI spec is available at /openapi.yaml.

Authentication

All requests require a Bearer token. Create an API key from your dashboard. 

Authorization: Bearer YOUR_API_KEY

POST /api/v1/checks

Request body

Field Type Required Description
registry string Yes rubygems, npm, or pypi
packages array Yes 1–500 objects, each with name and version

Example request

curl -X POST https://www.coderecon.com/api/v1/checks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "registry": "rubygems",
    "packages": [
      { "name": "nokogiri", "version": "1.16.5" },
      { "name": "devise", "version": "4.9.4" }
    ]
  }'

Example response

{
  "status": "complete",
  "package_count": 2,
  "results": {
    "nokogiri": {
      "version": "1.16.5",
      "status": "analyzed",
      "scores": {
        "license_compliance": {
          "score": 0.95,
          "confidence": 1.0,
          "analyzer": "static",
          "signals": [
            { "signal": "permissive_license", "description": "MIT license detected" }
          ]
        },
        "security_surface": {
          "score": 0.45,
          "confidence": 0.9,
          "analyzer": "static",
          "signals": [
            {
              "signal": "eval_usage",
              "description": "Dynamic code evaluation detected",
              "detail": ["lib/nokogiri/html5.rb:87"]
            }
          ]
        }
      }
    },
    "devise": {
      "version": "4.9.4",
      "status": "pending"
    }
  }
}

Result statuses

analyzed Analysis complete. Scores are included. This check is billable.
pending Package is known but analysis is still running. Not billed. Retry shortly.
unknown Package or version not found in the registry.

Facet scores

Each analyzed package returns scores across five facets. Scores range from 0 (high risk) to 1 (low risk).

Facet What it measures
license_compliance License permissiveness and compatibility
maintenance_health Release cadence, version count, staleness
supply_chain_integrity Maintainer changes, single-maintainer risk
security_surface Eval, system calls, native extensions, network calls
prompt_injection Prompt injection patterns in package files

Error responses

Status Meaning
401 Invalid or missing API key
422 Missing registry or too many packages (>500)
429 Rate limit or monthly quota exceeded

Billing

Each package with analyzed status counts as one billable check. Packages with pending or unknown status are not billed. Each (organization, package_version) pair is billed at most once per billing period, so re-checking the same versions costs nothing.

MCP Server

CodeRecon exposes package analysis as MCP tools so AI coding agents can check supply chain risk before adding or upgrading dependencies.

Setup

Add a .mcp.json file to your project root: 

{
  "mcpServers": {
    "coderecon": {
      "type": "http",
      "url": "https://www.coderecon.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

This works with Claude Code, Cursor, and any MCP-compatible client. The server uses the same API key authentication as the REST API.

Available tools

check_packages

Check supply chain risk for one or more packages (up to 500 per call). Omit version on any entry to check the latest.

Parameter Type Required Description
registry string Yes rubygems, npm, or pypi
packages array Yes Array of objects with name (required) and version (optional)

On-demand ingestion

If an MCP tool request references a package that isn't in the CodeRecon database yet, ingestion is automatically queued. The tool will return a message to retry shortly. Free plans are capped at 50 on-demand ingestions per billing period.

GitHub Actions

The official GitHub Action is coming soon. It will parse your lockfile, call the CodeRecon API, and annotate PRs with risk scores.

In the meantime, you can call the REST API directly from a workflow step: 

- name: Check dependencies
  run: |
    curl -sf -X POST https://www.coderecon.com/api/v1/checks \
      -H "Authorization: Bearer ${{ secrets.CODERECON_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "registry": "rubygems",
        "packages": [
          { "name": "rails", "version": "8.0.0" }
        ]
      }'

Rate limits and quotas

Both the REST API and MCP server share the same rate limits and query quotas.

Plan Checks / month Rate limit Overage
Free 200 10 req/min Hard block
Starter 2,000 30 req/min $0.07 / check
Team 10,000 60 req/min $0.05 / check
Pro 50,000 120 req/min $0.03 / check
Enterprise Custom Unlimited Custom