# GovCon API

Version: `1.0.0`

## Federal Contracts API for Developers

Clean JSON access to federal procurement data: contract opportunities,
FPDS prime contracts, SAM Award Notices, subawards, the SAM entity registry,
debarment exclusions, and contracting-officer contacts.

### What's covered
- **Contract opportunities** (SAM.gov notices, daily refresh)
- **Contracts** (FPDS prime contract transactions; every base award and modification for types A/B/C/D; FY2025+ coverage)
- **SAM Award Notices** (the SAM-noticed slice; backward-compatible surface for integrations that depend on it)
- **Subawards** (FFATA Section 2 reports, FY2025+)
- **SAM entity registry** (~873K registered firms by UEI or CAGE; registration
  status, expiration, NAICS, business-type certifications)
- **Exclusions** (debarred / suspended entities)
- **Companies** (Pro: combined SAM profile + award history)
- **Vendor Risk** (Pro: 7-signal screening per UEI)

Every response includes a top-level `_sources` array naming the data sources composed in that response.

### Authentication
All endpoints (except public demo) require Bearer token authentication:
```
Authorization: Bearer your_api_key_here
```

### Plans
- **Free Trial**: 25 req/day, 14 days, no credit card
- **Developer ($19/mo)**: 1000 req/hr, all opportunities + contracts + awards + exclusions
  filters + SAM entity lookup (UEI, CAGE, name search) + CSV exports
- **Pro ($39/mo)**: everything Developer + Companies API + multi-filter
  entity search + SAM expiration radar + Vendor Risk + Subawards + dense subaward enrichment on `/contracts/{piid}`

Use `/api/v1/stats` and `/api/v1/me` endpoints for current data and plan details.

### 📚 Documentation
- **This page**: Interactive API reference for developers
- **[Comprehensive Guide](/api-guide)**: Business documentation with worked examples and use cases

Single-file Markdown bundle generated from the live OpenAPI 3.1 schema. Source: <https://govconapi.com/openapi.json>.

## Endpoints

### `GET /api-guide`

**Api Guide**

Comprehensive API documentation with performance metrics and enterprise patterns

**Responses:**
- `200`: Successful Response

### `GET /api/agency-crosswalk`

**Get Agency Crosswalk**

Public endpoint - returns agency name standardization mappings (pre-built by weekly cron).

Each row is enriched with the matched `federal_hierarchy` entry (organization_id, cgac, type)
when the canonical_agency resolves to a SAM Federal Hierarchy org. ~99% match rate.
Use organization_id to call GET /api/v1/federal-hierarchy/{id} for structured data.

**Responses:**
- `200`: Successful Response

### `GET /api/v1/awards/search`

**Search Federal Contract Awards**

Tags: Awards

Search awarded contracts by awardee name, UEI, agency, NAICS, amount range, and date range. All filters available on all plans. Free plan: max 50 results. Paid plan: max 1000 results.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `awardee_name` | query |  | no | Awardee company name (partial match, case-insensitive) |
| `uei` | query |  | no | Exact UEI match |
| `naics` | query |  | no | NAICS code |
| `agency` | query |  | no | Awarding agency (partial match) |
| `amount_min` | query |  | no | Minimum award amount |
| `amount_max` | query |  | no | Maximum award amount |
| `awarded_after` | query |  | no | Awards on or after this date (YYYY-MM-DD) |
| `awarded_before` | query |  | no | Awards on or before this date (YYYY-MM-DD) |
| `state` | query |  | no | Awardee state code (2-letter, e.g. CA) |
| `sort_by` | query |  | no | Sort field: award_amount, award_date, awardee_name |
| `sort_order` | query |  | no | Sort order: asc or desc |
| `limit` | query | integer | no | Results per page |
| `offset` | query | integer | no | Pagination offset |
| `fields` | query |  | no | Comma-separated response fields to return. `notice_id` always included. Example: `fields=notice_id,awardee_name,award_amount,award_date`. |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/awards/{award_number}`

**Get Award by Contract Number**

Tags: Awards

Get a single award record by award/contract number. Returns the most recent record if multiple exist.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `award_number` | path | string | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `POST /api/v1/checkout`

**Create Checkout Session**

Create Stripe checkout session for Developer plan subscription

**Responses:**
- `200`: Successful Response

### `GET /api/v1/companies/search`

**Search awarded companies across SAM Award Notices + FPDS prime contracts (firms with 1+ federal award; for all registered firms use /entities/search)**

Tags: Companies (Pro)

Case-insensitive substring (ILIKE) match against awardee names across BOTH
SAM Award Notices and FPDS prime contract transactions.

Scope as of 2026-06-05: ~101,234 distinct UEIs across SAM Award Notice winners
+ FPDS prime contractors. Many federal contractors don't appear in the SAM
Award Notice slice (FPDS coverage is broader); the search now spans both so a
contractor like Picogrid ($18M+ FPDS, 0 SAM Award Notices) surfaces by name.

Existing fields keep their meaning — `total_awards` / `total_value` /
`last_award_date` describe SAM Award Notice activity only. New `fpds_*`
fields surface FPDS prime contract activity independently. Results are
ranked by the combined value (Award Notice + FPDS) so the biggest federal
contractor for the name surfaces first regardless of which source it lives in.

Optional `naics` and `agency` filters narrow the candidate set to companies
that have WON awards under that NAICS / from that agency (distinct from
Federal Contractor Search, which filters by SAM registration data —
"registered for NAICS X" vs "won awards under NAICS X").

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `q` | query | string | yes | Name substring match. UEIs are exact 12-char identifiers — for direct UEI lookup use GET /api/v1/companies/{uei}. |
| `naics` | query |  | no | 6-digit NAICS code. Filters to companies that have won at least one award under this NAICS. |
| `agency` | query |  | no | Agency top-level name (e.g. 'DEPT OF DEFENSE'). Filters to companies that have won at least one award from this agency. Matches the top-level of SAM's dotted agency path. |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `fields` | query |  | no | Comma-separated response fields. `uei` always included. Example: `fields=uei,name,total_value,fpds_obligated_total`. |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/companies/{uei}`

