API Reference — Blackfyre GovCon Intelligence API

Overview

Authentication

All API requests require an API key passed in the X-API-Key request header. Keys are prefixed with bk_live_ for production.

Getting an API key

Sign up for a Developer or Platform plan at blackfyre.ai/checkout. Your API key is generated instantly on checkout and accessible from your dashboard.

Key security

Keep your API key secret. Never expose it in client-side JavaScript or public repos. Rotate compromised keys immediately from your dashboard. Keys are hashed — Blackfyre cannot recover a lost key.

curl

# Pass your API key in the X-API-Key header
curl -H "X-API-Key: bk_live_YOUR_KEY" \
  https://api.blackfyre.ai/v1/opportunities

Overview

Rate Limits

Rate limits are enforced per API key on a rolling 30-day window. The X-RateLimit-Remaining and X-RateLimit-Reset headers are included on every response.

Developer

10,000 requests / month

Platform

Unlimited

Exceeding the monthly limit returns 429 Too Many Requests. Each list endpoint defaults to 25 results; increase with the limit param (max 100) to reduce call count for bulk operations.

Overview

Error Codes

All errors return a JSON body with an error string and a machine-readable code.

HTTP Status	Code	Description
401	UNAUTHORIZED	Missing or invalid `X-API-Key`. Check that your key is correct and hasn't been revoked.
429	RATE_LIMIT_EXCEEDED	Monthly request quota exhausted. Upgrade to Platform or wait for reset.
400	VALIDATION_ERROR	A required parameter is missing or a value is out of the allowed range.
404	NOT_FOUND	The requested resource does not exist.
500	SERVER_ERROR	Unexpected server error. These are logged and investigated automatically.

            Error response
          
{
  "error": "API key is invalid or has been revoked",
  "code":  "UNAUTHORIZED"
}

Opportunities

List Opportunities

GET /v1/opportunities

Returns a paginated list of federal contract opportunities sourced from SAM.gov. Filter by NAICS, set-aside type, agency, notice type, deadline, and wired probability score. Results are ordered by most recently updated.

Query Parameters

Name	Type	Req	Description
naics	string	opt	6-digit NAICS code (e.g. `541511`)
set_aside	string	opt	Set-aside type: `8a`, `sdvosb`, `wosb`, `hubzone`
agency_id	uuid	opt	Filter by awarding agency UUID
notice_type	string	opt	SAM.gov notice type: `Solicitation`, `Sources Sought`, `Award`
state	string	opt	2-letter place of performance state (e.g. `VA`)
response_before	date	opt	ISO 8601 date — only return opps with deadline before this date
response_after	date	opt	ISO 8601 date — only return opps with deadline after this date
wired_min	float	opt	Minimum wired probability score 0.0–1.0
drift_alert	boolean	opt	Pass `true` to return only opps with a requirement drift alert
limit	integer	opt	Results per page. Default 25, max 100.
offset	integer	opt	Pagination offset. Default 0, max 10000.

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  "https://api.blackfyre.ai/v1/opportunities\
?naics=541511\
&set_aside=sdvosb\
&state=VA\
&limit=10"

Response

                json
              
{
  "data": [
    {
      "id": "9f2c1a3e-...",
      "notice_id": "VA-25-IT-0042",
      "title": "Cybersecurity Operations Support",
      "notice_type": "Solicitation",
      "naics_code": "541511",
      "set_aside_type": "SDVOSB",
      "place_of_performance_state": "VA",
      "response_deadline": "2026-05-30",
      "estimated_value_low": 2500000,
      "estimated_value_high": 3200000,
      "wired_probability_score": 0.31,
      "requirement_drift_alert": false,
      "amendment_count": 1,
      "updated_at": "2026-05-13T14:22:00Z"
    }
  ],
  "meta": {
    "total": 847,
    "limit": 10,
    "offset": 0
  }
}

Opportunities

Search Opportunities

GET /v1/opportunities/search

Keyword search across opportunity titles and descriptions. Automatically uses semantic vector search when available, falling back to keyword matching. Returns the most relevant matches for your query.

Query Parameters

Name	Type	Req	Description
keyword	string	req	Search term — title and description are searched. Max 500 chars.
agency	string	opt	Partial agency name (e.g. `Department of Veterans`)
naics	string	opt	6-digit NAICS code
set_aside	string	opt	Set-aside shorthand: `8a`, `sdvosb`, `wosb`, `hubzone`
limit	integer	opt	Max 50. Default 25.
offset	integer	opt	Pagination offset. Default 0.

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  "https://api.blackfyre.ai/v1/opportunities\
/search?keyword=zero+trust+architecture\
&agency=Department+of+Defense\
&limit=10"

Response

json
{
  "data": [ /* opportunity objects */ ],
  "meta": {
    "total": 23,
    "limit": 10,
    "offset": 0,
    "source": "semantic"
  }
}

