Update API schema to latest (#19156)

* Add description to snapshot api * Update API schema
2025-07-26 13:47:03 +02:00 · 2025-07-15 20:53:21 -06:00 · 2025-07-15 20:53:21 -06:00 · 3eb3797bc5
commit 3eb3797bc5
parent f81ac43be6
2 changed files with 172 additions and 63 deletions
--- a/docs/static/frigate-api.yaml
+++ b/docs/static/frigate-api.yaml
@ -105,7 +105,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/users/{username}":
+  /users/{username}:
    delete:
      tags:
        - Auth
@ -130,7 +130,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/users/{username}/password":
+  /users/{username}/password:
    put:
      tags:
        - Auth
@ -161,7 +161,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/users/{username}/role":
+  /users/{username}/role:
    put:
      tags:
        - Auth
@ -228,7 +228,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/faces/train/{name}/classify":
+  /faces/train/{name}/classify:
    post:
      tags:
        - Events
@ -259,7 +259,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/faces/{name}/create":
+  /faces/{name}/create:
    post:
      tags:
        - Events
@ -284,7 +284,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/faces/{name}/register":
+  /faces/{name}/register:
    post:
      tags:
        - Events
@ -340,7 +340,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/faces/{name}/delete":
+  /faces/{name}/delete:
    post:
      tags:
        - Events
@ -371,6 +371,37 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
+  /faces/{old_name}/rename:
+    put:
+      tags:
+        - Events
+      summary: Rename Face
+      operationId: rename_face_faces__old_name__rename_put
+      parameters:
+        - name: old_name
+          in: path
+          required: true
+          schema:
+            type: string
+            title: Old Name
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RenameFaceBody"
+      responses:
+        "200":
+          description: Successful Response
+          content:
+            application/json:
+              schema: {}
+        "422":
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HTTPValidationError"
  /lpr/reprocess:
    put:
      tags:
@ -659,7 +690,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/review/event/{event_id}":
+  /review/event/{event_id}:
    get:
      tags:
        - Review
@ -685,7 +716,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/review/{review_id}":
+  /review/{review_id}:
    get:
      tags:
        - Review
@ -711,7 +742,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/review/{review_id}/viewed":
+  /review/{review_id}/viewed:
    delete:
      tags:
        - Review
@ -774,7 +805,7 @@ paths:
          content:
            application/json:
              schema: {}
-  "/go2rtc/streams/{camera_name}":
+  /go2rtc/streams/{camera_name}:
    get:
      tags:
        - App
@ -991,7 +1022,7 @@ paths:
          content:
            application/json:
              schema: {}
-  "/logs/{service}":
+  /logs/{service}:
    get:
      tags:
        - App
@ -1287,7 +1318,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/preview/{camera_name}/start/{start_ts}/end/{end_ts}":
+  /preview/{camera_name}/start/{start_ts}/end/{end_ts}:
    get:
      tags:
        - Preview
@ -1325,7 +1356,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/preview/{year_month}/{day}/{hour}/{camera_name}/{tz_name}":
+  /preview/{year_month}/{day}/{hour}/{camera_name}/{tz_name}:
    get:
      tags:
        - Preview
@ -1376,7 +1407,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/preview/{camera_name}/start/{start_ts}/end/{end_ts}/frames":
+  /preview/{camera_name}/start/{start_ts}/end/{end_ts}/frames:
    get:
      tags:
        - Preview
@ -1463,7 +1494,7 @@ paths:
          content:
            application/json:
              schema: {}
-  "/export/{camera_name}/start/{start_time}/end/{end_time}":
+  /export/{camera_name}/start/{start_time}/end/{end_time}:
    post:
      tags:
        - Export
@ -1507,7 +1538,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/export/{event_id}/rename":
+  /export/{event_id}/rename:
    patch:
      tags:
        - Export
@ -1538,7 +1569,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/export/{event_id}":
+  /export/{event_id}:
    delete:
      tags:
        - Export
@ -1563,7 +1594,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/exports/{export_id}":
+  /exports/{export_id}:
    get:
      tags:
        - Export
@ -1699,7 +1730,7 @@ paths:
            anyOf:
              - type: string
              - type: "null"
-            default: "00:00,24:00"
+            default: 00:00,24:00
            title: Time Range
        - name: has_clip
          in: query
@ -2007,7 +2038,7 @@ paths:
            anyOf:
              - type: string
              - type: "null"
-            default: "00:00,24:00"
+            default: 00:00,24:00
            title: Time Range
        - name: has_clip
          in: query
@ -2147,7 +2178,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}":
+  /events/{event_id}:
    get:
      tags:
        - Events
@ -2198,7 +2229,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/retain":
+  /events/{event_id}/retain:
    post:
      tags:
        - Events
@ -2249,7 +2280,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/plus":
+  /events/{event_id}/plus:
    post:
      tags:
        - Events
@ -2280,7 +2311,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/false_positive":
+  /events/{event_id}/false_positive:
    put:
      tags:
        - Events
