From 57cddc14bb5c3ffe6c58ba48bdc2411c261fa86f Mon Sep 17 00:00:00 2001
From: Allen Porter <allen@thebends.org>
Date: Sat, 14 May 2022 23:14:53 -0700
Subject: [PATCH] Add documentation for the existing calendar rest APIs (#1330)

---
 docs/api/rest.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/docs/api/rest.md b/docs/api/rest.md
index 39714975..967ee48d 100644
--- a/docs/api/rest.md
+++ b/docs/api/rest.md
@@ -456,6 +456,73 @@ curl -X GET -H "Authorization: Bearer ABCDEFGH" \
 
 </ApiEndpoint>
 
+
+<ApiEndpoint path="/api/calendars" method="get">
+
+Returns the list of calendar entities.
+
+```json
+[
+  {
+    "entity_id": "calendar.holidays",
+    "name": "National Holidays",
+  },
+  {
+    "entity_id": "calendar.personal",
+    "name": "Personal Calendar",
+  }
+]
+```
+
+Sample `curl` command:
+
+```shell
+curl -X GET -H "Authorization: Bearer ABCDEFGH" \
+  -H "Content-Type: application/json" \
+  http://localhost:8123/api/calendars
+```
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/api/calendars/<calendar entity_id>" method="get">
+
+Returns the list of calendar events for the specified calendar entity_id between the `start` and `end` times (exclusive).
+
+The events in the response have a `start` and `end` that contain either `dateTime` or `date` for an all day event.
+
+```json
+[
+  {
+    "summary": "Cinco de Mayo",
+    "start": {
+      "date": "2022-05-05"
+    },
+    "end": {
+      "date": "2022-05-06"
+    },
+  },
+  {
+    "summary": "Birthday Party",
+    "start": {
+      "dateTime": "2022-05-06T20:00:00-07:00"
+    },
+    "end": {
+      "dateTime": "2022-05-06T23:00:00-07:00"
+    }
+  }
+]
+```
+
+Sample `curl` command:
+
+```shell
+curl -X GET -H "Authorization: Bearer ABCDEFGH" \
+  -H "Content-Type: application/json" \
+  http://localhost:8123/api/calendars/calendar.holidays?start=2022-05-01T07:00:00.000Z&end=2022-06-12T07:00:00.000Z
+```
+
+</ApiEndpoint>
+
 <ApiEndpoint path="/api/states/<entity_id>" method="post">
 
 Updates or creates a state. You can create any state that you want, it does not have to be backed by an entity in Home Assistant.