**Company profile with aggregated stats**

Tags: Companies (Pro)

Aggregate profile for a single UEI.

Combines two sources:
  - **SAM entity registration** (legal name, DBA, address, NAICS, PSC,
    business-type certifications, registration dates, CAGE codes)
  - **Award history** (totals, top NAICS/agencies, activity windows)

Returns 200 if either source has the UEI. Returns 404 only when the UEI
is unknown to both. Award fields default to 0/empty when the company is
SAM-registered but has never won a contract (the common case for SMBs
in the SAM directory of ~880K registered entities).

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uei` | path | string | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/companies/{uei}/awards`

**Award history for a UEI (paginated)**

Tags: Companies (Pro)

Full paginated award history. sort=date (default, desc) | amount (desc).
Also accepts sort_by=award_date|award_amount + sort_order=asc|desc.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uei` | path | string | yes |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `sort` | query | string | no |  |
| `sort_by` | query |  | no | Sort field: award_date or award_amount (alias for sort) |
| `sort_order` | query |  | no | Sort order: asc or desc (used with sort_by) |
| `fields` | query |  | no | Comma-separated response fields. `notice_id` always included. |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/companies/{uei}/peers`

**Similar companies by NAICS + agency overlap**

Tags: Companies (Pro)

Find similar awardees based on overlap of NAICS codes and agencies.

Scoring: count NAICS overlap + count agency overlap (each weighted by
their award frequency at the target UEI). Not a true Jaccard; closer
to 'weighted match count'.

This is the slowest endpoint. Expect 200-1500ms on prod data.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uei` | path | string | yes |  |
| `limit` | query | integer | no |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/companies/{uei}/prime-relationships`

**Primes that have paid this UEI as a sub-vendor. Reverse lookup by subawardee_uei.**

Tags: Subawards

What primes have paid this sub? Indexed on subawardee_uei.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uei` | path | string | yes |  |
| `sort_by` | query |  | no |  |
| `sort_order` | query |  | no |  |
| `date_from` | query |  | no |  |
| `date_to` | query |  | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `fields` | query |  | no |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/companies/{uei}/subawards`

**Subawards paid by this prime (UEI). Reverse lookup over /subawards/search.**

Tags: Subawards

What subs has this prime paid? Indexed on prime_awardee_uei.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uei` | path | string | yes |  |
| `sort_by` | query |  | no |  |
| `sort_order` | query |  | no |  |
| `date_from` | query |  | no |  |
| `date_to` | query |  | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `fields` | query |  | no |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/contacts/lookup`

**Look Up Contracting Officer Contact Info**

Tags: Contacts (Pro)

Resolver lookup for a contracting officer.

Two query modes:
- **By name** (`name=X`, optional `agency=Y` and `state=ST`). Returns up to 5 substring matches.
- **By email** (`email=foo@bar.gov`). Exact match, single record. Useful for CRM-enrichment workflows where the email is on file and the customer wants the current name / agency / phone for that address.

