Attack Surface API
Get the board's data as JSON.
The API returns everything the board shows as read-only JSON. That includes report velocity, surge, crowding, and the enumerated attack surface for each program. The parameters and fields on this page were taken from live responses. Each call has a price in dollars, and you pay only for the calls you make.
How it works
Authentication
Send your key in an X-API-Key header on every request. An Authorization: Bearer header also works. Don't put the key in a URL. Each call checks that your subscription is active, so access stops as soon as it lapses. You can create and rotate your key on the key page.
# authenticate with a header, always over https curl -H "X-API-Key: bsk_live_xxxxxxxx" https://bugrater.com/api/v1/surface/programs # every billable response carries your cost and remaining balance X-Usage-Cost: 0.50 X-Balance-Remaining: 187.50
The response envelope
Every response is JSON, including errors. These three fields appear on every response. Each endpoint adds its own fields, listed below.
okboolean. true on success, false on an error.
cost_usdnumber. What this call cost you (0 on free calls and errors).
balance_usdnumber. Your remaining API balance after the call.
Discovery endpoints
https://bugrater.com/api/v1/surface/programs
$0.50
Every rated program with its rating, momentum and crowd data. Page through this call to decide which programs to pull in detail.
Query parameters
sort
score, surge, velocity, hunters
Default is score. score sorts the whole set. surge, velocity and hunters only sort within the returned page.
page
integer
Default 1.
limit
integer
Rows per page, default 50.
Response fields
sort, page, limit
echoed
Your query parameters, echoed back.
count
integer
Rows in this page.
total
integer
Rated programs in the whole set.
data
array
The rows.
id, name, slug, platform, url
mixed
Program identity and a link to its drill-down.
rating
number
Composite BugRater rating, 0 to 100.
status
string
heating, warming, steady, cooling.
surge_pct
number
Percent change in report intake compared with a week ago.
trend
integer
Direction of the surge as -1, 0 or 1.
reports_per_day
number
Reports received per day, 90-day average.
reports_90d
integer
Total reports in the last 90 days.
sparkline
array
Recent daily intake points, enough to draw the curve without another call.
hunters
integer
Participants on the program.
reports_per_hunter
number
reports_90d divided by hunters.
crowd
string
under-hunted, busy, crowded.
bounty_est
integer
Rough typical bounty in USD.
score_drivers
object
The six inputs behind the rating: bounty, crowding, response, freshness, surface, momentum.
surface
object
Enumeration depth: domains, wildcards, subdomains, subdomains_alive, signals, and signals_by_type (a typed count map, e.g. {"staging_env":4}).
scored_at
datetime
When this program was last scored.
https://bugrater.com/api/v1/surface/movers
$0.50
The two lists at the top of the board, in one call. One has programs that are heating up, the other has programs that are under-hunted but still active. Each entry is a full /programs scorecard row.
No parameters
Response fields
heating_up
array
Up to 5 programs with the biggest positive surge. Full scorecard rows (see /programs).
under_hunted
array
Up to 5 active programs with the fewest hunters. Full scorecard rows (see /programs).
https://bugrater.com/api/v1/surface/signals
$0.50
High-value signals across all programs, newest first. These include staging environments, exposed configs, and login and admin panels.
Query parameters
type
staging_env, exposed_config, login_page, admin_panel, debug_mode
Filter to one signal type.
severity
high, medium, low
Filter by severity.
page
integer
Default 1.
limit
integer
Default 50.
Response fields
count, total
integer
Rows in this page, and total rows matching the filter.
filters
array
The filters that were applied.
data
array
The signals.
hostname
string
The host the signal was found on.
signal_type
string
staging_env, exposed_config, login_page, admin_panel, debug_mode.
severity
string
high, medium, low.
title, detail
string
A plain-text description of what was found.
confidence
integer
Detector confidence, 0 to 100.
last_seen_at
datetime
When the scanner last confirmed it.
program
object
name and slug of the owning program.
https://bugrater.com/api/v1/surface/me
Free
Your plan, remaining balance, 30-day usage and the current price list. This call is free, so you can poll it as often as you like.
No parameters
Response fields
plan
string
attack_surface.
subscription_status
string
active while your subscription is live.
subscription_expires
datetime
When access ends unless renewed.
balance_usd
number
API dollars remaining.
usage_30d_usd, calls_30d
number
Amount spent and number of calls in the last 30 days.
rate_limit_per_min
integer
Requests per minute allowed.
prices
object
The live per-endpoint price map.
Program endpoints
{id} is the program id from any discovery row (the id field, or the last path segment of its url). An unknown id returns a 404, and an empty answer returns no rows; neither is charged.
https://bugrater.com/api/v1/surface/programs/{id}
$0.75
The program scorecard, with the composite rating, its six drivers and the market data.
No parameters
Response fields
program
object
id, name, slug, platform, url.
score
object
The rating and its drivers.
composite
number
The overall rating, 0 to 100.
bounty_norm, crowding_inv, response_qual, freshness, surface_area, state_momentum
number
The six drivers behind the composite.
bounty_est
integer
Rough typical bounty, USD.
domain_count, signal_count
integer
Number of root domains and signals we hold for the program.
market
object
Current report activity.
reports_90d, reports_per_day
number
Reports over 90 days, and per day.
hunters, reports_per_hunter
number
Crowd size and reports per hunter.
crowd, status
string
under-hunted/busy/crowded, and heating/warming/steady/cooling.
surge_pct, trend
number
Momentum percent, and its sign as -1/0/1.
sparkline
array
The recent daily intake points behind the trend.
surface
object
Enumeration depth: subdomains, subdomains_alive, and signals_by_type (a typed count map).
https://bugrater.com/api/v1/surface/programs/{id}/subdomains
$1.00
Enumerated subdomains, with each host's signals nested under it.
No parameters
Response fields
count
integer
Subdomains returned.
unattached_count
integer
Signals not tied to a specific enumerated host.
data
array
The subdomains.
subdomain
string
The host.
is_alive
boolean
Whether a probe answered.
http_status, dns_a, dns_cname
string/int
Probe and DNS results, null when not resolved.
source
string
How it was found, e.g. dns_brute.
last_seen_at
datetime
When it was last confirmed.
signals
array
The signals on this host: signal_type, severity, title, detail, confidence, last_seen_at.
https://bugrater.com/api/v1/surface/programs/{id}/signals
$0.75
This program's surface signals as a flat list, most severe first.
No parameters
Response fields
count
integer
Signals returned.
data
array
hostname, signal_type, severity, title, detail, confidence, last_seen_at per signal.
https://bugrater.com/api/v1/surface/programs/{id}/probes
$0.50
Live HTTP probe results for the program's hosts.
No parameters
Response fields
count
integer
Probes returned.
data
array
The probes.
url, hostname, scheme
string
What was probed.
status_code
integer
HTTP status, 0 when the host did not answer.
title, server, powered_by, content_type, redirect_url
string
Response fingerprints, null when absent.
probed_at
datetime
When the probe ran.
https://bugrater.com/api/v1/surface/programs/{id}/velocity
$0.50
The full daily intake series behind the sparkline, for your own trend analysis.
Query parameters
days
integer
Window length, default 90.
Response fields
window_days
integer
The window used.
reports_per_day, surge_pct
number
Reports per day and momentum.
series
array
One point per day: date and reports_90d.
https://bugrater.com/api/v1/surface/programs/{id}/full
$2.00
Everything for one program in a single call: scorecard, market, domains, subdomains with their signals, probes, and the flat signal list. It costs less than calling each endpoint separately.
No parameters
Response fields
program, score, market
object
Same as GET /programs/{id}.
domains
array
Root scopes: root_domain, is_wildcard, wildcard_pattern, eligible_bounty.
subdomains
array
Same as the subdomains endpoint, with signals attached.
probes
array
Same as the probes endpoint.
signals
array
Same as the program signals endpoint.
A real response
One row from GET /programs?sort=surge, as the API returns it.
{
"ok": true,
"cost_usd": 0.5,
"balance_usd": 199.5,
"sort": "surge", "page": 1, "limit": 1, "count": 1, "total": 153,
"data": [
{
"id": 5947, "name": "Early Warning", "platform": "hackerone",
"rating": 48.6, "status": "heating", "surge_pct": 35.9, "trend": 1,
"reports_per_day": 1, "reports_90d": 92,
"sparkline": [61, 63, 68, 74, 80, 85, 89, 92],
"hunters": 241, "reports_per_hunter": 0.36, "crowd": "under-hunted",
"bounty_est": 300,
"score_drivers": { "bounty": 18, "crowding": 20, "response": 9, "freshness": 2, "surface": 8, "momentum": 5 },
"surface": { "domains": 6, "subdomains": 118, "signals": 22, "signals_by_type": { "exposed_config": 7 } },
"url": "https://bugrater.com/scope/program/5947"
}
]
}
A full pull, step by step
# 1. find what is heating up (costs $0.50) curl -H "X-API-Key: $KEY" https://bugrater.com/api/v1/surface/movers # 2. check a candidate's market data (costs $0.75) curl -H "X-API-Key: $KEY" https://bugrater.com/api/v1/surface/programs/5947 # 3. pull its whole attack surface (costs $2.00) curl -H "X-API-Key: $KEY" https://bugrater.com/api/v1/surface/programs/5947/full # check your balance at any time (free) curl -H "X-API-Key: $KEY" https://bugrater.com/api/v1/surface/me
Errors
Errors are JSON too, with ok:false and a message. The codes are:
401 missing or invalid key, 403 no active subscription on the key, 402 balance too low for the call,
404 unknown program id (not charged),
429 over the rate limit (includes a Retry-After header).