API documentation

The same intelligence the web interface shows - lookups, search, and live SSVC decisions - served as a JSON API. No private, richer endpoint behind the curtain. Base URL: https://api.harpia.ae/api/v1. All responses are JSON, UTF-8. Machine-readable OpenAPI 3.1 spec - load it into Swagger UI, Postman, or openapi-generator to scaffold a client.

On this page: Quickstart · Authentication · Limits explained · Endpoints · Query language · Decisions · Use cases · Errors · Plans · FAQ

Want to evaluate first? The homepage search is the API with a face - no account needed. For programmatic access, three steps:

• Create a free account - email and a password, no card.
• Mint an API key on your account page.
• Send it as a Bearer token on every request.

export HARPIA_KEY="hpk_…"

# Is this CVE exploited?
curl -s -H "Authorization: Bearer $HARPIA_KEY" \
  "https://api.harpia.ae/api/v1/vulnerabilities/CVE-2024-3400" | jq '.x_intel_priority.exploit_maturity'

# Search the feed
curl -s -H "Authorization: Bearer $HARPIA_KEY" \
  "https://api.harpia.ae/api/v1/vulnerabilities/search?term=product:openssl+version:%3C3.0" | jq '.total'

# What should MY team do about it? (live SSVC decision)
curl -s -H "Authorization: Bearer $HARPIA_KEY" \
  "https://api.harpia.ae/api/v1/vulnerabilities/CVE-2024-3400/decision?exposure=exposed&mission_consequence=critical" \
  | jq '.x_intel_priority.decision'
# → "immediate"

API keys

Keys are minted and revoked on your account page (browser session only - a key can never mint another key). Send the key on every request:

Authorization: Bearer hpk_…

Key mechanics worth knowing:

• A key inherits its owner's plan live. Upgrade your plan and every key you hold gets the new limits on its very next request - no re-issue needed.
• Keys expire. You choose a lifetime (up to 365 days) at mint time. Expired or revoked keys return 401.
• Revocation is immediate. Deleting a key kills it on the next request.
• Key count is capped per plan (see plans). Rotate by minting the replacement first, switching your integration, then revoking the old key - zero downtime.

Anonymous access

Without a token you can browse the web app freely - search and CVE pages work signed out, showing the exploitation basics: the maturity ladder, CISA KEV, CVSS, severity, CWE, EPSS, the exploit-evidence count, fix status, and malicious-package flags. The remaining first-party momentum and plan feeds are quota-free.

Direct anonymous API calls are not supported: requests that don't come from the web app receive 401 with a pointer here. A free account gets you an API key, higher limits, proprietary scoring (trending and risk), the SSVC automatability input, and the live SSVC decision per CVE. Threat attribution, references, exploit repositories, bulk and delta-sync are Pro and up; the raw TAXII feed is Enterprise-only.

Your account carries two separate budgets: one for browsing this site, one shared by all of your API keys. They never draw from each other, so reading the site all day cannot exhaust the allowance your integration runs on. The browsing budget is deliberately generous; the API budget is the one sized to your plan.

Six independent mechanisms apply. Knowing which one you hit tells you exactly what to change:

Playing nicely with the limits

• Honor Retry-After. On 429, sleep the advertised seconds. Do not hammer - the bucket refills at a fixed rate regardless.
• Sync deltas, not snapshots. Poll /vulnerabilities/changes?since=… instead of re-fetching the world. A nightly delta is typically a few hundred records, not the entire corpus.
• Batch. One POST /vulnerabilities/lookup with 100 IDs costs one request, not 100. Same for POST /decisions/evaluate.
• Cache lookups briefly. Exploitation state changes on feed-build cadence (hours), not per second. A 15-minute local cache removes most duplicate traffic.
• One key per integration. Separate CI, SOC, and dashboards - one noisy pipeline then cannot starve the others, and usage stays attributable on the usage page.

Every public endpoint, its parameters and the plan it needs. Base URL https://api.harpia.ae/api/v1. The plan column is measured against the running API, not transcribed: anything below the listed plan gets 403.

Search

Lookup

Decisioning

curl -s -X POST \
  -H "Authorization: Bearer $HARPIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"components":[{"purl":"pkg:npm/lodash@4.17.20"}]}' \
  "https://api.harpia.ae/api/v1/inventory/match"