One of `name` or `email` is required.

**This is a resolver, not a directory.** It is not possible to list or paginate contacts via this endpoint. To browse the full directory, search by NAICS or agency, view award history, or see colleague graphs and AI dossiers, use the web app at https://contacts.govconapi.com (included with Pro).

**Auth:** Pro tier ($39/mo). Returns 402 on Developer-only keys.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `name` | query |  | no | Name (or partial name) of the contracting officer. Required unless `email` is provided. |
| `agency` | query |  | no | Optional agency substring for disambiguation (e.g. 'Air Force', 'DLA'). Used only with `name`. |
| `state` | query |  | no | Optional 2-letter state/territory code (e.g. 'CA', 'DC'). Used only with `name`. |
| `email` | query |  | no | Exact email address for reverse lookup. Returns one record. Mutually exclusive with `name` (if both, `email` wins). |

**Responses:**
- `200`: Up to 5 contacts matching the query.
- `402`: Caller's plan does not include contacts_access. Upgrade to Pro.
- `404`: No matching contacts.
- `422`: Required parameter missing or invalid.
- `429`: Rate limit exceeded.
- `503`: Contacts data store temporarily unavailable. Retry.

### `GET /api/v1/contracts/search`

**Search FPDS prime contract transactions by UEI, PIID, agency, NAICS**

Tags: Contracts

Per conventions §1.1, §3.5, §4.2, §5, §6.1, §9.3 and ARCHITECTURE.md §4.1.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uei` | query |  | no | Recipient UEI (exact) |
| `parent_uei` | query |  | no | Recipient parent UEI (corporate roll-up) |
| `piid` | query |  | no | Award PIID (exact) |
| `parent_piid` | query |  | no | Parent award PIID (vehicle/IDV) |
| `agency` | query |  | no | Awarding agency name substring (case-insensitive) |
| `naics` | query |  | no | NAICS, exactly 6 digits |
| `award_type_code` | query |  | no | FPDS award type: A, B, C, or D |
| `date_from` | query |  | no | YYYY-MM-DD (action_date) |
| `date_to` | query |  | no | YYYY-MM-DD (action_date) |
| `amount_min` | query |  | no | federal_action_obligation min |
| `amount_max` | query |  | no | federal_action_obligation max |
| `sort_by` | query |  | no |  |
| `sort_order` | query |  | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `fields` | query |  | no | lean \| expanded \| full \| comma-list of columns |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/contracts/{piid}`

**Single contract by PIID — latest action + roll-up + optional subaward enrichment**

Tags: Contracts

Returns the LATEST transaction row for this PIID plus a roll-up of
obligation/value totals across every transaction (mods included).

Detail-style response per ARCHITECTURE.md §4.2 — singular `contract` key
at top level; `subaward_rollup` enrichment as a sibling, NOT nested.
Pro-gated subaward enrichment via contacts_access per §8.4 (Free tier
sees the contract record but no subaward block).

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `piid` | path | string | yes |  |
| `fields` | query |  | no | lean \| expanded \| full \| comma-list of columns |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/contracts/{piid}/modifications`

**Full transaction history for a PIID — every modification row, oldest to newest**

Tags: Contracts

Returns every transaction row for the given PIID, oldest action first.

Modification trail use case: amendments, options exercised, partial
terminations. Each row is a single FPDS action; mods stack on the
original award. NOT windowed by date — when the customer asks for one
PIID's full history, they get the full history (per conventions §4.4).

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `piid` | path | string | yes |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `fields` | query |  | no | lean \| expanded \| full \| comma-list of columns |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/entities/by-cage/{cage_code}`

**SAM entity lookup by CAGE code (Developer tier)**

Tags: Entities

SAM-registered entity by Commercial and Government Entity (CAGE) code.

CAGE is the DoD/DLA-issued 5-character identifier used by contracting
officers and legacy procurement systems. Each CAGE code is assigned to
one entity by DLA. Large entities (USPS, financial institutions) can
have multiple CAGE codes per UEI; this endpoint returns the entity
that owns the CAGE you queried.

