Mast - API Documentation

Licensed API access

Reliable flag status data for your app.

Mast API access requires a license key for API requests. A license keeps requests authorized and helps fund ongoing source monitoring, maintenance, and data quality work.

Required License key required

Send your key in the x-mast-license-key header.

Coming soon Developer account

Cache-aware responses

Developer note

Mast refreshes official sources on the server about every 30 minutes. API responses come from the latest Mast cache, so your app can read stable JSON quickly without polling state or federal source pages directly.

Use the cache.refreshedAt, cache.refreshIntervalMs, and cache.isStale fields when they appear to show data age or decide when to refresh your own UI.

Current Status

GET

/api/v1/status?countryCode=US

curl -H "x-mast-license-key: YOUR_LICENSE_KEY" \
  https://www.mast.today/api/v1/status?countryCode=US

const response = await fetch(
  "https://www.mast.today/api/v1/status?countryCode=US",
  {
    headers: {
      "x-mast-license-key": "YOUR_LICENSE_KEY"
    }
  }
);
const data = await response.json();

Returns the current half-mast status for a country plus the same calendar events used by the app. For the United States, Mast includes recurring federal observances from official federal sources.

countryCode: Optional ISO country code. Defaults to US.
stateCode: Optional U.S. state abbreviation, such as AZ.

{
  "ok": true,
  "status": {
    "countryCode": "US",
    "countryName": "US",
    "isHalfMast": false,
    "scope": "unknown",
    "title": "No active order",
    "authority": "Unknown",
    "source": "",
    "reason": "No active half-mast order has been recorded for this country."
  },
  "calendar": {
    "countryCode": "US",
    "events": [
      {
        "title": "Memorial Day",
        "scope": "federal",
        "authority": "4 U.S.C. 6(d) and 4 U.S.C. 7(m)",
        "source": "https://uscode.house.gov/...",
        "effectiveFrom": "2026-05-25T00:00:00.000Z",
        "effectiveUntil": "2026-05-25T23:59:59.000Z",
        "timeRule": "half-staff until noon local time, then full-staff",
        "type": "recurring-federal-observance"
      }
    ]
  },
  "cache": {
    "refreshedAt": "2026-04-30T20:00:00.000Z",
    "refreshIntervalMs": 1800000
  }
}

Calendar

GET

/api/v1/calendar?countryCode=US

curl -H "x-mast-license-key: YOUR_LICENSE_KEY" \
  https://www.mast.today/api/v1/calendar?countryCode=US

const response = await fetch(
  "https://www.mast.today/api/v1/calendar?countryCode=US",
  {
    headers: {
      "x-mast-license-key": "YOUR_LICENSE_KEY"
    }
  }
);
const data = await response.json();

Returns known half-mast date ranges for a country. The app uses this endpoint to highlight calendar days and display source details.

countryCode: Optional ISO country code. Defaults to US.
stateCode: Optional U.S. state abbreviation, such as AZ.

{
  "ok": true,
  "calendar": {
    "countryCode": "US",
    "events": [
      {
        "countryCode": "US",
        "countryName": "United States",
        "title": "Peace Officers Memorial Day",
        "scope": "federal",
        "authority": "4 U.S.C. 7(m) and 36 U.S.C. 136",
        "source": "https://uscode.house.gov/...",
        "effectiveFrom": "2026-05-15T00:00:00.000Z",
        "effectiveUntil": "2026-05-15T23:59:59.000Z",
        "reason": "Federal law provides for half-staff display on Peace Officers Memorial Day unless it falls on Armed Forces Day.",
        "timeRule": "half-staff sunrise to sunset local time",
        "type": "recurring-federal-observance"
      }
    ]
  },
  "cache": {
    "refreshedAt": "2026-04-30T20:00:00.000Z",
    "refreshIntervalMs": 1800000
  }
}

State Sources

GET

/api/v1/state/sources?countryCode=US&stateCode=AZ

curl -H "x-mast-license-key: YOUR_LICENSE_KEY" \
  https://www.mast.today/api/v1/state/sources?countryCode=US&stateCode=AZ