Opportunities

Get Opportunity

GET /v1/opportunities/:id

Returns a single opportunity with full detail — including the linked agency, contracting office, contracting officer, and incumbent vendor profile.

Path Parameters

Name	Type	Req	Description
id	uuid	req	Opportunity UUID from the list or search response

Related sub-endpoints on an opportunity:

GET /v1/opportunities/:id/amendments

GET /v1/opportunities/:id/competitors

GET /v1/opportunities/:id/pwin

GET /v1/opportunities/:id/lineage

GET /v1/opportunities/:id/matrix

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  https://api.blackfyre.ai/v1/opportunities\
/9f2c1a3e-4b5d-6e7f-8a9b-0c1d2e3f4a5b

Response

json
{
  "data": {
    "id": "9f2c1a3e-...",
    "title": "Cybersecurity Operations Support",
    "notice_type": "Solicitation",
    "naics_code": "541511",
    "set_aside_type": "SDVOSB",
    "response_deadline": "2026-05-30",
    "estimated_value_low": 2500000,
    "estimated_value_high": 3200000,
    "wired_probability_score": 0.31,
    "agencies": {
      "name": "Department of Veterans Affairs"
    },
    "contracting_officers": {
      "name": "Jane M. Carter",
      "email": "jane.carter@va.gov"
    }
  }
}

Opportunities

P-Win Score

GET /v1/opportunities/:id/pwin

Returns a probability-of-win (P-Win) score for a specific opportunity, optionally personalized to your vendor's CAGE code. The score accounts for incumbent advantage, set-aside fit, historical win rates, and competition density.

Query Parameters

Name	Type	Req	Description
vendor_cage	string	opt	Your 5-character CAGE code. Omit for a generic competitive P-Win score.

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  "https://api.blackfyre.ai/v1/opportunities\
/9f2c1a3e-.../pwin?vendor_cage=4BK27"

Response

json
{
  "opportunity_id": "9f2c1a3e-...",
  "vendor_cage": "4BK27",
  "pwin_score": 0.42,
  "factors": {
    "incumbent_risk": "moderate",
    "set_aside_fit": true,
    "competition_density": "low",
    "past_performance_match": 0.78
  }
}

Opportunities

Semantic Search

POST /v1/opportunities/semantic-search

Vector-embedding search over opportunity text. Pass a natural-language description of your capabilities or a capability statement excerpt — the API finds opportunities semantically similar to your input, not just keyword matches.

Request Body (JSON)

Name	Type	Req	Description
text	string	req	Natural-language capability description or query. Max 8000 chars.
match_threshold	float	opt	Similarity cutoff 0.1–0.95. Default 0.75. Lower = more results.
limit	integer	opt	Max results. Default 10, max 50.
filters.naics	string	opt	Post-search NAICS filter applied to semantic results
filters.set_aside	string	opt	Post-search set-aside filter

curl

curl -X POST \
  -H "X-API-Key: bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "SDVOSB cybersecurity SOC operations
      incident response NIST SP 800-61",
    "match_threshold": 0.72,
    "limit": 15,
    "filters": { "set_aside": "sdvosb" }
  }' \
  https://api.blackfyre.ai/v1/opportunities\
/semantic-search

Response

json
{
  "data": [ /* opportunity objects */ ],
  "query": "SDVOSB cybersecurity SOC...",
  "match_threshold": 0.72,
  "count": 9
}

Awards

List Awards

GET /v1/awards

Returns contract awards from USASpending data. Filter by vendor, agency, NAICS code, and award type. Useful for incumbent research, competitive analysis, and market sizing.

Query Parameters

Name	Type	Req	Description
vendor_id	uuid	opt	Filter awards by vendor UUID
agency_id	uuid	opt	Filter by awarding agency UUID
naics	string	opt	6-digit NAICS code
award_type	string	opt	Contract type: `A` (BPA), `B` (Purchase Order), `D` (Delivery Order), `IDV_A`–`IDV_E`
limit	integer	opt	Default 25, max 100.
offset	integer	opt	Pagination offset. Default 0.

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  "https://api.blackfyre.ai/v1/awards\
?naics=541511&agency_id=UUID&limit=5"

Response

json
{
  "data": [
    {
      "piid": "VA7018D0057",
      "award_type": "D",
      "total_value": 2850000,
      "period_start": "2024-10-01",
      "period_end": "2026-09-30",
      "naics_code": "541511",
      "vendor_cage": "4BK27"
    }
  ],
  "limit": 5,
  "offset": 0
}

Awards

Get Award

GET /v1/awards/:piid

Returns a single contract award by PIID (Procurement Instrument Identifier) with full joined data including agency, vendor, contracting office, and contracting officer.

Path Parameters