Bulk & sync (Pro and up)

Account

Browser session workflows

These routes belong to the first-party web app, not Bearer integrations. They are included here so the published HTTP contract matches the service.

Search response shape

{
  "total": 128,          // capped to your plan's reachable window
  "page": 1, "limit": 20,
  "results": [{
    "id": "CVE-2024-3400",
    "description": "…",
    "published": "2024-04-12",
    "severity": "CRITICAL", "cvss": 10.0,
    "exploit_maturity": "active",     // disclosed | poc | weaponized | active - every plan
    "exploited_in_wild": true, "exploit_count": 58,
    "weaponized": true, "cisa_kev": true,
    "is_automatable": true,           // SSVC automatability: registered plans and up
    "is_fixable": true,               // every plan
    "epss_score": 0.99,               // every plan
    "trend_level": "trending", "trending_score": 97.2,  // proprietary scoring: registered plans and up
    "ransomware_use": true,           // attribution fields: Pro and up
    "is_malicious": false, "malicious_packages": null, "ttps": [...],
    "cwe": ["CWE-77"], "aliases": ["USN-…","RHSA-…"]
  }],
  "facets": { "exploited": 12, "weaponized": 31, "ransomware": 4,
              "cisa_kev": 12, "critical": 40, "high": 55, "medium": 30,
              "low": 3, "malicious": 0 }
}

The term parameter accepts everything the search box does. AND is implicit; OR, NOT, quoted phrases and parentheses are supported. Negation binds to a whole qualifier or group, so kev:true NOT ssvc:active and NOT (kev:true OR trend:trending) both do what they look like. - and ! are accepted as shorthand for NOT; the examples here spell it out because a leading hyphen is easy to misread next to ids and hyphenated words.

Ordinary searches return CVEs and malicious-package findings. Advisory restatements stay hidden so counts and remediation decisions are not duplicated. Enter an advisory id to resolve it to the CVE or CVEs it covers, or use type:osv_advisory when the advisory records themselves are required.

Worked examples

Each of these runs as-is. The attribution and ATT&CK ones need Pro.

Severity describes a bug; a decision tells a team what to do. Select one framework per request. The endpoint merges locked feed facts with your context:

GET /vulnerabilities/CVE-2024-3400/decision?framework=harpia_ssvc&exposure=exposed&mission_consequence=critical

{
  "cve_id": "CVE-2024-3400",
  "framework": "harpia_ssvc",
  "inputs": {
    "framework": {"value":"harpia_ssvc", "source":"customer", "defaulted":false},
    "exposure": {"value":"exposed", "source":"customer", "defaulted":false},
    "mission_consequence": {"value":"critical", "source":"customer", "defaulted":false}
  },
  "x_intel_priority": {
    "decision": "immediate",
    "exploit_maturity": "active", "exploited_in_wild": true,
    "is_automatable": true,
    "epss_score": 0.99, "attack_vector": "NETWORK",
    "outcome": "Priority: immediate - … Exploitation=active, Exposure=exposed, …"
  },
  "policy_evaluated": true,
  "engine_version": "harpia-decision-v3",
  "facts": {
    "exploitation": {"value":"active", "source":"harpia"},
    "automatable": {"value":true, "source":"harpia"},
    "technical_impact": {
      "reported": {"value":"total", "source":"cisagov_ssvc"},
      "derived": {"value":"total", "source":"harpia", "method":"cvss_v3_ci_v1"},
      "effective": {"value":"total", "method":"conservative_max"},
      "conflict": false
    }
  },
  "guidance": {
    "id": "harpia_ssvc",
    "framework": "Harpia SSVC",
    "source": "Harpia SSVC priority-to-timeline policy",
    "reference": "https://harpia.ae/decisions#harpia-ssvc",
    "timeline": "3_days",
    "label": "3 days",
    "window_days": 3,
    "requires_forensic_triage": false,
    "discovered_at": "2026-08-24",
    "due_date": "2026-08-27",
    "overdue": false,
    "criteria": {"priority":"immediate"}
  }
}

Select framework=bod_26_04 for the CISA timeline based on Publicly Exposed, On KEV, Automatable, and Technical Impact. BOD mode does not return a Harpia priority.

Decisions are computed live by the policy engine on every request - never cached, never pre-baked - so a CVE that gets weaponized overnight changes its answer the moment the feed updates.

