From 5a89772eb8e05ad563a04c2aa3130486a83f5ee1 Mon Sep 17 00:00:00 2001
From: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com>
Date: Tue, 6 Jan 2026 07:36:14 -0600
Subject: [PATCH] endpoint descriptions

---
 docs/static/frigate-api.yaml | 53 ++++++++++++++++++++++++++++++++++++
 frigate/api/app.py           | 22 +++++++++++++--
 2 files changed, 72 insertions(+), 3 deletions(-)

diff --git a/docs/static/frigate-api.yaml b/docs/static/frigate-api.yaml
index 1bd5e95b8..2e18cad6f 100644
--- a/docs/static/frigate-api.yaml
+++ b/docs/static/frigate-api.yaml
@@ -326,6 +326,59 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/HTTPValidationError"
+  /media/sync:
+    post:
+      tags:
+        - App
+      summary: Start media sync job
+      description: |-
+        Start an asynchronous media sync job to find and (optionally) remove orphaned media files.
+        Returns 202 with job details when queued, or 409 if a job is already running.
+      operationId: sync_media_media_sync_post
+      requestBody:
+        required: true
+        content:
+          application/json:
+      responses:
+        "202":
+          description: Accepted - Job queued
+        "409":
+          description: Conflict - Job already running
+        "422":
+          description: Validation Error
+
+  /media/sync/current:
+    get:
+      tags:
+        - App
+      summary: Get current media sync job
+      description: |-
+        Retrieve the current running media sync job, if any. Returns the job details or null when no job is active.
+      operationId: get_media_sync_current_media_sync_current_get
+      responses:
+        "200":
+          description: Successful Response
+        "422":
+          description: Validation Error
+
+  /media/sync/status/{job_id}:
+    get:
+      tags:
+        - App
+      summary: Get media sync job status
+      description: |-
+        Get status and results for the specified media sync job id. Returns 200 with job details including results, or 404 if the job is not found.
+      operationId: get_media_sync_status_media_sync_status__job_id__get
+      parameters:
+        - name: job_id
+          in: path
+      responses:
+        "200":
+          description: Successful Response
+        "404":
+          description: Not Found - Job not found
+        "422":
+          description: Validation Error
   /faces/train/{name}/classify:
     post:
       tags:
diff --git a/frigate/api/app.py b/frigate/api/app.py
index f5c874695..a50e52afc 100644
--- a/frigate/api/app.py
+++ b/frigate/api/app.py
@@ -608,7 +608,13 @@ def restart():
     )
 
 
-@router.post("/media/sync", dependencies=[Depends(require_role(["admin"]))])
+@router.post(
+    "/media/sync",
+    dependencies=[Depends(require_role(["admin"]))],
+    summary="Start media sync job",
+    description="""Start an asynchronous media sync job to find and (optionally) remove orphaned media files.
+    Returns 202 with job details when queued, or 409 if a job is already running.""",
+)
 def sync_media(body: MediaSyncBody = Body(...)):
     """Start async media sync job - remove orphaned files.
 
@@ -651,7 +657,13 @@ def sync_media(body: MediaSyncBody = Body(...)):
     )
 
 
-@router.get("/media/sync/current", dependencies=[Depends(require_role(["admin"]))])
+@router.get(
+    "/media/sync/current",
+    dependencies=[Depends(require_role(["admin"]))],
+    summary="Get current media sync job",
+    description="""Retrieve the current running media sync job, if any. Returns the job details
+    or null when no job is active.""",
+)
 def get_media_sync_current():
     """Get the current running media sync job, if any."""
     job = get_current_media_sync_job()
@@ -666,7 +678,11 @@ def get_media_sync_current():
 
 
 @router.get(
-    "/media/sync/status/{job_id}", dependencies=[Depends(require_role(["admin"]))]
+    "/media/sync/status/{job_id}",
+    dependencies=[Depends(require_role(["admin"]))],
+    summary="Get media sync job status",
+    description="""Get status and results for the specified media sync job id. Returns 200 with
+    job details including results, or 404 if the job is not found.""",
 )
 def get_media_sync_status(job_id: str):
     """Get the status of a specific media sync job."""