docs/API.md

API reference · v1

Base: https://wuhp-bbconnectapi.hf.space/api/v1

All endpoints are public. Do not send an API key, HF token, login cookie, or Authorization header. The deployment secret is unrelated to calling this API.

Interactive docs · OpenAPI JSON · Examples

List programs

GET /programs

Query parameter	Default	Meaning
platforms	hackerone	Comma-separated hackerone, bugcrowd, intigriti, yeswehack; case-insensitive
search	empty	Case-insensitive substring in name, handle, program URL, or website; not policy/asset text
bounty_only	false	Include only programs known to offer bounties; unknown status is excluded
include_details	false	Retrieve live rewards, scopes, rules, and tables for the selected page
limit	25	1–1000 for summaries; 1–100 with full details
offset	0	0–100000; use the returned next_offset
currency	unset	Three-letter currency code, case-insensitive; excludes unknown currencies
reward_at_least	unset	Require advertised directory max_bounty >= amount; requires currency
sort_by	name	name, max_bounty, or min_bounty; bounty sorting requires currency
descending	false	Reverse the selected sort; unknown bounty values always come last

curl 'https://wuhp-bbconnectapi.hf.space/api/v1/programs?platforms=hackerone&currency=USD&reward_at_least=1000&sort_by=max_bounty&descending=true&limit=10'

Filtering/sorting uses directory metadata before pagination and live enrichment. It does not fetch every program's reward table to decide eligibility. Missing snapshot currencies/reward values can exclude otherwise matching programs; use individual details for current values. No currency conversion is performed.

Response shape (illustrative values):

{
  "ok": true,
  "partial": false,
  "api_version": "1.0.0",
  "total": 200,
  "limit": 10,
  "offset": 0,
  "next_offset": 10,
  "include_details": false,
  "programs": [{
    "id": "hackerone:security",
    "platform": "hackerone",
    "handle": "security",
    "name": "HackerOne",
    "url": "https://hackerone.com/security",
    "offers_bounties": true,
    "min_bounty": 100,
    "max_bounty": 15000,
    "currency": "usd"
  }],
  "sources": {},
  "filters": {
    "currency": null,
    "reward_at_least": null,
    "reward_filter_source": "directory_metadata",
    "sort_by": "name",
    "descending": false
  }
}

The example is abbreviated; generated response models also allow native/source metadata. Optional detail fields are null in summary responses. total counts filtered directory programs, not only the returned page. next_offset: null means the crawl is finished. IDs include the platform; Intigriti uses its program UUID as handle because company URL slugs can repeat.

With include_details=true, each program also has targets, rules, reward_table, field_status, and details_source. Any failed/partial detail lookup makes the page partial: true; inspect each program rather than discarding the whole page.

Get program details

GET /programs/{platform}/{handle}

curl 'https://wuhp-bbconnectapi.hf.space/api/v1/programs/hackerone/security'

Use handles from /programs. Successful responses include:

Field	Description
ok, partial, api_version	Result status and REST contract version
platform, handle	Requested program identity
min_bounty, max_bounty, currency	Published numeric range and currency; null when unavailable
reward_table	Native severity/asset-tier table or grid, preserving its descriptions
targets.in_scope, targets.out_of_scope	Native platform records, kept separate
rules	Native policy sections; fields vary by platform, described below
field_status	Availability for scopes, rules, and ranges
mode	live or public_dataset
source_url, fetched_at, source_updated_at, cached, warning	Provenance, retrieval time, last edit if known, fallback/cache state

HackerOne rules include policy text, scope description, structured policy, disclosure/safe-harbor declarations, and exclusions. Bugcrowd includes brief HTML, targets overview, target-group instructions, safe harbor, resources, and VRT rules. Intigriti includes the latest in/out-of-scope text, FAQs, severity assessment, and rules of engagement/testing requirements. YesWeHack includes policy text/HTML, qualifying/non-qualifying vulnerabilities, account requirements, and relevant program rule grids.

Policy HTML is data, not trusted executable markup. Referenced external documents remain links; the API does not recursively crawl them. Absence of a rule never implies permission to test.

Fallback responses have partial: true: dataset scopes and known rewards may remain available, while rules is null and its field_status is unavailable. Live fields may be marked not_published rather than being invented. 0 is a published zero; null is not zero.

A missing or unreachable program returns 503 source_unavailable when no usable public data exists. The API cannot always distinguish an unknown program from upstream denial/outage, so it does not falsely claim a definitive program 404.

Normalized program assets

GET /programs/{platform}/{handle}/assets

Optional queries: asset_type, search, limit (1–1000, default 100), offset (default 0).

