api

API Endpoints

Complete brin API reference. Artifact lookup, PR scanning, batch, search, trust graph. Every endpoint, parameter, and response shape.

base URL: https://api.brin.sh
auth: none.

##look up an artifact

GET/{origin}/{identifier}

look up a single artifact and get its security score.

Bash

# Packages
curl https://api.brin.sh/npm/express
curl https://api.brin.sh/npm/express@4.18.0
curl https://api.brin.sh/pypi/requests
curl https://api.brin.sh/crate/tokio
 
# Repositories
curl https://api.brin.sh/repo/expressjs/express
 
# Web
curl https://api.brin.sh/domain/example.com
curl https://api.brin.sh/page/example.com/docs
 
# AI components
curl https://api.brin.sh/mcp/owner/repo
curl https://api.brin.sh/skill/owner/repo
 
# Contributors
curl https://api.brin.sh/contributor/homanp
 
# Commits
curl https://api.brin.sh/commit/owner/repo@abc123def

supported origins:

Origin	What it scans	Identifier format	Example
`npm`	npm packages	`package` or `package@version`	`/npm/express`
`pypi`	PyPI packages	`package`	`/pypi/requests`
`crate`	Cargo crates	`package`	`/crate/tokio`
`repo`	GitHub repositories	`owner/repo`	`/repo/expressjs/express`
`domain`	Domains	`hostname`	`/domain/example.com`
`page`	Web pages	`hostname/path`	`/page/example.com/docs`
`mcp`	MCP servers	`owner/repo` or registry name	`/mcp/owner/repo`
`skill`	AI agent skills	`owner/repo` or `owner/repo/skill`	`/skill/owner/repo`
`email`	Emails	Message-ID (returned after POST)	`/email/msg-id@example.com`
`commit`	Git commits	`owner/repo@sha`	`/commit/owner/repo@abc123`
`contributor`	GitHub contributors	`username` or `github:username`	`/contributor/homanp`

query parameters:

Param	Type	Default	Description
`format`	`string`	`json`	response format: `json`, `simple`, or `badge`
`details`	`boolean`	`false`	include `sub_scores` in the response. forces `threats` to be included even for non-flagged results.
`refresh`	`boolean`	`false`	if the existing record is older than 24 hours, enqueue a fresh scan and return the current record with `pending_deep_scan: true`
`webhook`	`string`	`none`	callback URL for scan progress events. must start with `https://`, `http://localhost`, or `http://127.0.0.1`
`tolerance`	`string`	`conservative`	controls how the score maps to a verdict: `conservative`, `lenient`, or `yolo`. see safety tolerance
`mode`	`string`	`none`	if set to `full`, wait for the deep scan to complete and return a non-preliminary result. does not force Tier 3/LLM — Tier 3 still follows normal trigger rules

response:

JSON

{
  "score": 85,
  "verdict": "safe",
  "confidence": "high",
  "tolerance": "conservative",
  "url": "https://api.brin.sh/npm/express",
  "scanned_at": "2026-03-01T12:00:00Z"
}

with ?details=true:

JSON

{
  "origin": "npm",
  "name": "express",
  "score": 85,
  "verdict": "safe",
  "confidence": "high",
  "tolerance": "conservative",
  "scanned_at": "2026-03-01T12:00:00Z",
  "sub_scores": {
    "identity": 95.0,
    "behavior": 80.0,
    "content": 100.0,
    "graph": 70.0
  }
}

when verdict is suspicious or dangerous, a threats array is included:

JSON

{
  "score": 12,
  "verdict": "dangerous",
  "threats": [
    {
      "type": "install_attack",
      "severity": "critical",
      "detail": "postinstall script exfiltrates environment variables to external endpoint"
    }
  ]
}

##scan a pull request

GET/pr/{owner}/{repo}/{number}

scan a GitHub pull request by repository owner, repo name, and PR number.

brin stores the repository slug as name and the pull request number as version in the response.

Bash

curl "https://api.brin.sh/pr/owner/repo/123"

###request modes

by default, a cache miss returns a provisional response immediately and queues the full scan in the background:

Bash

curl "https://api.brin.sh/pr/owner/repo/123"

that fast response sets pending_deep_scan: true. the worker fetches the pull request from GitHub and runs the full scanner asynchronously.

for CI or blocking workflows, use mode=full:

Bash

curl "https://api.brin.sh/pr/owner/repo/123?mode=full&details=true"

with mode=full, the API enqueues the job and polls until the worker replaces the pending placeholder with the final result.

###how the PR scanner works

the full scanner combines GitHub metadata, aggregate diff analysis, and conditional LLM review.

