Mast API

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-staff 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-staff 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": 14400000
  }
}

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-staff 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 the U.S. flag to be displayed at half-staff from sunrise to sunset on Peace Officers Memorial Day, unless it falls on Armed Forces Day. The observance honors law enforcement officers who lost their lives in the line of duty and recognizes the service and sacrifice of peace officers across the country.",
        "timeRule": "half-staff sunrise to sunset local time",
        "type": "recurring-federal-observance"
      }
    ]
  },
  "cache": {
    "refreshedAt": "2026-04-30T20:00:00.000Z",
    "refreshIntervalMs": 14400000
  }
}

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
    }
  ]
}

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.

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
}

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.

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.