const response = await fetch(
  "https://www.mast.today/api/v1/state/sources?countryCode=US&stateCode=AZ",
  {
    headers: {
      "x-mast-license-key": "YOUR_LICENSE_KEY"
    }
  }
);
const data = await response.json();

Returns registered state-level source metadata for official state flag status pages and notice archives.

{
  "ok": true,
  "countryCode": "US",
  "stateCode": "AZ",
  "sources": [
    {
      "stateName": "Arizona",
      "authority": "Arizona Governor / az.gov",
      "sourceType": "official-state-notice-page",
      "statusUrl": "https://az.gov/half-staff-notices",
      "supportsCurrentStatus": true,
      "supportsHistoricalNotices": true
    }
  ]
}

Pipeline Status

GET

/api/v1/pipeline/status

curl -H "x-mast-license-key: YOUR_LICENSE_KEY" \
  https://www.mast.today/api/v1/pipeline/status

const response = await fetch(
  "https://www.mast.today/api/v1/pipeline/status",
  {
    headers: {
      "x-mast-license-key": "YOUR_LICENSE_KEY"
    }
  }
);
const data = await response.json();

Returns federal and U.S. state pipelines with source metadata, pull health, fetch errors, cache freshness, and active or upcoming retained events.

{
  "ok": true,
  "summary": {
    "total": 52,
    "fresh": 52,
    "stale": 0,
    "degraded": 0,
    "disabled": 0
  },
  "pipelines": [
    {
      "pipelineType": "federal",
      "label": "United States Federal",
      "code": "US",
      "pullStatus": "fresh"
    },
    {
      "pipelineType": "state",
      "label": "Connecticut",
      "code": "CT",
      "pullStatus": "fresh",
      "source": {
        "authority": "Connecticut Governor / portal.ct.gov",
        "supportsCurrentStatus": true,
        "supportsHistoricalNotices": true
      },
      "eventCount": 1
    }
  ]
}

The same data powers the pipeline status page.

Federal Feed

GET

/api/v1/federal/feed?year=2026

curl -H "x-mast-license-key: YOUR_LICENSE_KEY" \
  https://www.mast.today/api/v1/federal/feed?year=2026

const response = await fetch(
  "https://www.mast.today/api/v1/federal/feed?year=2026",
  {
    headers: {
      "x-mast-license-key": "YOUR_LICENSE_KEY"
    }
  }
);
const data = await response.json();

Returns U.S. federal feed source metadata and recurring federal half-staff observances for a given year.

year: Optional four-digit year. Defaults to the current UTC year.
liveCandidates: Included from the server cache when live federal feed polling is enabled.

{
  "ok": true,
  "countryCode": "US",
  "scope": "federal",
  "sources": [
    {
      "id": "white-house-proclamations",
      "name": "White House Presidential Proclamations",
      "url": "https://www.whitehouse.gov/presidential-actions/proclamations/"
    }
  ],
  "recurringEvents": [
    {
      "id": "memorial-day-2026",
      "title": "Memorial Day",
      "effectiveFrom": "2026-05-25T00:00:00.000Z",
      "timeRule": "half-staff until noon local time, then full-staff"
    }
  ],
  "liveCandidates": null
}

U.S. Status

GET

/api/v1/status/us

curl -H "x-mast-license-key: YOUR_LICENSE_KEY" \
  https://www.mast.today/api/v1/status/us

const response = await fetch(
  "https://www.mast.today/api/v1/status/us",
  {
    headers: {
      "x-mast-license-key": "YOUR_LICENSE_KEY"
    }
  }
);
const data = await response.json();

Convenience endpoint for the current U.S. status. It returns the same status object as /api/v1/status?countryCode=US, without the calendar wrapper.

Report inaccuracies

POST

Use this endpoint when a user needs to send Mast a correction for inaccurate flag-status information.

POST /api/v1/report/inaccuracy: Sends a sanitized inaccurate-information report to the Mast operator inbox.