Tier	What it does	Notes
Tier 1	Scores the PR author's identity using GitHub account age, contribution history, org memberships, prior commits to the target repo, email-domain reputation, and review status.	Always runs
Tier 2	Scores PR behavior and content using total change size, sensitive-file count, PR title/body quality, agent config changes, security tooling changes, CI workflow tampering, secret detection, comment injection, PR-description injection, and obfuscation heuristics.	Always runs
Tier 3	Prepares a workspace with `pr-description.txt`, `diff.patch`, and `metadata.json`, then asks OpenCode to look for backdoors, agent targeting, sabotage, and other semantic risk.	Runs only when triggered

Tier 3 is triggered when any of these are true:

agent config files were touched
a critical deterministic threat was found
sensitive files were changed
lower-trust authors need deeper review

###GitHub data used

the worker pulls these GitHub resources during the full scan:

GET /repos/{owner}/{repo}/pulls/{number} for PR metadata
GET /repos/{owner}/{repo}/pulls/{number}/reviews for approval state and reviewers
GET /repos/{owner}/{repo}/pulls/{number}/files for changed files and per-file patches
GET /repos/{owner}/{repo}/pulls/{number} with Accept: application/vnd.github.diff for the aggregate diff
contributor profile and org lookups for the PR author
repo-specific prior commit count for the PR author

###response

pass details=true to include sub-scores and all detected threats:

Bash

curl "https://api.brin.sh/pr/owner/repo/123?details=true&mode=full"

JSON

{
  "origin": "pr",
  "name": "owner/repo",
  "version": "123",
  "score": 68,
  "confidence": "medium",
  "verdict": "caution",
  "tolerance": "conservative",
  "scanned_at": "2026-03-26T12:00:00Z",
  "url": "https://api.brin.sh/pr/owner/repo",
  "sub_scores": {
    "identity": 74.0,
    "behavior": 55.0,
    "content": 72.0,
    "graph": null
  },
  "threats": [
    {
      "type": "agent_config_tampering",
      "severity": "high",
      "detail": "Agent config file modified: AGENTS.md"
    }
  ]
}

notes:

pending_deep_scan: true means you're still looking at a provisional or stale-refresh result.
graph is currently null for pull requests. the scanner emits graph edges, but PR graph scoring isn't active yet.

###webhooks

for async integrations, pass a webhook URL:

Bash

curl "https://api.brin.sh/pr/owner/repo/123?webhook=https://your-server.com/brin-callback"

accepted webhook URLs:

https://...
http://localhost/...
http://127.0.0.1/...

events arrive in this order:

Event	Description
`tier1_complete`	Author identity scoring finished
`tier2_complete`	Deterministic PR behavior and content checks finished
`tier3_complete`	LLM review finished, when Tier 3 ran
`scan_complete`	Final stored result

each event includes score, verdict, confidence, sub_scores, threats, and tiers_completed.

###threat types

the PR scanner emits these deterministic threat types, plus any matching Tier 3 findings:

Threat	Severity	Meaning
`first_time_contributor`	low	author has no prior commits to the target repository
`agent_config_tampering`	high / critical	agent instruction files were modified or newly added
`security_sabotage`	medium	security tooling config was modified
`supply_chain_mod`	critical	CI workflow patch contains remote script execution patterns
`credential_exposure`	critical	added lines contain secret or credential patterns
`obfuscation`	high	high-entropy additions suggest hidden or encoded payloads
`code_comment_injection`	high	added comments target AI reviewers or agents
`pr_injection`	critical	PR title or body contains AI-targeting instructions
`scan_error`	critical	the PR could not be fetched or parsed

###CI example

use mode=full in GitHub Actions when you want a single blocking response:

YAML

name: PR Security Scan
 
on:
  pull_request_target:
    types: [opened, reopened, synchronize, ready_for_review]
 
permissions:
  contents: read
  pull-requests: write
  issues: write
 
