Document the v2 schedule endpoint

docs/ai/api.md

@@ -97,6 +97,22 @@ Requires API key.
 
 ---
 
+# Schedule (v2)
+
+Endpoint:
+
+GET /api/v2/schedule?email=<email>&licenseKey=<key>
+
+Authenticates with the paired `email` + `licenseKey` query parameters and
+validates only that the key belongs to the account (not that the license is
+active/entitled). Returns the user's Blocks with start/end times and the IDs of
+the selected Proclamations (content is fetched separately via
+`/api/v2/proclamations`). Rate limited to 10 requests per minute per IP.
+Failure messages follow the existing v2 shape:
+`not-authorized` or `this key doesn't appear to belong to you`.
+
+---
+
 # GHL Account Creation Webhook
 
 Endpoint:

docs/openapi.yaml

@@ -31,6 +31,8 @@ tags:
     description: Proclamation content, optionally scoped by license entitlement.
   - name: License
     description: License key validation.
+  - name: Schedule
+    description: A user's daily listening schedule, consumed by the kiosk.
   - name: Automations
     description: Signed machine-to-machine webhooks.
 paths:
@@ -230,6 +232,64 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorMessage'
+  /api/v2/schedule:
+    get:
+      tags: [Schedule]
+      summary: Get a user's listening schedule (query-param auth)
+      description: |
+        Machine-to-app endpoint used by the RadiantWave kiosk. Authenticates via
+        the paired `email` + `licenseKey` **query parameters** and validates only
+        that the key belongs to the account for that email. License
+        active/entitlement is deliberately not checked here: an invalid license
+        would already lock the kiosk out, so this endpoint only checks the
+        pairing.
+
+        Returns every Block with its start/end times and the ordered list of
+        selected Proclamation IDs. Proclamation content is not included; the
+        kiosk fetches it separately via `/api/v2/proclamations`.
+      operationId: getSchedule
+      parameters:
+        - in: query
+          name: email
+          required: true
+          schema:
+            type: string
+            format: email
+          description: Account email.
+        - in: query
+          name: licenseKey
+          required: true
+          schema:
+            type: string
+            pattern: '^[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$'
+          description: License key. The legacy alias `key` is also accepted.
+      responses:
+        '200':
+          description: The user's schedule (possibly empty).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ScheduleResponse'
+        '400':
+          description: |
+            Missing/invalid parameters, unknown key or user, or the key does not
+            belong to the email's account. Possible messages: `not-authorized`,
+            `this key doesn't appear to belong to you`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMessage'
+        '429':
+          description: Rate limit exceeded (10 requests per minute per IP).
+          headers:
+            Retry-After:
+              schema:
+                type: integer
+              description: Seconds to wait before retrying.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMessage'
   /api/v2/automations/create/account:
     post:
       tags: [Automations]
@@ -436,6 +496,49 @@ components:
         email_address:
           type: string
           format: email
+    ScheduleBlock:
+      type: object
+      required: [id, startTime, startMinutes, endTime, endMinutes, proclamationIds]
+      properties:
+        id:
+          type: string
+          format: uuid
+        startTime:
+          type: string
+          example: '06:00'
+          description: Wall-clock start time as `HH:MM`.
+        startMinutes:
+          type: integer
+          minimum: 0
+          maximum: 1440
+          description: Minutes from midnight.
+        endTime:
+          type: string
+          example: '08:00'
+          description: Wall-clock end time as `HH:MM`.
+        endMinutes:
+          type: integer
+          minimum: 0
+          maximum: 1440
+          description: Minutes from midnight.
+        proclamationIds:
+          type: array
+          description: IDs of the selected Proclamations, in play order.
+          items:
+            type: string
+            format: uuid
+    ScheduleResponse:
+      type: object
+      required: [email, blocks]
+      properties:
+        email:
+          type: string
+          format: email
+        blocks:
+          type: array
+          maxItems: 4
+          items:
+            $ref: '#/components/schemas/ScheduleBlock'
     OnboardingRequest:
       type: object
       required: [email]