Response is the same shape as `/entities/{uei}` plus a `queried_cage`
field echoing the input. Developer tier (matches `/entities/{uei}` —
both are alternate-identifier lookups for the same underlying record).

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `cage_code` | path | string | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/entities/expiring`

**Registrations expiring within N days (Pro)**

Tags: Entities

Active SAM registrations expiring within `within_days` days.

Pro. Renewal-radar use case: customers monitor a state, a NAICS
cohort, or the full population for entities that need to renew. Past-due
expirations are excluded (status would already be 'E').

Sorted by expiration_date ascending (most urgent first). Result includes
`days_until_expiration` for direct rendering.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `within_days` | query | integer | no | Days from today to look ahead |
| `state` | query |  | no |  |
| `naics` | query |  | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/entities/search`

**Search SAM entities (q = Developer; filters = Pro)**

Tags: Entities

Filter-based entity search.

**Developer tier**: pass `q` only (name substring, trigram-indexed).

**Pro**: combine `q` with `naics` / `state` / `business_type` /
`active_only` filters. The DSBS replacement.

At least one of `q` / `naics` / `state` / `business_type` / `active_only`
must be provided. NAICS values omit the Y/N small-business suffix (we
match either flag).

`business_type` accepts SAM 2-3 char codes like `8W` (WOSB), `QF`
(SDVOSB), `27` (Self-Cert SDB), `2X` (For Profit), etc. Full list in
`entities/business_types.py`. Note: SBA-certified codes (A6, XX, JT, A4)
are valid but appear ~zero times in the Public V2 SAM extract.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `q` | query |  | no | Name substring (Developer tier) |
| `naics` | query |  | no | NAICS code, no Y/N suffix (Pro) |
| `state` | query |  | no | 2-letter US state (Pro) |
| `business_type` | query |  | no | SAM business-type code (Pro). See entities/business_types.py. |
| `active_only` | query | boolean | no | Only Active registrations (Pro) |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `fields` | query |  | no | Comma-separated response fields. `uei` always included. Example: `fields=uei,legal_business_name,primary_naics`. |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/entities/{uei}`

**SAM entity lookup by UEI (Developer tier)**

Tags: Entities

Single SAM-registered entity by UEI.

Returns registration block (status, dates, expiring_soon flag) and entity
block (legal name, DBA, address, NAICS/PSC, business-type certifications,
decoded labels, CAGE codes).

Available on Developer tier (any active API key). For award-history merge
on top of this data, Pro subscribers should use `/companies/{uei}`.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uei` | path | string | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/exclusions/search`

**Search Excluded Entities**

Tags: Exclusions

Search SAM.gov exclusions database for debarred entities. Search by name, UEI, CAGE code, agency, or location.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `entity_name` | query |  | no | Entity or person name (partial match) |
| `name` | query |  | no | Alias for entity_name (accepted for backwards compatibility) |
| `uei_sam` | query |  | no | UEI SAM identifier |
| `cage_code` | query |  | no | CAGE code |
| `excluding_agency` | query |  | no | Excluding agency code (e.g., DOJ, DOD) |
| `classification_type` | query |  | no | Classification: Individual, Firm, Vessel, Special Entity Designation |
| `exclusion_type` | query |  | no | Type: Ineligible (Proceedings Pending), Ineligible (Proceedings Completed), etc. |
| `state` | query |  | no | State/province code |
| `country` | query |  | no | Country code |
| `active_only` | query | boolean | no | Only show currently active exclusions |
| `limit` | query | integer | no | Results per page |
| `offset` | query | integer | no | Pagination offset |
| `fields` | query |  | no | Comma-separated response fields to return. `uei_sam` always included. Example: `fields=entity_name,uei_sam,excluding_agency_code,activate_date`. Omit to return all fields (default). |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/exclusions/{uei_sam}`

**Check UEI Against Exclusions List**

Tags: Exclusions

Vendor-risk screening lookup: pass a UEI SAM and find out whether that entity has an active or historical exclusion record.

**Response semantics**
- `200` — entity IS on the exclusions list. Body contains the full record.
- `404` — UEI is **not** on the exclusions list. This is the expected answer for the vast majority of legitimate vendors and means the entity is clean.