Common asset types: url, api, domain, wildcard, ip, ip_range, android, ios, device, other. Unsupported native categories become other, with their native type retained.

curl 'https://wuhp-bbconnectapi.hf.space/api/v1/programs/hackerone/security/assets?asset_type=wildcard&limit=20'

Each normalized record has identifier, type, native_type, instructions, eligible_for_bounty, and raw (the complete original record). Out-of-scope prose can be a native string, retained in raw.

Response fields: in_scope, out_of_scope, rules, source, field_status, total, limit, offset, next_offset, ok, partial, api_version, note.

Asset filtering and pagination apply only to in_scope. Every exclusion and the full program rules are retained. total is the filtered in-scope count. A wildcard never overrides an exclusion or a restriction in the rules. Group instructions remain in the native raw record.

Batch program details

POST /programs/batch

curl -X POST 'https://wuhp-bbconnectapi.hf.space/api/v1/programs/batch' \
  -H 'Content-Type: application/json' \
  -d '{"programs":[{"platform":"hackerone","handle":"security"},{"platform":"yeswehack","handle":"outscale"}]}'

Body: programs, an array of 1–20 objects containing platform and handle; unknown body fields are rejected. Results preserve input order (including duplicates), with individual statuses. Response: ok, partial, api_version, count, succeeded, programs.

If any lookup succeeds, HTTP status is 200, even when other items fail. If all fail, status is 503 with the same batch result envelope, so you can still inspect every item. A success that uses dataset fallback can itself be partial.

Service metadata

Endpoint	Behavior
GET /health	Application readiness/version, authentication_required: false, upstream_checked: false; no upstream calls
GET /sources	Per-platform capabilities, cache times, public-access status, and request limits; no upstream calls
GET /stats?platforms=hackerone,bugcrowd	Directory totals, known bounty counts, unknown bounty status, and source states; all four platforms by default

Healthy application status does not guarantee that every upstream platform is reachable. Stats do not fetch individual live detail documents. Free hosted Spaces can sleep, making the first request slow.

Errors, capacity, and retries

HTTP status	Meaning	Action
200	Successful response, possibly partial	Check ok, partial, and per-item/source states
400	Invalid filter combination/platform list	Fix the query; see error message
422	Invalid type, enum, bounds, or JSON body	Inspect error.details
429	Both REST collection slots are busy	Wait for Retry-After seconds, then retry
503	No usable upstream data, or every batch item failed	Retry with backoff; inspect fallback/field availability

Ordinary errors use:

{"ok":false,"api_version":"1.0.0","error":{"code":"invalid_filters","message":"Set currency when filtering or sorting by bounty amounts; currencies are never mixed."}}

Validation errors add error.details entries with location, message, type. All-failed batch responses use the batch envelope instead. Responses include X-API-Version. REST responses are not HTTP-cached (Cache-Control: no-store), while source data is shared in an in-memory cache.

REST collection capacity is two concurrent requests per application process, not a per-user key quota. Each batch/detail page uses at most four workers. Prefer summary listings, small full-detail pages, and bounded retries on 429/503. Do not run unbounded parallel crawls. There is no key to obtain or refresh.

Freshness and pagination

Successful source requests are cached for 900 seconds; failed requests for 60. The cache is lost on restart/sleep. There is no persistent database, background schedule, refresh-bypass parameter, or atomic multi-platform snapshot. Source fetched_at and source_updated_at have different meanings. Dates may be ISO timestamps or native upstream HTTP dates.

Offset pages can shift as directories change or caches expire. Follow next_offset and deduplicate by id for long crawls. Native rule and asset fields are intentionally preserved and can evolve with platforms; common REST envelope fields use the versioned /api/v1 path.

Gradio compatibility

The Gradio UI and event API remain at the same host/root paths.

Endpoint	Positional inputs	Behavior
/collect	[platforms, search, bounty_only, limit, offset]	Exactly five values; full details
/collect_options	[platforms, search, bounty_only, limit, offset, include_details]	Exactly six values; optional summary mode
/details	[platform, handle]	Complete live detail document
/scope	[platform, handle]	Alias of /details
/sources	[]	Source capabilities

Gradio /collect defaults to full details; REST /api/v1/programs defaults to summaries. This deliberate difference preserves existing clients.

For raw Gradio HTTP, POST {"data":[["hackerone"],"",false,10,0]} to /gradio_api/call/collect, read event_id, then GET /gradio_api/call/collect/EVENT_ID as an event stream. The complete event's JSON array contains the result at index 0; error events indicate processing failures. Heartbeats are not results. Python defaults cannot replace missing Gradio positional values.

New integrations should use REST unless they specifically need Gradio queue/event behavior.