行事曆訂閱 API 參考

建立可撤銷的 ICS 訂閱來源，內容可包含經濟數據發布、國定假日，或兩者。

建立訂閱

使用你的 Narwhal Bearer 金鑰傳送建立訂閱的請求。產品概覽 →

POST /v1/calendars/subscriptions

curl --request POST \
  --url "https://api.narwhalapi.com/v1/calendars/subscriptions" \
  --header "Authorization: Bearer $NARWHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"countries":["USA"],"start_date":"2026-09-01","end_date":"2026-12-31","include_releases":true,"include_holidays":true}'

請求欄位

欄位	規則
`countries`	必填清單，包含 1–50 個 ISO alpha-3 國家代碼。
`start_date / end_date`	必填的日期範圍，包含首尾日期，年份須介於 1900 至 2200 年，且起訖日期最多相差 366 天。
`include_releases / include_holidays`	選填的布林值；兩者預設皆為 true，且至少一個必須保持為 true。
`families`	選填的發布類別： `gdp`, `prices`, `labour`, `trade`, `yield_curve`。省略或使用空清單表示包含所有類別。若只要訂閱假日資料，請將 `include_releases` 设為 false。
`scope`	選填的範圍識別碼，不得為空字串，最長 64 個字元。

僅訂閱假日時，可選擇已發布假日資料但未涵蓋於經濟數據發布清單的國家。

回應範例

回應範例。建立訂閱時，請儲存含權杖的 URL；建立訂閱的回應僅會回傳一次該 URL。

已建立

{
  "subscription_id": "example-subscription",
  "url": "https://api.narwhalapi.com/v1/calendars/subscriptions/EXAMPLE_TOKEN.ics",
  "expires_at": "2026-12-31T23:59:59Z",
  "refresh_note": "calendar clients control refresh latency"
}

subscription_id 用來識別要撤銷的紀錄。 expires_at 是到期時間戳記；更新延遲由行事曆用戶端控制。

更新與撤銷

行事曆用戶端透過以下請求取得資料： GET /v1/calendars/subscriptions/{token}.ics。訂閱來源支援 ETag 更新。請將含權杖的 URL 視為機密：任何持有此 URL 的人，都能在到期或撤銷前讀取訂閱內容。

使用你的 Bearer 金鑰呼叫 DELETE /v1/calendars/subscriptions/{subscription_id} 來撤銷訂閱。已過期、已撤銷或無法識別的訂閱權杖會回傳 404。訂閱內容絕不會包含你的 API 金鑰。