Api docs updates (#20388)

* Update classification API docs

* Add information to events api

* Fix tag

* Add exports

* Add generic response to model for classification apis

* Add preview API information

* Cleanup

* Cleanup

frigate/api/defs/request/classification_body.py

@@ -1,4 +1,6 @@
-from pydantic import BaseModel
+from typing import List
+
+from pydantic import BaseModel, Field
 
 
 class RenameFaceBody(BaseModel):
@@ -7,3 +9,9 @@ class RenameFaceBody(BaseModel):
 
 class AudioTranscriptionBody(BaseModel):
     event_id: str
+
+
+class DeleteFaceImagesBody(BaseModel):
+    ids: List[str] = Field(
+        description="List of image filenames to delete from the face folder"
+    )

frigate/api/defs/response/classification_response.py

@@ -0,0 +1,38 @@
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, Field, RootModel
+
+
+class FacesResponse(RootModel[Dict[str, List[str]]]):
+    """Response model for the get_faces endpoint.
+
+    Returns a mapping of face names to lists of image filenames.
+    Each face name corresponds to a directory in the faces folder,
+    and the list contains the names of image files for that face.
+
+    Example:
+        {
+            "john_doe": ["face1.webp", "face2.jpg"],
+            "jane_smith": ["face3.png"]
+        }
+    """
+
+    root: Dict[str, List[str]] = Field(
+        default_factory=dict,
+        description="Dictionary mapping face names to lists of image filenames",
+    )
+
+
+class FaceRecognitionResponse(BaseModel):
+    """Response model for face recognition endpoint.
+
+    Returns the result of attempting to recognize a face from an uploaded image.
+    """
+
+    success: bool = Field(description="Whether the face recognition was successful")
+    score: Optional[float] = Field(
+        default=None, description="Confidence score of the recognition (0-1)"
+    )
+    face_name: Optional[str] = Field(
+        default=None, description="The recognized face name if successful"
+    )

frigate/api/defs/response/export_response.py

@@ -0,0 +1,30 @@
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ExportModel(BaseModel):
+    """Model representing a single export."""
+
+    id: str = Field(description="Unique identifier for the export")
+    camera: str = Field(description="Camera name associated with this export")
+    name: str = Field(description="Friendly name of the export")
+    date: float = Field(description="Unix timestamp when the export was created")
+    video_path: str = Field(description="File path to the exported video")
+    thumb_path: str = Field(description="File path to the export thumbnail")
+    in_progress: bool = Field(
+        description="Whether the export is currently being processed"
+    )
+
+
+class StartExportResponse(BaseModel):
+    """Response model for starting an export."""
+
+    success: bool = Field(description="Whether the export was started successfully")
+    message: str = Field(description="Status or error message")
+    export_id: Optional[str] = Field(
+        default=None, description="The export ID if successfully started"
+    )
+
+
+ExportsResponse = List[ExportModel]

frigate/api/defs/response/preview_response.py

@@ -0,0 +1,17 @@
+from typing import List
+
+from pydantic import BaseModel, Field
+
+
+class PreviewModel(BaseModel):
+    """Model representing a single preview clip."""
+
+    camera: str = Field(description="Camera name for this preview")
+    src: str = Field(description="Path to the preview video file")
+    type: str = Field(description="MIME type of the preview video (video/mp4)")
+    start: float = Field(description="Unix timestamp when the preview starts")
+    end: float = Field(description="Unix timestamp when the preview ends")
+
+
+PreviewsResponse = List[PreviewModel]
+PreviewFramesResponse = List[str]

frigate/api/defs/tags.py

@@ -10,5 +10,5 @@ class Tags(Enum):
     review = "Review"
     export = "Export"
     events = "Events"
-    classification = "classification"
+    classification = "Classification"
     auth = "Auth"