@ -2306,7 +2337,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/sub_label":
+  /events/{event_id}/sub_label:
    post:
      tags:
        - Events
@ -2338,7 +2369,39 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/description":
+  /events/{event_id}/recognized_license_plate:
+    post:
+      tags:
+        - Events
+      summary: Set Plate
+      operationId: set_plate_events__event_id__recognized_license_plate_post
+      parameters:
+        - name: event_id
+          in: path
+          required: true
+          schema:
+            type: string
+            title: Event Id
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EventsLPRBody"
+      responses:
+        "200":
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "422":
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HTTPValidationError"
+  /events/{event_id}/description:
    post:
      tags:
        - Events
@ -2370,7 +2433,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/description/regenerate":
+  /events/{event_id}/description/regenerate:
    put:
      tags:
        - Events
@ -2430,7 +2493,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{camera_name}/{label}/create":
+  /events/{camera_name}/{label}/create:
    post:
      tags:
        - Events
@ -2473,7 +2536,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/end":
+  /events/{event_id}/end:
    put:
      tags:
        - Events
@ -2505,7 +2568,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}":
+  /{camera_name}:
    get:
      tags:
        - Media
@ -2592,7 +2655,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/ptz/info":
+  /{camera_name}/ptz/info:
    get:
      tags:
        - Media
@ -2617,7 +2680,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/latest.{extension}":
+  /{camera_name}/latest.{extension}:
    get:
      tags:
        - Media
@ -2720,7 +2783,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/recordings/{frame_time}/snapshot.{format}":
+  /{camera_name}/recordings/{frame_time}/snapshot.{format}:
    get:
      tags:
        - Media
@ -2767,7 +2830,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/plus/{frame_time}":
+  /{camera_name}/plus/{frame_time}:
    post:
      tags:
        - Media
@ -2846,7 +2909,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/recordings/summary":
+  /{camera_name}/recordings/summary:
    get:
      tags:
        - Media
@ -2879,13 +2942,13 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/recordings":
+  /{camera_name}/recordings:
    get:
      tags:
        - Media
      summary: Recordings
      description: >-
-        Return specific camera recordings between the given 'after'/'end' times.
+        Return specific camera recordings between the given "after"/"end" times.
        If not provided the last hour will be used
      operationId: recordings__camera_name__recordings_get
      parameters:
@ -2900,14 +2963,14 @@ paths:
          required: false
          schema:
            type: number
-            default: 1744227965.180043
+            default: 1752611870.43948
            title: After
        - name: before
          in: query
          required: false
          schema:
            type: number
-            default: 1744231565.180048
+            default: 1752615470.43949
            title: Before
      responses:
        "200":
@ -2921,13 +2984,14 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/start/{start_ts}/end/{end_ts}/clip.mp4":
+  /{camera_name}/start/{start_ts}/end/{end_ts}/clip.mp4:
    get:
      tags:
        - Media
      summary: Recording Clip
      description: >-
-        For iOS devices, use the master.m3u8 HLS link instead of clip.mp4. Safari does not reliably process progressive mp4 files.
+        For iOS devices, use the master.m3u8 HLS link instead of clip.mp4.
+        Safari does not reliably process progressive mp4 files.
      operationId: recording_clip__camera_name__start__start_ts__end__end_ts__clip_mp4_get
      parameters:
        - name: camera_name
@ -2960,11 +3024,14 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/vod/{camera_name}/start/{start_ts}/end/{end_ts}":
+  /vod/{camera_name}/start/{start_ts}/end/{end_ts}:
    get:
      tags:
        - Media
      summary: Vod Ts
+      description: >-
+        Returns an HLS playlist for the specified timestamp-range on the
+        specified camera. Append /master.m3u8 or /index.m3u8 for HLS playback.
      operationId: vod_ts_vod__camera_name__start__start_ts__end__end_ts__get
      parameters:
        - name: camera_name
@ -2997,12 +3064,14 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/vod/{year_month}/{day}/{hour}/{camera_name}":
+  /vod/{year_month}/{day}/{hour}/{camera_name}:
    get:
      tags:
        - Media
      summary: Vod Hour No Timezone
-      description: VOD for specific hour. Uses the default timezone (UTC).
+      description: >-
+        Returns an HLS playlist for the specified date-time on the specified
+        camera. Append /master.m3u8 or /index.m3u8 for HLS playback.
      operationId: vod_hour_no_timezone_vod__year_month___day___hour___camera_name__get
      parameters:
        - name: year_month
@ -3041,11 +3110,15 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/vod/{year_month}/{day}/{hour}/{camera_name}/{tz_name}":
+  /vod/{year_month}/{day}/{hour}/{camera_name}/{tz_name}:
    get:
      tags:
        - Media
      summary: Vod Hour
