Award announcements¶

Award announcements are short paragraphs saying that an award was made, served from two sources at /api/news/award_announcements/. For field definitions, see the Award announcements Data Dictionary.

Every row names its source, so you can always tell government text from text MakeGov wrote. The dataset is updated daily.

Authentication: this endpoint requires authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401.

Plans: every filter and every field is available on every plan, including Free.

Endpoints¶

• GET /api/news/award_announcements/ — list, with filtering, search, ordering and pagination
• GET /api/news/award_announcements/{uuid}/ — one announcement

The detail path segment must be a valid UUID; anything else is a 404.

Two sources¶

Each generated paragraph is written in the style of the official release, so read source rather than the wording. The figures, dates and names in a generated paragraph come from FPDS through a fixed template, and FPDS can be wrong or incomplete. Treat a generated announcement as a lead, and check the award itself before you rely on it: piids on the row works as the piid filter on IDVs, OTAs and OTIDVs.

One generated row can announce several awards when IDVs join a vehicle together, so the row carries lists of piids, award_uuids and awardees. For those rows, the $25 million test applies to the vehicle's ceiling rather than to each IDV. Orders and other child awards are not announced.

Source fields¶

source, source_name and source_url are in the default shape of every row, on both the list and the detail endpoint.

A generated announcement is dropped when an official release covers the award¶

When an official release covers the same award as a generated announcement, by award link or by contract number, the generated row is removed and only the official one remains. This can happen after the generated row was published, so a stored makegov_generated uuid can later return 404. A withdrawn release covers nothing, so a generated announcement of the same award stays.

Withdrawn announcements¶

The Department of War sometimes publishes a correction saying that an award was not released, not awarded or rescinded. That announcement is marked is_withdrawn: true.

• Lists and alerts hide it by default. Add include_withdrawn=true to include it.
• It stays retrievable by uuid at /api/news/award_announcements/{uuid}/, with or without that parameter.

Exclude withdrawn rows from anything you count or sum, which the default does for you.

Corrections¶

A correction is not its own row. The corrected values are applied to the announcement it corrects: amount, piids and is_withdrawn show the corrected values, text stays as published, and corrections records what changed. A correction that can't be matched to one original announcement is not served.

published_date versus award_date¶

The two dates answer different questions, and each source fills them differently.

FPDS reports awards after they are made, so a generated row's published_date is usually later than its award_date. published_date_* filters work across both sources; award_date_* filters return only generated rows.

Fields that differ by source¶

These fields come from the official release and are always null on a generated row:

• component
• contracting_activity
• corrections
• is_modification
• small_business on each awardee

is_withdrawn is also null on a generated row. obligated_at_award is not official-only: a generated row carries the FPDS figure when every award in the row has had a single action, and null otherwise.

In the other direction, announcement_type is set only on generated rows, and civilian is false on every official row. A generated row can be civilian: false too, because every new DoD OTA and OT IDV is announced.

Because they are null, a filter on these fields narrows the result to one source: component, small_business and is_modification return only official rows, and announcement_type returns only generated rows. For new awards across both sources, use action_type=new_award.

Filtering¶

Multi-value filters accept | (or the word OR) for OR. Date filters require YYYY-MM-DD; invalid dates or inverted ranges return 400 (see Date filters).

An unrecognized query parameter on the list endpoint returns 400 rather than being silently ignored, so a mistyped filter never returns a full, unfiltered page.

Amounts¶

amount is the announcement's headline dollar figure, and value_kind says what it measures. It is null when the announcement states none.

Amounts are not comparable across kinds: a ceiling is an upper bound, a combined_ceiling is shared by every awardee in a pool, and a modification_value is a change rather than a total. Sum or rank amount only within one value_kind. The kinds are listed in the data dictionary.

Ordering¶

ordering= allowlist:

• published_date — the default is -published_date (newest first)
• amount
• rank — relevance; requires a non-empty search, and is the implicit default under one

-amount and -published_date put rows without a value last. Results are tie-broken deterministically, so paging through a large result set never repeats or skips an announcement.

Pagination¶

Standard page-number pagination:

• page (default 1)
• limit (default 10, max 100)

Responses carry count / next / previous / results.

Shaping¶

See Response shaping for the syntax.

• List default: uuid, source, source_name, source_url, published_date, award_date, title, amount, value_kind, action_type, announcement_type, awardee_count, piids, is_modification, is_multiple_award, is_withdrawn, awardees(*)
• Detail default: the list fields plus source_record_id, text, obligated_at_award, award_kind, award_uuids, civilian, component, contracting_activity, corrections, organization(*)

Lists leave out text because a single paragraph can run past 16,000 characters. Name it in ?shape= to get it; every field is available on both the list and the detail endpoint.

Expansions¶

• awardees(...) — name, uei, location, small_business
• organization(...) — organization_id, office_code, office_name, agency_code, agency_name, department_code, department_name

Alerts¶

award_announcement is an alertable query type, delivered as alerts.award_announcement.match and using the same filters documented above. See the webhooks guide.

An alert fires when a matching announcement first appears and when one changes, so expect a second alert when a correction is applied or when an official announcement's award links fill in. Withdrawn announcements do not match unless the alert sets include_withdrawn to true. A generated row being dropped in favor of an official release does not fire on the generated row, though the official row can match on its own.

To receive only government text, include "source": "official_release" in the alert's filters.

Examples¶

# Official announcements of $100 million or more
GET /api/news/award_announcements/?source=official_release&amount_min=100000000

# Everything the Navy has announced since September
GET /api/news/award_announcements/?agency=Navy&published_date_after=2026-09-01

# New OTAs and OT IDVs written by MakeGov
GET /api/news/award_announcements/?source=makegov_generated&announcement_type=ota|ot_idv

# New awards from both sources
GET /api/news/award_announcements/?action_type=new_award

# Announcements naming one contract number
GET /api/news/award_announcements/?piid=N00019-25-C-0070

# Announcements naming an awardee
GET /api/news/award_announcements/?awardee=example%20systems

# A phrase, ranked by relevance
GET /api/news/award_announcements/?search=%22hypersonic%22

# Include withdrawn announcements
GET /api/news/award_announcements/?source=official_release&include_withdrawn=true

# A lean list payload with the text and awardee names
GET /api/news/award_announcements/?shape=uuid,source,published_date,title,text,awardees(name)

# Detail, with every default field
GET /api/news/award_announcements/{uuid}/

Notes:

• * is only valid inside expansions, such as awardees(*).
• Invalid shape fields return HTTP 400 with structured validation errors.