Name	Type	Req	Description
piid	string	req	Contract PIID (e.g. `VA7018D0057`)

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  https://api.blackfyre.ai/v1/awards\
/VA7018D0057

Vendors

List Vendors

GET /v1/vendors

Returns vendors ranked by total award value. Useful for building a competitive landscape view of who wins the most in federal contracting.

Query Parameters

Name	Type	Req	Description
limit	integer	opt	Default 25, max 100.
offset	integer	opt	Pagination offset. Default 0.

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  https://api.blackfyre.ai/v1/vendors?limit=10

Response

json
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "cage_code": "4BK27",
      "uei": "XKYZ1234ABCD",
      "name": "Apex Cyber Solutions LLC",
      "business_types": ["SDVOSB", "SB"],
      "naics_primary": "541511",
      "total_awards_value": 48200000,
      "total_awards_count": 17
    }
  ],
  "meta": {
    "total": 12483,
    "limit": 10,
    "offset": 0
  }
}

Vendors

Search Vendors

GET /v1/vendors/search

Search and filter the vendor database by name, NAICS codes, set-aside certifications, and agency focus. Use this to find teaming partners, competitors, or incumbent research targets.

Query Parameters

Name	Type	Req	Description
name	string	opt	Partial company name search (case-insensitive)
naics	string	opt	NAICS code — returns vendors with this code in their portfolio
set_aside	string	opt	Business type filter: `SDVOSB`, `8(a)`, `WOSB`, `HUBZone`
limit	integer	opt	Default 25, max 100.

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  "https://api.blackfyre.ai/v1/vendors\
/search?naics=541511&set_aside=SDVOSB"

Vendors

Get Vendor

GET /v1/vendors/:cage

Returns a complete vendor profile by CAGE code, including all NAICS codes, certifications, award history totals, and teaming data. Related sub-endpoints provide award history, contract vehicle memberships, and competitor analysis.

Path Parameters

Name	Type	Req	Description
cage	string	req	5-character CAGE code

Related sub-endpoints:

GET /v1/vendors/:cage/awards

GET /v1/vendors/:cage/vehicles

GET /v1/vendors/:cage/competitors

GET /v1/vendors/:cage/expiring-contracts

GET /v1/vendors/:cage/teaming-style

GET /v1/vendors/:cage/new-markets

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  https://api.blackfyre.ai/v1/vendors/4BK27

Response

json
{
  "cage_code": "4BK27",
  "uei": "XKYZ1234ABCD",
  "name": "Apex Cyber Solutions LLC",
  "business_types": ["SDVOSB", "SB"],
  "naics_primary": "541511",
  "naics_all": ["541511", "541519", "541690"],
  "total_awards_value": 48200000,
  "total_awards_count": 17,
  "teaming_style": "sub_preferred",
  "pass_through_ratio": 0.22
}

Vendors

Full Contract History

GET /v1/vendors/full-contract-history

Combined FAR contract history (from USASpending.gov) plus OTA (Other Transaction Authority) awards from DoD public announcements — in a single call. OTAs are outside FAR and invisible in standard USASpending queries.

Query Parameters

Name	Type	Req	Description
company_name	string	opt*	Company legal name. Name variations are searched automatically.
uei	string	opt*	SAM.gov UEI. More precise than name-based lookup.
fiscal_years	string	opt	Comma-separated fiscal years (e.g. `2024,2025,2026`). Default is all three.

* At least one of company_name or uei is required.

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  "https://api.blackfyre.ai/v1/vendors\
/full-contract-history\
?company_name=Leidos&fiscal_years=2024,2025"

Response

json
{
  "company": "Leidos",
  "summary": {
    "total_obligated_all_sources": 4820000000,
    "far_contracts_obligated": 4200000000,
    "ota_contracts_obligated": 620000000,
    "far_contract_count": 412,
    "ota_contract_count": 18
  },
  "far_contracts": { "source": "USASpending.gov", "data": {...} },
  "ota_contracts": { "source": "DoD Public Announcements", "data": {...} }
}

Contracting Officers

Search Officers

GET /v1/people/search

Search contracting officer profiles by name and agency. Returns activity metrics including active action count, average days-to-award, small business award percentage, and wired signal indicators — built by a former CO who knows what signals matter.

Query Parameters

Name	Type	Req	Description
q	string	opt	Partial name search (e.g. `Carter`)
agency	string	opt	Partial agency name filter
limit	integer	opt	Default 20, max 100.
page	integer	opt	Page number. Default 1.

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  "https://api.blackfyre.ai/v1/people\
/search?agency=Veterans+Affairs&limit=5"

Response