+      description: >-
+        Returns an HLS playlist for the specified date-time (with timezone) on
+        the specified camera. Append /master.m3u8 or /index.m3u8 for HLS
+        playback.
      operationId: vod_hour_vod__year_month___day___hour___camera_name___tz_name__get
      parameters:
        - name: year_month
@ -3090,11 +3163,14 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/vod/event/{event_id}":
+  /vod/event/{event_id}:
    get:
      tags:
        - Media
      summary: Vod Event
+      description: >-
+        Returns an HLS playlist for the specified object. Append /master.m3u8 or
+        /index.m3u8 for HLS playback.
      operationId: vod_event_vod_event__event_id__get
      parameters:
        - name: event_id
@ -3115,11 +3191,15 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/snapshot.jpg":
+  /events/{event_id}/snapshot.jpg:
    get:
      tags:
        - Media
      summary: Event Snapshot
+      description: >-
+        Returns a snapshot image for the specified object id. NOTE: The query
+        params only take affect while the event is in-progress. Once the event
+        has ended the snapshot configuration is used.
      operationId: event_snapshot_events__event_id__snapshot_jpg_get
      parameters:
        - name: event_id
@ -3190,7 +3270,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/thumbnail.{extension}":
+  /events/{event_id}/thumbnail.{extension}:
    get:
      tags:
        - Media
@ -3240,7 +3320,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/grid.jpg":
+  /{camera_name}/grid.jpg:
    get:
      tags:
        - Media
@ -3279,7 +3359,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/snapshot-clean.png":
+  /events/{event_id}/snapshot-clean.png:
    get:
      tags:
        - Media
@ -3311,7 +3391,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/clip.mp4":
+  /events/{event_id}/clip.mp4:
    get:
      tags:
        - Media
@ -3336,7 +3416,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/events/{event_id}/preview.gif":
+  /events/{event_id}/preview.gif:
    get:
      tags:
        - Media
@ -3361,7 +3441,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/start/{start_ts}/end/{end_ts}/preview.gif":
+  /{camera_name}/start/{start_ts}/end/{end_ts}/preview.gif:
    get:
      tags:
        - Media
@ -3407,7 +3487,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/start/{start_ts}/end/{end_ts}/preview.mp4":
+  /{camera_name}/start/{start_ts}/end/{end_ts}/preview.mp4:
    get:
      tags:
        - Media
@ -3453,7 +3533,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/review/{event_id}/preview":
+  /review/{event_id}/preview:
    get:
      tags:
        - Media
@ -3488,7 +3568,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/preview/{file_name}/thumbnail.webp":
+  /preview/{file_name}/thumbnail.webp:
    get:
      tags:
        - Media
@ -3514,7 +3594,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/preview/{file_name}/thumbnail.jpg":
+  /preview/{file_name}/thumbnail.jpg:
    get:
      tags:
        - Media
@ -3540,7 +3620,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/{label}/thumbnail.jpg":
+  /{camera_name}/{label}/thumbnail.jpg:
    get:
      tags:
        - Media
@ -3571,7 +3651,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/{label}/best.jpg":
+  /{camera_name}/{label}/best.jpg:
    get:
      tags:
        - Media
@ -3602,7 +3682,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/{label}/clip.mp4":
+  /{camera_name}/{label}/clip.mp4:
    get:
      tags:
        - Media
@ -3633,7 +3713,7 @@ paths:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
-  "/{camera_name}/{label}/snapshot.jpg":
+  /{camera_name}/{label}/snapshot.jpg:
    get:
      tags:
        - Media
@ -3985,6 +4065,23 @@ components:
          title: End Time
      type: object
      title: EventsEndBody
+    EventsLPRBody:
+      properties:
+        recognizedLicensePlate:
+          type: string
+          maxLength: 100
+          title: Recognized License Plate
+        recognizedLicensePlateScore:
+          anyOf:
+            - type: number
+              maximum: 1
+              exclusiveMinimum: 0
+            - type: "null"
+          title: Score for recognized license plate
+      type: object
+      required:
+        - recognizedLicensePlate
+      title: EventsLPRBody
    EventsSubLabelBody:
      properties:
        subLabel:
@ -4105,6 +4202,15 @@ components:
        - thumbnails
        - snapshot
      title: RegenerateDescriptionEnum
+    RenameFaceBody:
+      properties:
+        new_name:
+          type: string
+          title: New Name
+      type: object
+      required:
+        - new_name
+      title: RenameFaceBody
    ReviewActivityMotionResponse:
      properties:
        start_time:
--- a/frigate/api/media.py
+++ b/frigate/api/media.py
@ -800,7 +800,10 @@ def vod_event(event_id: str):
    )


-@router.get("/events/{event_id}/snapshot.jpg")
+@router.get(
+    "/events/{event_id}/snapshot.jpg",
+    description="Returns a snapshot image for the specified object id. NOTE: The query params only take affect while the event is in-progress. Once the event has ended the snapshot configuration is used.",
+)
 def event_snapshot(
    request: Request,
    event_id: str,