jobs:
  scan:
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    concurrency:
      group: brin-pr-${{ github.event.pull_request.number }}
      cancel-in-progress: true
 
    steps:
      - name: Scan PR with Brin
        id: scan
        shell: bash
        env:
          REPO: ${{ github.repository }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          set -euo pipefail
 
          RESPONSE=$(curl -sfL --max-time 300 \
            "https://api.brin.sh/pr/${REPO}/${PR_NUMBER}?mode=full&details=true&tolerance=conservative")
 
          SCORE=$(jq -r '.score' <<<"$RESPONSE")
          VERDICT=$(jq -r '.verdict' <<<"$RESPONSE")
          STATUS=clean
          SHOULD_FAIL=false
 
          if [ "$VERDICT" = "dangerous" ] || [ "$SCORE" -lt 30 ]; then
            STATUS=blocking
            SHOULD_FAIL=true
          elif [ "$VERDICT" = "suspicious" ]; then
            STATUS=review
          fi
 
          echo "score=${SCORE}" >> "$GITHUB_OUTPUT"
          echo "verdict=${VERDICT}" >> "$GITHUB_OUTPUT"
          echo "status=${STATUS}" >> "$GITHUB_OUTPUT"
          echo "should_fail=${SHOULD_FAIL}" >> "$GITHUB_OUTPUT"
 
          THREATS=$(jq -r '(.threats // [])[] | "- \(.type): \(.detail)"' <<<"$RESPONSE")
          {
            echo "threats<<BRIN_EOF"
            echo "$THREATS"
            echo "BRIN_EOF"
          } >> "$GITHUB_OUTPUT"

###safety tolerance

tolerance changes verdict thresholds without changing the raw score:

conservative — strictest, best for external or high-risk pull requests
lenient — treats scores 60+ as safe
yolo — treats scores 40+ as safe

Bash

curl "https://api.brin.sh/pr/owner/repo/123?mode=full&tolerance=lenient"

##batch lookup

POST/bulk

look up up to 100 artifacts in a single request.

Bash

curl -X POST https://api.brin.sh/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "lookups": [
      {"origin": "npm", "identifier": "express"},
      {"origin": "pypi", "identifier": "requests"},
      {"origin": "domain", "identifier": "example.com", "webhook": "https://your-server.com/cb"}
    ],
    "tolerance": "lenient"
  }'

response:

JSON

{
  "results": [
    {
      "score": 85,
      "verdict": "safe",
      "confidence": "high",
      "tolerance": "lenient",
      "url": "https://api.brin.sh/npm/express",
      "scanned_at": "2026-03-01T12:00:00Z"
    }
  ]
}

##list and search artifacts

GET/

list and search all scanned artifacts with filtering, sorting, and pagination.

Bash

# All dangerous npm packages
curl "https://api.brin.sh/?origin=npm&verdict=dangerous"
 
# Search by name
curl "https://api.brin.sh/?q=lodash"
 
# Only artifacts with threats, sorted by score ascending
curl "https://api.brin.sh/?has_threats=true&sort=score&order=asc"

query parameters:

Param	Default	Description
`origin`	—	filter by origin type (`npm`, `pypi`, `crate`, `repo`, `mcp`, `skill`, `domain`, `page`, `email`, `commit`, `contributor`)
`verdict`	—	filter by verdict (`safe`, `caution`, `suspicious`, `dangerous`)
`confidence`	—	filter by confidence (`low`, `medium`, `high`)
`min_score`	—	minimum score (0–100)
`max_score`	—	maximum score (0–100)
`has_threats`	—	`true` to only return artifacts with threats
`q`	—	full-text search on identifier
`sort`	`scanned_at`	sort field: `scanned_at`, `score`, `origin`, `identifier`
`order`	`desc`	sort direction: `asc`, `desc`
`limit`	`50`	results per page (max 200)
`offset`	`0`	pagination offset

response:

JSON

{
  "total": 142,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "origin": "npm",
      "identifier": "chalk",
      "version": "5.6.2",
      "score": 78,
      "verdict": "caution",
      "confidence": "medium",
      "scanned_at": "2026-02-26T13:44:34Z",
      "pending_deep_scan": false
    }
  ]
}

##query the trust graph

GET/graph/{origin}/{identifier}

query the artifact's neighborhood in the trust graph.

Bash

curl "https://api.brin.sh/graph/domain/vercel.com?depth=2"

query parameters:

Param	Default	Description
`depth`	`2`	traversal depth (1–5)

returns nodes and edges arrays for graph visualization.

##webhooks

when a webhook URL is provided, brin POSTs progress events as each scan tier completes. events are delivered with up to 3 retries.

events: tier1_complete, tier2_complete, tier3_complete, scan_complete

JSON

{
  "event": "scan_complete",
  "origin": "npm",
  "identifier": "express",
  "timestamp": "2026-03-01T12:00:30Z",
  "data": {
    "score": 85,
    "verdict": "safe",
    "confidence": "high",
    "sub_scores": {
      "identity": 95,
      "behavior": 80,
      "content": 100,
      "graph": 70
    },
    "threats": [],
    "tiers_completed": ["tier1", "tier2", "tier3"]
  }
}

##response headers

every response includes:

Text

x-brin-score:      85
x-brin-verdict:    safe
x-brin-confidence: high
x-brin-tolerance:  conservative

##error responses

JSON

{ "error": "not found" }

Status	Description
`200`	Success
`400`	Bad request
`404`	Entity not found
`500`	Server error

On this page

Share feedback