CI/CD gate - block deploys on exploited dependencies

Parse the inventory locally and fail the build when something actively exploited ships in the artifact:

harpia scan --output json bom.json > scan.json

n=$(jq '[.findings[] | select(.vulnerability.maturity == "active" or .vulnerability.kev)] | length' scan.json)
[ "$n" -gt 0 ] && { echo "BLOCK: $n actively exploited findings"; exit 1; }

Nightly patch queue - rank by decision, not by CVSS

# 1. delta since last run (cheap - only what changed)
#    → {"count": 464, "ids": ["CVE-…", …]}
curl -s -H "Authorization: Bearer $HARPIA_KEY" \
  "https://api.harpia.ae/api/v1/vulnerabilities/changes?since=2026-07-16" > delta.json

# 2. one bulk decision call for the changed IDs under your context
#    (chunk into batches of 500 when the delta is bigger)
jq '{ids:.ids[:500], exposure:"controlled", mission_consequence:"high"}' delta.json \
| curl -s -H "Authorization: Bearer $HARPIA_KEY" -H "Content-Type: application/json" \
  -d @- "https://api.harpia.ae/api/v1/decisions/evaluate" \
| jq '.results | to_entries[]
      | select(.value.x_intel_priority.decision | IN("immediate","out_of_cycle"))
      | .key'

Two requests per night for a typical delta, regardless of estate size.

SOC alert enrichment

An IDS alert names a CVE. One call answers "is this noise or an incident?":

curl -s -H "Authorization: Bearer $HARPIA_KEY" \
  "https://api.harpia.ae/api/v1/vulnerabilities/$CVE/decision?exposure=exposed&mission_consequence=critical" \
| jq '{decision:.x_intel_priority.decision, wild:.x_intel_priority.exploited_in_wild,
       automatable:.x_intel_priority.is_automatable}'

Wire it into the SOAR playbook: immediate → page on-call; anything else → enrich the ticket and move on.

Threat-intel platform ingestion (STIX/TAXII)

MISP, OpenCTI, and every TAXII 2.1 client can subscribe directly - no custom code:

curl -H "Accept: application/taxii+json;version=2.1" \
  "https://harpia.ae/threatintel/"                      # discovery
curl -H "Accept: application/taxii+json;version=2.1" \
  "https://harpia.ae/threatintel/collections/"          # collections

Objects are STIX 2.1 (vulnerabilities, relationships, ATT&CK mappings). Browse interactively with the STIX explorer.

Vendor exposure watch

A weekly report of what is being hit in your vendor stack:

curl -s -H "Authorization: Bearer $HARPIA_KEY" \
  "https://api.harpia.ae/api/v1/vulnerabilities/search?term=vendor:paloaltonetworks+exploited:true&sort=trending" \
| jq '.results[] | {id, exploit_maturity, trend_level}'

Plans, limits, and the full feature matrix live in one place - see plans on the intelligence page, which now includes a Signed out column so you can see what an account actually changes.

Every account carries two separate budgets - one for browsing this site, one shared by all of your API keys - and they never draw from each other. Your live figures are on the usage page, and a banner appears once either passes 80%.

How fresh is the data?

The feed rebuilds continuously from upstream sources (NVD, OSV.dev, CISA KEV, EPSS, exploit telemetry). A CVE's exploitation state changes within hours of public evidence, and SSVC decisions reflect it on the next request - decisions are never cached.

How do I upgrade?

Harpia is invite-reviewed - we take on a limited number of accounts and read every request. Request access from your account and tell us what you're building; we reply to your account email, usually within a day or two.

I upgraded - when do the new limits apply?

On your very next request. Keys resolve their owner's plan live; nothing to re-issue.

Can I use the API from a browser app?

The API is same-origin by design and does not emit CORS headers. Call it from your backend - which is also where your key belongs. Browser sessions (the web UI) authenticate with an HttpOnly cookie instead of a key.

Does TAXII need authentication?

/taxii2/ discovery is public. STIX search requires Pro or above, and raw collection, object, version, and manifest access requires an Enterprise key.

A CVE's state looks wrong.

Send the ID and evidence to feed@harpia.ae - corrections ship with the next feed build.

Something else?

Contact lists the right inbox for every topic - support, sales, security reports, and data corrections.