MastDevelopers

Mast API v1

Half-staff flag data,
ready to build with.

Find current flag status, upcoming order dates, official sources, and pipeline health through a small set of predictable JSON endpoints.

Start building Browse endpoints
--Fresh
--Stale
--Degraded
--Disabled
ViewPipeline health

Loading pipeline health metrics...

Start here

Getting started

Make your first request in a few minutes.
2
Keep your key private

Send it in the x-mast-license-key header. Avoid putting it in URLs or public client code.

3
Request a status

Start with the Current Status endpoint and add a two-letter state code when needed.

Base URL

All v1 endpoints begin with https://www.mast.today/api/v1.

Your first request

Successful responses include ok: true. Status and calendar responses also include cache metadata so your UI can communicate freshness.

Core concept

Authentication

Every v1 request requires a developer API key.

Send the license header

Include your key in the x-mast-license-key request header. Mast connects usage to your developer account and resets plan usage on the first day of each month.

x-mast-license-key: YOUR_LICENSE_KEY
Do not expose your key

For public websites and mobile apps, proxy Mast requests through your own server or serverless function.

Common responses

200 Success
The request was accepted.
401 Unauthorized
The key is missing or invalid.
429 Rate limited
The account has exceeded its current allowance.

Build with Mast

Use cases

Choose the endpoint that matches what your product needs to answer.
Status badgesShow whether flags are at full-staff or half-staff right now.Current status CalendarsHighlight upcoming federal and state half-staff dates.Calendar NewsroomsDisplay the authority and official source behind an order.State sources OperationsMonitor source freshness and degraded ingestion pipelines.Pipeline health

Need a fuller walkthrough? Explore implementation ideas and open-source examples.

Help

Frequently asked questions

Short answers to the questions developers ask first.
Which endpoint should I start with?

Use Current Status. It returns the current answer and the calendar context used by Mast.

How often does the data update?

Mast refreshes official sources on a configured interval, usually about every four hours. Read cache.refreshedAt and cache.isStale instead of assuming freshness.

Can I call the API directly from a browser?

The API supports cross-origin requests, but a browser request exposes your key. A server-side proxy is the safer production design.

What does an empty status mean?

An inactive response means Mast has no active order for that location at that time. Check the cache fields and source endpoints when provenance matters.

How do I report incorrect data?

Use the Report Inaccuracy endpoint or the correction controls on Mast’s public status pages.

Endpoint reference

API endpoints

Requests and responses use JSON unless noted otherwise.

Endpoint

GET

Current status

Current status plus calendar context for a country or U.S. state.
/api/v1/status?countryCode=US&stateCode=AZ
Code language

Query parameters

countryCode string
Optional ISO country code. Defaults to US.
stateCode string
Optional two-letter U.S. state or territory code.

Example response

{
  "ok": true,
  "status": {
    "countryCode": "US",
    "stateCode": "AZ",
    "isHalfMast": false,
    "title": "No active order",
    "authority": "Unknown"
  },
  "calendar": { "events": [] },
  "cache": {
    "refreshedAt": "2026-07-22T12:00:00.000Z",
    "refreshIntervalMs": 14400000,
    "isStale": false
  }
}

Endpoint

GET

U.S. status

A compact convenience endpoint for the current national status.
/api/v1/status/us

Returns the same national status object used by Current Status without the calendar wrapper.

Endpoint

GET

Calendar

Known half-staff date ranges for a country or U.S. state.
/api/v1/calendar?countryCode=US&stateCode=AZ

Query parameters

countryCode string
Optional ISO country code. Defaults to US.
stateCode string
Optional two-letter state or territory code.

Example response

{
  "ok": true,
  "calendar": {
    "countryCode": "US",
    "events": [{
      "title": "Peace Officers Memorial Day",
      "scope": "federal",
      "effectiveFrom": "2026-05-15T00:00:00.000Z",
      "timeRule": "half-staff sunrise to sunset local time"
    }]
  },
  "cache": { "isStale": false }
}

Endpoint

GET

State sources

Official source metadata and capability details for a state pipeline.
/api/v1/state/sources?countryCode=US&stateCode=AZ

Example response

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

Endpoint

GET

Federal feed

Federal sources and recurring observances for a selected year.
/api/v1/federal/feed?year=2026

Query parameters

year number
Optional four-digit year. Defaults to the current UTC year.

Example response

{
  "ok": true,
  "countryCode": "US",
  "scope": "federal",
  "recurringEvents": [{
    "id": "memorial-day-2026",
    "title": "Memorial Day",
    "timeRule": "half-staff until noon local time, then full-staff"
  }]
}

Endpoint

GET

Pipeline health

Freshness, source metadata, errors, and retained-event counts.
/api/v1/pipeline/status

Example response

{
  "ok": true,
  "summary": {
    "total": 53,
    "fresh": 53,
    "stale": 0,
    "degraded": 0,
    "disabled": 0
  },
  "pipelines": [{
    "pipelineType": "federal",
    "label": "United States Federal",
    "pullStatus": "fresh"
  }]
}

For a human-readable view, open Pipeline Health.

Endpoint

POST

Report inaccuracy

Send a sanitized correction report to the Mast operator.
/api/v1/report/inaccuracy

JSON body

url string
The page or source connected to the correction.
message string
A concise explanation of what appears inaccurate.
stateCode string
Optional two-letter state code.