json
{
  "data": [
    {
      "id": "c3d4e5f6-...",
      "name": "Jane M. Carter",
      "title": "Contracting Officer",
      "email": "jane.carter@va.gov",
      "agency_name": "Department of Veterans Affairs",
      "active_actions_count": 14,
      "avg_days_to_award": 62,
      "small_business_award_pct": 0.74,
      "sole_source_pct": 0.18,
      "wired_signal_count": 3
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total": 2841
  }
}

Contracting Officers

Get Officer

GET /v1/people/:id

Returns a full contracting officer profile by UUID, including all behavioral metrics available. Use this to understand who you're dealing with before submitting a proposal.

Path Parameters

Name	Type	Req	Description
id	uuid	req	Contracting officer UUID from search response

Sub-endpoints:

GET /v1/people/:id/awards

GET /v1/people/:id/patterns

GET /v1/people/:id/capacity

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  https://api.blackfyre.ai/v1/people\
/c3d4e5f6-4b5d-6e7f-8a9b-0c1d2e3f4a5b

Contracting Officers

Award Patterns

GET /v1/people/:id/patterns

Returns behavioral pattern analysis for a contracting officer — small business bias, sole-source propensity, FY-end surge behavior, protest history, and top vendor relationships. This is the intelligence a former CO knows to look for.

Path Parameters

Name	Type	Req	Description
id	uuid	req	Contracting officer UUID

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  https://api.blackfyre.ai/v1/people\
/c3d4e5f6-.../patterns

Response

json
{
  "data": {
    "co_name": "Jane M. Carter",
    "small_business_award_pct": 0.74,
    "sole_source_pct": 0.18,
    "protest_history_count": 2,
    "protest_sustained_count": 0,
    "avg_days_to_award": 62,
    "fy_end_surge_pattern": true,
    "wired_signal_count": 3,
    "top_vendor_relationships": [
      { "vendor_id": "...", "award_count": 8 }
    ],
    "interpretation": {
      "sb_bias": "Strong SB preference",
      "sole_source_risk": "Competitive award pattern",
      "fy_end_behavior": "Awards heavily in Aug/Sep"
    }
  }
}

Intelligence

Market Share

GET /v1/intelligence/market-share

Returns vendor market share rankings within a NAICS code and/or agency — showing who owns the space. Use this for price-to-win benchmarking and competitive landscape analysis.

Query Parameters

Name	Type	Req	Description
naics	string	opt	6-digit NAICS code to scope the market
agency_id	uuid	opt	Filter to a specific agency
fy	integer	opt	Federal fiscal year (e.g. `2025`)
limit	integer	opt	Top N vendors. Default 10.

curl

curl -H "X-API-Key: bk_live_YOUR_KEY" \
  "https://api.blackfyre.ai/v1/intelligence\
/market-share?naics=541511&fy=2025"

Response

json
{
  "data": {
    "total_market_value": 2840000000,
    "vendors": [
      {
        "vendor_cage": "3D3V6",
        "total_value": 420000000,
        "market_share_pct": 14.8
      }
    ]
  },
  "filters": {
    "naics": "541511",
    "fy": 2025
  }
}

Intelligence

Ask Hamilton

POST /v1/intel/ask

Send a natural-language question to Hamilton — Blackfyre's AI GovCon advisor built by a former Contracting Officer. Hamilton has access to live procurement data and will route your question to the appropriate intelligence service. Ask about opportunities, vendors, regulations, pricing, strategy, or anything else GovCon.

Request Body (JSON)

Name	Type	Req	Description
question	string	req	Your GovCon question. Natural language.
context	string	opt	Optional context — e.g. your capability statement, a solicitation excerpt, or your company profile snippet.
session_id	string	opt	Pass a consistent session ID to maintain conversation context across multiple turns.

curl

curl -X POST \
  -H "X-API-Key: bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Who is the incumbent on
      VA-25-IT-0042 and what is their
      typical pricing strategy?",
    "context": "We are an SDVOSB with
      NAICS 541511 past performance
      at VA and DHS."
  }' \
  https://api.blackfyre.ai/v1/intel/ask

Response

json
{
  "answer": "The incumbent is Apex Cyber Solutions
(CAGE 4BK27), an SDVOSB. Based on their
award history, they typically price at
blended rates 8–12% below GSA MAS
schedule for NAICS 541511. Their last
3 VA awards ranged from $2.1M–$3.4M.
I'd recommend positioning at $2.7M with
a strong past performance volume.",
  "sources": [
    {
      "type": "award",
      "piid": "VA7018D0057",
      "value": 2850000
    }
  ],
  "session_id": "sess_abc123"
}

REST API Reference

Authentication

Rate Limits

Error Codes

List Opportunities

Search Opportunities

Get Opportunity

P-Win Score

Semantic Search

List Awards

Get Award

List Vendors

Search Vendors

Get Vendor

Full Contract History

Search Officers

Get Officer

Award Patterns

Market Share

Ask Hamilton