Browse documentation

bbradar Pro guide

Pro API reference

Complete reference for authentication, platform and Self-Hosted data, MCP-efficient polling, endpoints, examples, responses, limits, and errors.

15 min read

Authentication

Every Pro API request uses your personal API key as a Bearer token. Keep the key in a server-side secret or MCP client environment—never in browser JavaScript or a public repository.

Base URL

http://ui/api

Request header

Authorization: Bearer YOUR_PRO_API_KEY

The complete secret is displayed once. Regenerating it immediately invalidates the previous key.

Manage API key

Make your first request

Start with capabilities so automation can negotiate the current contract without scanning catalog data.

curl -sS "http://ui/api/v1/pro/capabilities" -H "Authorization: Bearer YOUR_PRO_API_KEY"

Invalid query or path parameters return 400 with a detail message and an errors array. Authentication failures return 401; missing programs return 404.

Opportunity and Target Intelligence

Pro responses include structured signals that clients can display directly. Each field below has one job.

Program opportunity

opportunity_tag: Tier, score, factors, and the reason a program is highlighted.
submission_cost: Amount, optional maximum, unit, fee or deposit type, source, and observation time.

Target score

targetOpportunityScoretargetOpportunityLabel: A 0–100 score and its fixed Elite, Strong, Potential, or Normal label.
targetScoreBreakdownwhyThisTarget: The underlying factors and a concise human-readable explanation.

Competition risk

competitionRiskcompetitionRiskReason: Low, Medium, High, or Unknown, plus the evidence behind that classification.

Self-Hosted capability markers

Self-Hosted IDs use Self-Hosted:program-slug. Their data_capabilities object is authoritative: target inventory is returned, while report counts, opportunity scores, target-change history, submission costs, and repository changes are not invented when no source exists.

Target labels use fixed score bands: Elite Target is 85–100, Strong Target is 70–84, Potential Target is 50–69, and Normal is 0–49. Out-of-scope or explicitly ineligible targets do not receive Target Intelligence.

Efficient MCP polling

Use after_id for incremental feeds. Results are oldest-first; persist meta.next_after_id and send it with the next request. This skips total-count and facet work.

Target changes

curl -sS -G "http://ui/api/v1/pro/targets/changes" \
  --data-urlencode "after_id=48101" \
  --data-urlencode "page_size=50" \
  -H "Authorization: Bearer YOUR_PRO_API_KEY"

Repository summaries

curl -sS -G "http://ui/api/v1/pro/repositories/changes" \
  --data-urlencode "after_id=17041" \
  --data-urlencode "include_targets=false" \
  --data-urlencode "page_size=50" \
  -H "Authorization: Bearer YOUR_PRO_API_KEY"

Cursor mode requires page=1. Repository target-intelligence filters are page-only; indexed search, platform, tag, submission-cost, and visibility filters can be used with the cursor.

Endpoint reference

Expand an endpoint for its purpose, complete parameter list, cURL request, response shape, and common errors.

List active platform and Self-Hosted programs with server-side search, filters, and pagination.

Parameters

platforms (csv, optional)

Use platforms=Self-Hosted for only the Self-Hosted catalog

tags (csv, optional; scope, language, or target-type tags)

search (optional; name, handle, platform, policy host, or Self-Hosted target)

updated_since (ISO datetime, optional)

page (default: 1)

page_size (max: 100)

cURL example

curl -sS -X GET "http://ui/api/v1/pro/programs" \
  -G \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  --data-urlencode "search=example" \
  --data-urlencode "platforms=hackerone,bugcrowd,Self-Hosted" \
  -H "Authorization: Bearer YOUR_PRO_API_KEY"

Example response

{
  "programs": [
    {
      "id": "HackenProof:example-handle",
      "handle": "example-handle",
      "name": "Example Program",
      "platform": "HackenProof",
      "link": "https://hackenproof.com/programs/example-handle",
      "profile_picture": "https://example.com/logo.png",
      "scope_tags": ["domain", "api"],
      "added_at": "2026-03-04T12:10:00Z",
      "date_launched": "2026-03-04",
      "last_updated": "2026-04-16T07:45:02Z",
      "targets_updated_at": "2026-04-16T07:45:02Z",
      "bounty_min": 100,
      "bounty_max": 5000,
      "report_count": 353,
      "submission_cost": {
        "amount": 5,
        "unit": "USD",
        "kind": "fee",
        "source": "hackenproof_catalog",
        "updated_at": "2026-04-16T07:45:02Z"
      },
      "up_votes": 48,
      "down_votes": 3,
      "total_votes": 51,
      "net_score": 45,
      "vote_ratio": 0.9412,
      "star_rating": 4.7,
      "review_signal": "very_positive",
      "weighted_sentiment": 0.88,
      "competitionRisk": "Medium",
      "competitionRiskReason": "Estimated from high public report count, less obvious asset type.",
      "target_counts": {
        "total": 42,
        "in_scope": 38,
        "out_of_scope": 4,
        "eligible_for_bounty": 32,
        "wildcard": 7
      },
      "target_activity": {
        "latest_change_at": "2026-04-16T07:45:02Z",
        "latest_added_at": "2026-04-15T09:20:31Z",
        "added_24h": 3,
        "added_7d": 9,
        "removed_7d": 1
      },
      "extra_data": {
        "report_count": 353,
        "report_count_source": "reports_received_last_90_days",
        "report_count_label": "reports received (last 90 days)"
      }
    }
  ],
  "meta": { "page": 1, "page_size": 20, "total": 120, "total_pages": 6 }
}

Common errors: 401, 402, 423, 429

Rate and concurrency limits

ScopeLimitNotes

Programs and opportunities80 requests/min

/programs and /opportunities/{level} share this endpoint bucket.

Targets, search, and export40 requests/min

/programs/{program_id}/targets, /targets/search, and /targets/export share this endpoint bucket.

Target and repository changes30 requests/min

/targets/changes and /repositories/changes share this endpoint bucket.

Global key bucket120 requests/min, burst 300

Shared by all Pro API v1 requests for the same API key.

Per key + IP bucket60 requests/min

Applied to one API key from one source IP.

Concurrent requests8 per key, 3 change feeds

Target and repository changes share a smaller concurrent cap because they are the heaviest endpoints.

Distinct IP guard5 IPs/hour

Exceeding this locks the key for 10 minutes. Three locks in 24 hours locks it for 24 hours.

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 response also includes Retry-After.

Errors and retries

Retry only transient failures, reduce concurrency, and use jitter to avoid synchronized traffic.

400

Invalid parameter or request shape.

Correct the request; do not retry it unchanged.

401

Missing, malformed, revoked, or incorrect API key.

Check the Bearer header and the current key.

402

The account no longer has active Pro access.

Restore Pro access before retrying.

404

The requested program or resource was not found.

Verify the composite program ID and URL encoding.

423

The key is temporarily locked by abuse protection.

Stop traffic and wait until the lock expires.

429

A rate or concurrency limit was exceeded.

Honor Retry-After and retry with exponential jitter.