**Coverage caveat:** roughly 73% of SAM exclusions are individuals or small entities without a UEI. A 404 here means *no UEI-keyed exclusion*; to also screen against name-based debarments (e.g. principals, officers, individuals), pair this lookup with `/api/v1/exclusions/search?entity_name=...`.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uei_sam` | path | string | yes |  |

**Responses:**
- `200`: Entity is on the exclusions list. Full record returned.
- `404`: No UEI-keyed exclusion found. Entity is clean by UEI; screen names separately for full coverage.
- `422`: Validation Error
- `429`: Rate limit exceeded.

### `GET /api/v1/federal-hierarchy/`

**List Federal Organizations**

Tags: Federal Hierarchy

Search and filter the SAM Federal Hierarchy (~907 federal departments, agencies, and offices). All filters are optional. Free tier — available to any authenticated API key.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `type` | query |  | no | Filter by type: DEPARTMENT or AGENCY (case-insensitive) |
| `cgac` | query |  | no | Filter by Treasury account code (e.g. 097 for DoD) |
| `parent_id` | query |  | no | Filter by parent organization_id |
| `hierarchy_level` | query |  | no | Filter by depth (1 = root department) |
| `is_active` | query |  | no | Filter by active status (default: true) |
| `search` | query |  | no | Match on canonical_name, short_name, or alternative_names (case-insensitive) |
| `limit` | query | integer | no | Results per page (default 50, max 1000) |
| `offset` | query | integer | no | Pagination offset |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/federal-hierarchy/{organization_id}`

**Federal Organization Detail**

Tags: Federal Hierarchy

Lookup a single federal organization by `organization_id`. Response includes the full record plus inline `parent`, `children`, and `ancestors` for traversal in one call.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `organization_id` | path | integer | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/federal-hierarchy/{organization_id}/ancestors`

**Ancestor Chain**

Tags: Federal Hierarchy

Return the chain of ancestors (root → immediate parent) for `organization_id`. Empty array if the organization is a root department.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `organization_id` | path | integer | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/federal-hierarchy/{organization_id}/children`

**Immediate Children**

Tags: Federal Hierarchy

Return immediate child organizations of `organization_id`.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `organization_id` | path | integer | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/identifiers/{identifier}`

**Resolve DUNS ↔ UEI**

Tags: Identifiers

Free reverse lookup between legacy DUNS (9 digits, or 13-digit DUNS+4) and current UEI (12 alphanumeric). Accepts either side; returns both plus the entity name and FFATA evidence count.

**Coverage truth.** The crosswalk is built from FFATA Section 2 subaward filings since FY2025, where both identifiers co-exist on the same record. A 404 here means *not in the FFATA-derived crosswalk* (about 24K firms indexed), not *not in SAM*. The official SAM DUNS↔UEI translator is admin-gated and not publicly available.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `identifier` | path | string | yes |  |

**Responses:**
- `200`: Pair found. Returns DUNS, UEI, entity name, evidence count, last seen.
- `404`: Identifier not in the FFATA-derived crosswalk.
- `422`: Identifier shape invalid (not 9-digit DUNS, not 12-char UEI).
- `429`: Rate limit exceeded.

### `POST /api/v1/keys`

**Create API Key**

Tags: Management

Create or regenerate API key. New users get free trial, existing users keep current plan.

**Responses:**
- `200`: Successful Response

### `GET /api/v1/me`

**Current User Info**

Tags: Management

Get current user's plan and account information

**Responses:**
- `200`: Successful Response

### `GET /api/v1/opportunities/delta`

**Delta Sync**

Tags: Delta Sync

Get all opportunities added or modified since a given timestamp. Use this to keep your local database in sync without re-pulling everything.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `since` | query | string | yes | ISO 8601 timestamp (e.g. 2026-04-05T06:00:00Z). Returns records where last_seen >= this value. |
| `limit` | query | integer | no | Results per page |
| `offset` | query | integer | no | Pagination offset |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/opportunities/search`

**Search Contract Opportunities**

Tags: Search

Search federal contract opportunities. All filters available on every plan. Developer plan adds CSV export, larger page size (1,000 vs 50), and 1,000/hour rate limit.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `naics` | query |  | no |  |
| `psc` | query |  | no |  |
| `agency` | query |  | no |  |
| `state` | query |  | no |  |
| `posted_after` | query |  | no |  |
| `due_before` | query |  | no |  |
| `due_after` | query |  | no |  |
| `keywords` | query |  | no | Full-text search across title, agency name, and contract description. Also matches solicitation number. |
| `set_aside` | query |  | no |  |
| `notice_type` | query |  | no |  |
| `solicitation_number` | query |  | no | Exact solicitation number (e.g., USCA25Q0053) |
| `value_min` | query |  | no |  |
| `value_max` | query |  | no |  |
| `location` | query |  | no |  |
| `date_from` | query |  | no |  |
| `date_to` | query |  | no |  |
| `sort_by` | query |  | no |  |
| `sort_order` | query |  | no |  |
| `naics_multiple` | query |  | no |  |
| `has_attachments` | query |  | no |  |
| `active_only` | query | boolean | no | Convenience filter, computed by us from `archive_date_detailed`. When true, returns only notices whose archive date is in the future (i.e. currently open). This is NOT a SAM source field — the stored `active` column is always 'Yes' by design (we never archive). Equivalent to filtering `archive_date_detailed > CURRENT_DATE` yourself. |
| `limit` | query | integer | no | Results per page (1-1000, plan-capped further). Use Query so 0/negative reject at validator instead of returning empty data. |
| `offset` | query | integer | no | Pagination offset |
| `format` | query | string | no |  |
| `fields` | query |  | no | Comma-separated list of response fields to return. Reduces payload size when you only need a few columns. Example: `fields=notice_id,title,naics,posted_date`. `notice_id` is always included. Omit to return all 59 fields per record (default). |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/opportunities/{notice_id}`

**Get Single Opportunity**

Tags: Search

Retrieve detailed information for a specific contract opportunity

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `notice_id` | path | string | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/opportunities/{notice_id}/attachments`

