/v1/announcements

Description

Returns approved FinCal API product announcements — such as newly added calendars, data corrections, or new endpoint releases — from a configurable look-back window. Only announcements that have been reviewed and approved are returned. The default window is the past 7 days. Use days=30 or larger to see older announcements.

If no announcements exist within the requested window, the response returns count: 0 and an empty announcements array — it is not an error.

Endpoint

GET https://fincalapi.com/v1/announcements

Parameters

Default Behavior

With no parameters, /v1/announcements returns all approved announcements from the past 7 days. If the API has not published any announcements in the last 7 days, the response is {"days": 7, "count": 0, "announcements": []}. Increase days to extend the look-back window.

Request Examples

All /v1/ endpoints require an API key. Get one free →

• GET /v1/announcements — Approved announcements from the past 7 days (default window)
• GET /v1/announcements?days=30 — Approved announcements from the past 30 days
• GET /v1/announcements?days=3650 — All approved announcements (up to 10 years back)

Usage Examples

import requests

API_KEY = "fincal_live_YOUR_KEY_HERE"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Default: past 7 days
response = requests.get("https://fincalapi.com/v1/announcements", headers=headers)
data = response.json()
print(f"Found {data['count']} announcement(s)")
for a in data["announcements"]:
    print(f"[{a['date']}] {a['title']}")

# Extended window: past 30 days
response = requests.get(
    "https://fincalapi.com/v1/announcements",
    params={"days": 30},
    headers=headers
)
print(response.json())

# Default 7-day window
curl -H "Authorization: Bearer fincal_live_YOUR_KEY_HERE" \
  "https://fincalapi.com/v1/announcements"

# Extended 30-day window
curl -H "Authorization: Bearer fincal_live_YOUR_KEY_HERE" \
  "https://fincalapi.com/v1/announcements?days=30"

Example JSON Response

When no announcements fall within the requested window (e.g., /v1/announcements on a quiet week):

{
  "days": 7,
  "count": 0,
  "announcements": []
}

When announcements are present (structure of a single entry):

{
  "days": 30,
  "count": 1,
  "announcements": [
    {
      "id": "example-announcement-id",
      "date": "YYYY-MM-DD",
      "title": "Announcement title",
      "summary": "Brief description of the update.",
      "type": "calendar_added",
      "related_calendars": ["NYSE"]
    }
  ]
}

To query live announcement data, pass your API key in the Authorization: Bearer header. See auth.html for examples.

Common Use Cases

• Changelog feeds for applications that integrate FinCal API data
• Automated alerts when new calendars or endpoints are added
• Audit trails confirming when specific calendar data corrections were published
• Healthcheck pages that surface the most recent platform activity

Notes & Limitations

• Only approved announcements are included. Internal or draft updates are never returned.
• A response with count: 0 and announcements: [] is normal when no platform updates have been published within the requested window — it is not an error condition.
• The days parameter accepts integers from 1 to 3650. Values outside that range return HTTP 422.
• The type field categorizes each announcement: calendar_added, endpoint_added, data_correction, or similar.
• The related_calendars field is null for non-calendar announcements and a list of calendar codes when calendars are directly involved.