**Get Opportunity Attachments**

Tags: Search

Retrieve attachment URLs for a specific contract opportunity. Returns direct SAM.gov download links.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `notice_id` | path | string | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/stats`

**Database Statistics**

Tags: Public

Get current database statistics and data freshness information

**Responses:**
- `200`: Successful Response

### `GET /api/v1/subawards/search`

**Search FFATA subawards by prime/sub UEI, contract PIID, agency, NAICS, or keywords**

Tags: Subawards

Filter-based subaward search with the standard envelope + window block.

Per conventions §1.1, §3.5, §4.2, §5, §6.1, §9.3.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `prime_uei` | query |  | no |  |
| `sub_uei` | query |  | no |  |
| `piid` | query |  | no |  |
| `agency` | query |  | no | Awarding agency name substring (case-insensitive) |
| `naics` | query |  | no | Exactly 6 digits |
| `sub_name` | query |  | no | Sub-vendor name substring (case-insensitive) |
| `date_from` | query |  | no | YYYY-MM-DD |
| `date_to` | query |  | no | YYYY-MM-DD |
| `amount_min` | query |  | no |  |
| `amount_max` | query |  | no |  |
| `sort_by` | query |  | no |  |
| `sort_order` | query |  | no |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `fields` | query |  | no |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/subawards/{subaward_sam_report_id}`

**Single FFATA report by SAM report ID (UUID)**

Tags: Subawards

Single-record lookup. Returns flat object per §1.2. NOT windowed (§4.4).

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `subaward_sam_report_id` | path | string | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `POST /api/v1/vendor-risk/bulk`

**Bulk vendor risk screening (up to 100 UEIs)**

Tags: Vendor Risk (Pro)

Return risk reports for each supplied UEI. Not-found UEIs come back
with status='not_found' rather than failing the whole request — stale
UEIs in vendor lists are normal.

**Request body:**
- Content type: `application/json`

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /api/v1/vendor-risk/{uei}`

**Vendor risk report for a UEI**

Tags: Vendor Risk (Pro)

Return all seven risk signals for a single UEI.

Always returns 200 with the full signal shape, even for clean vendors.
Never returns a risk score; callers interpret the signals themselves.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uei` | path | string | yes |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /demo/opportunities`

**Demo Opportunities**

Public demo endpoint - returns latest 2 opportunities (cached for 6 hours)

**Responses:**
- `200`: Successful Response

### `GET /export.csv`

**Export Csv**

Export opportunities as CSV. Max 1000 records. Subset of /opportunities/search filters.

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `keywords` | query |  | no |  |
| `naics` | query |  | no |  |
| `naics_multiple` | query |  | no |  |
| `agency` | query |  | no |  |
| `state` | query |  | no |  |
| `set_aside` | query |  | no |  |
| `notice_type` | query |  | no |  |
| `solicitation_number` | query |  | no |  |
| `limit` | query | integer | no |  |

**Responses:**
- `200`: Successful Response
- `422`: Validation Error

### `GET /favicon.ico`

**Favicon Ico**

Serve favicon.ico (redirect to SVG)

**Responses:**
- `200`: Successful Response

### `GET /health`

**Health**

Health check endpoint.

**Responses:**
- `200`: Successful Response

### `GET /robots.txt`

**Robots**

Generate robots.txt for search engine crawlers

**Responses:**
- `200`: Successful Response

### `GET /sitemap.xml`

**Sitemap**

Generate XML sitemap for search engines including daily snapshots

**Responses:**
- `200`: Successful Response