From b79ad9871afc06e6507eeaef0ca82431399154a2 Mon Sep 17 00:00:00 2001 From: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com> Date: Sat, 13 Jun 2026 17:04:22 -0500 Subject: [PATCH] generate the API docs OpenAPI spec from the app with per-endpoint auth requirements (#23476) --- .github/workflows/pull_request.yml | 2 + AGENTS.md | 10 + docs/static/frigate-api.yaml | 4105 ++++++++++++++++++---------- generate_api_auth_spec.py | 606 ++++ 4 files changed, 3257 insertions(+), 1466 deletions(-) create mode 100644 generate_api_auth_spec.py diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index 516b55e89b..d2e279966e 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -125,5 +125,7 @@ jobs: run: devcontainer up --workspace-folder . - name: Run mypy in devcontainer run: devcontainer exec --workspace-folder . bash -lc "python3 -u -m mypy --config-file frigate/mypy.ini frigate" + - name: Check API spec is up to date + run: devcontainer exec --workspace-folder . bash -lc "python3 generate_api_auth_spec.py --check" - name: Run unit tests in devcontainer run: devcontainer exec --workspace-folder . bash -lc "python3 -u -m unittest" diff --git a/AGENTS.md b/AGENTS.md index 61b8373a82..d078c2fdba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -235,6 +235,14 @@ ruff check frigate/ # Type check python3 -u -m mypy --config-file frigate/mypy.ini frigate + +# Regenerate the OpenAPI spec after adding, changing, or removing an API +# endpoint or its auth dependency — outputs docs/static/frigate-api.yaml, +# annotated with each endpoint's auth requirement (admin / any / camera / +# public). NEVER edit that file by hand. CI runs the --check variant and fails +# if it is out of date. (from repo root) +python3 generate_api_auth_spec.py +python3 generate_api_auth_spec.py --check ``` ### Frontend (from web/ directory) @@ -316,6 +324,8 @@ async def get_events(request: Request, limit: int = 100): # Implementation ``` +After adding, changing, or removing an endpoint (or its auth dependency), regenerate the OpenAPI spec with `python3 generate_api_auth_spec.py` so `docs/static/frigate-api.yaml` stays in sync and the endpoint's auth requirement is documented. CI enforces this via the `--check` variant; never edit that file by hand. + ### Configuration Access ```python diff --git a/docs/static/frigate-api.yaml b/docs/static/frigate-api.yaml index 2c6109b985..0ee41a0feb 100644 --- a/docs/static/frigate-api.yaml +++ b/docs/static/frigate-api.yaml @@ -1,14 +1,14 @@ +# Generated by generate_api_auth_spec.py — do not edit by hand. +# Regenerate with: python3 generate_api_auth_spec.py +# The empty info.title is intentional: a docusaurus-openapi-docs convention +# that suppresses the generated API introduction page. openapi: 3.1.0 info: - # To avoid the introduction page we set the title to empty string - # https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/4e771d309f6defe395449b26cc3c65814d72cbcc/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts#L92-L129 - title: "" + title: '' version: 0.1.0 - servers: - url: https://demo.frigate.video/api - url: http://localhost:5001/api - paths: /auth/first_time_login: get: @@ -16,30 +16,33 @@ paths: - Auth summary: First Time Login description: |- + **Access:** Public — no authentication required. + Return whether the admin first-time login help flag is set in config. This endpoint is intentionally unauthenticated so the login page can query it before a user is authenticated. operationId: first_time_login_auth_first_time_login_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: [] + x-required-role: public /auth: get: tags: - Auth summary: Authenticate request - description: >- - Authenticates the current request based on proxy headers or JWT token. - This endpoint verifies authentication credentials and manages JWT token - refresh. On success, no JSON body is returned; authentication state is - communicated via response headers and cookies. + description: |- + **Access:** Public — no authentication required. + + Authenticates the current request based on proxy headers or JWT token. This endpoint verifies authentication credentials and manages JWT token refresh. On success, no JSON body is returned; authentication state is communicated via response headers and cookies. operationId: auth_auth_get responses: - "202": + '202': description: Authentication Accepted (no response body) content: application/json: @@ -50,65 +53,67 @@ paths: schema: type: string remote-role: - description: "Resolved role (e.g., admin, viewer, or custom)" + description: Resolved role (e.g., admin, viewer, or custom) schema: type: string Set-Cookie: description: May include refreshed JWT cookie when applicable schema: type: string - "401": + '401': description: Authentication Failed + security: [] + x-required-role: public /profile: get: tags: - Auth summary: Get user profile - description: >- - Returns the current authenticated user's profile including username, - role, and allowed cameras. This endpoint requires authentication and - returns information about the user's permissions. + description: |- + **Access:** Any authenticated user. + + Returns the current authenticated user's profile including username, role, and allowed cameras. This endpoint requires authentication and returns information about the user's permissions. operationId: profile_profile_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateUserAuth: [] + x-required-role: any /logout: get: tags: - Auth summary: Logout user - description: >- - Logs out the current user by clearing the session cookie. After logout, - subsequent requests will require re-authentication. + description: |- + **Access:** Public — no authentication required. + + Logs out the current user by clearing the session cookie. After logout, subsequent requests will require re-authentication. operationId: logout_logout_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: [] + x-required-role: public /login: post: tags: - Auth summary: Login with credentials - description: >- - Authenticates a user with username and password. Returns a JWT token as - a secure HTTP-only cookie that can be used for subsequent API requests. - The JWT token can also be retrieved from the response and used as a - Bearer token in the Authorization header. + description: |- + **Access:** Public — no authentication required. + Authenticates a user with username and password. Returns a JWT token as a secure HTTP-only cookie that can be used for subsequent API requests. The JWT token can also be retrieved from the response and used as a Bearer token in the Authorization header. Example using Bearer token: - ``` - - curl -H "Authorization: Bearer " - https://frigate_ip:8971/api/profile - + curl -H "Authorization: Bearer " https://frigate_ip:8971/api/profile ``` operationId: login_login_post requestBody: @@ -116,68 +121,79 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AppPostLoginBody" + $ref: '#/components/schemas/AppPostLoginBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: [] + x-required-role: public /users: get: tags: - Auth summary: Get all users - description: >- - Returns a list of all users with their usernames and roles. Requires - admin role. Each user object contains the username and assigned role. + description: |- + **Access:** Admin role required. + + Returns a list of all users with their usernames and roles. Requires admin role. Each user object contains the username and assigned role. operationId: get_users_users_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin post: tags: - Auth summary: Create new user - description: >- - Creates a new user with the specified username, password, and role. - Requires admin role. Password must be at least 12 characters long. + description: |- + **Access:** Admin role required. + + Creates a new user with the specified username, password, and role. Requires admin role. Password must be at least 12 characters long. operationId: create_user_users_post requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/AppPostUsersBody" + $ref: '#/components/schemas/AppPostUsersBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/users/{username}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /users/{username}: delete: tags: - Auth summary: Delete user - description: >- - Deletes a user by username. The built-in admin user cannot be deleted. - Requires admin role. Returns success message or error if user not found. + description: |- + **Access:** Admin role required. + + Deletes a user by username. The built-in admin user cannot be deleted. Requires admin role. Returns success message or error if user not found. operationId: delete_user_users__username__delete parameters: - name: username @@ -187,28 +203,29 @@ paths: type: string title: Username responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/users/{username}/password": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /users/{username}/password: put: tags: - Auth summary: Update user password - description: >- - Updates a user's password. Users can only change their own password - unless they have admin role. Requires the current password to verify - identity for non-admin users. Password must be at least 12 characters - long. If user changes their own password, a new JWT cookie is - automatically issued. + description: |- + **Access:** Any authenticated user. + + Updates a user's password. Users can only change their own password unless they have admin role. Requires the current password to verify identity for non-admin users. Password must be at least 12 characters long. If user changes their own password, a new JWT cookie is automatically issued. operationId: update_password_users__username__password_put parameters: - name: username @@ -222,28 +239,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AppPutPasswordBody" + $ref: '#/components/schemas/AppPutPasswordBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/users/{username}/role": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + /users/{username}/role: put: tags: - Auth summary: Update user role - description: >- - Updates a user's role. The built-in admin user's role cannot be - modified. Requires admin role. Valid roles are defined in the - configuration. + description: |- + **Access:** Admin role required. + + Updates a user's role. The built-in admin user's role cannot be modified. Requires admin role. Valid roles are defined in the configuration. operationId: update_role_users__username__role_put parameters: - name: username @@ -257,19 +277,22 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AppPutRoleBody" + $ref: '#/components/schemas/AppPutRoleBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /go2rtc/streams: get: tags: @@ -277,44 +300,54 @@ paths: summary: Go2Rtc Streams operationId: go2rtc_streams_go2rtc_streams_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "/go2rtc/streams/{camera_name}": + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' + /go2rtc/streams/{stream_name}: get: tags: - Camera summary: Go2Rtc Camera Stream - operationId: go2rtc_camera_stream_go2rtc_streams__camera_name__get + operationId: go2rtc_camera_stream_go2rtc_streams__stream_name__get parameters: - - name: camera_name + - name: stream_name in: path required: true schema: anyOf: - type: string - - type: "null" - title: Camera Name + - type: 'null' + title: Stream Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/go2rtc/streams/{stream_name}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' put: tags: - Camera summary: Go2Rtc Add Stream - description: Add or update a go2rtc stream configuration. + description: |- + **Access:** Admin role required. + + Add or update a go2rtc stream configuration. operationId: go2rtc_add_stream_go2rtc_streams__stream_name__put parameters: - name: stream_name @@ -328,25 +361,31 @@ paths: required: false schema: type: string - default: "" + default: '' title: Src responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin delete: tags: - Camera summary: Go2Rtc Delete Stream - description: Delete a go2rtc stream. + description: |- + **Access:** Admin role required. + + Delete a go2rtc stream. operationId: go2rtc_delete_stream_go2rtc_streams__stream_name__delete parameters: - name: stream_name @@ -356,17 +395,20 @@ paths: type: string title: Stream Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /ffprobe: get: tags: @@ -379,7 +421,7 @@ paths: required: false schema: type: string - default: "" + default: '' title: Paths - name: detailed in: query @@ -389,24 +431,31 @@ paths: default: false title: Detailed responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + description: '**Access:** Admin role required.' /keyframe_analysis: get: tags: - Camera summary: Keyframe Analysis - description: >- + description: |- + **Access:** Admin role required. + Probe a camera's record stream and classify its keyframe spacing. + Detects smart/+ codecs and long/variable GOPs that degrade recording. operationId: keyframe_analysis_keyframe_analysis_get parameters: @@ -415,26 +464,32 @@ paths: required: false schema: type: string - default: "" + default: '' title: Camera responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /ffprobe/snapshot: get: tags: - Camera summary: Ffprobe Snapshot - description: Get a snapshot from a stream URL using ffmpeg. + description: |- + **Access:** Admin role required. + + Get a snapshot from a stream URL using ffmpeg. operationId: ffprobe_snapshot_ffprobe_snapshot_get parameters: - name: url @@ -442,7 +497,7 @@ paths: required: false schema: type: string - default: "" + default: '' title: Url - name: timeout in: query @@ -452,30 +507,32 @@ paths: default: 10 title: Timeout responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /reolink/detect: get: tags: - Camera summary: Reolink Detect - description: >- + description: |- + **Access:** Admin role required. + Detect Reolink camera capabilities and recommend optimal protocol. - Queries the Reolink camera API to determine the camera's resolution - - and recommends either http-flv (for 5MP and below) or rtsp (for higher - resolutions). + and recommends either http-flv (for 5MP and below) or rtsp (for higher resolutions). operationId: reolink_detect_reolink_detect_get parameters: - name: host @@ -483,44 +540,46 @@ paths: required: false schema: type: string - default: "" + default: '' title: Host - name: username in: query required: false schema: type: string - default: "" + default: '' title: Username - name: password in: query required: false schema: type: string - default: "" + default: '' title: Password responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /onvif/probe: get: tags: - Camera summary: Probe ONVIF device - description: >- - Probe an ONVIF device to determine capabilities and optionally test - available stream URIs. Query params: host (required), port (default 80), - username, password, test (boolean), auth_type (basic or digest, default - basic). + description: |- + **Access:** Admin role required. + + Probe an ONVIF device to determine capabilities and optionally test available stream URIs. Query params: host (required), port (default 80), username, password, test (boolean), auth_type (basic or digest, default basic). operationId: onvif_probe_onvif_probe_get parameters: - name: host @@ -541,14 +600,14 @@ paths: required: false schema: type: string - default: "" + default: '' title: Username - name: password in: query required: false schema: type: string - default: "" + default: '' title: Password - name: test in: query @@ -565,23 +624,28 @@ paths: default: basic title: Auth Type responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/cameras/{camera_name}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /cameras/{camera_name}: delete: tags: - Camera summary: Delete Camera description: |- + **Access:** Admin role required. + Delete a camera and all its associated data. Removes the camera from config, stops processes, and cleans up @@ -606,24 +670,31 @@ paths: default: false title: Delete Exports responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/camera/{camera_name}/set/{feature}/{sub_command}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /camera/{camera_name}/set/{feature}/{sub_command}: put: tags: - Camera summary: Camera Set - description: Set a camera feature state. Use camera_name='*' to target all cameras. - operationId: camera_set_camera__camera_name__set__feature___sub_command__put + description: |- + **Access:** Admin role required. + + Set a camera feature state. Use camera_name='*' to target all cameras. + operationId: + camera_set_camera__camera_name__set__feature___sub_command__put parameters: - name: camera_name in: path @@ -643,32 +714,38 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Sub Command requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/CameraSetBody" + $ref: '#/components/schemas/CameraSetBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/camera/{camera_name}/set/{feature}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /camera/{camera_name}/set/{feature}: put: tags: - Camera summary: Camera Set - description: Set a camera feature state. Use camera_name='*' to target all cameras. + description: |- + **Access:** Admin role required. + + Set a camera feature state. Use camera_name='*' to target all cameras. operationId: camera_set_camera__camera_name__set__feature__put parameters: - name: camera_name @@ -689,116 +766,208 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Sub Command requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/CameraSetBody" + $ref: '#/components/schemas/CameraSetBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /chat/tools: get: tags: - Chat summary: Get available tools - description: Returns OpenAI-compatible tool definitions for function calling. + description: |- + **Access:** Admin role required. + + Returns OpenAI-compatible tool definitions for function calling. operationId: get_tools_chat_tools_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin /chat/execute: post: tags: - Chat summary: Execute a tool - description: Execute a tool function call from an LLM. + description: |- + **Access:** Admin role required. + + Execute a tool function call from an LLM. operationId: execute_tool_chat_execute_post requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/ToolExecuteRequest" + $ref: '#/components/schemas/ToolExecuteRequest' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /chat/completion: post: tags: - Chat summary: Chat completion with tool calling - description: >- - Send a chat message to the configured GenAI provider with tool calling - support. The LLM can call Frigate tools to answer questions about your - cameras and events. + description: |- + **Access:** Admin role required. + + Send a chat message to the configured GenAI provider with tool calling support. The LLM can call Frigate tools to answer questions about your cameras and events. operationId: chat_completion_chat_completion_post requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/ChatCompletionRequest" + $ref: '#/components/schemas/ChatCompletionRequest' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /vlm/monitor: + post: + tags: + - Chat + summary: Start a VLM watch job + description: |- + **Access:** Admin role required. + + Start monitoring a camera with the vision provider. The VLM analyzes live frames until the specified condition is met, then sends a notification. Only one watch job can run at a time. + operationId: start_vlm_monitor_vlm_monitor_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/VLMMonitorRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + get: + tags: + - Chat + summary: Get current VLM watch job + description: |- + **Access:** Admin role required. + + Returns the current (or most recently completed) VLM watch job. + operationId: get_vlm_monitor_vlm_monitor_get + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin + delete: + tags: + - Chat + summary: Cancel the current VLM watch job + description: |- + **Access:** Admin role required. + + Cancels the running watch job if one exists. + operationId: cancel_vlm_monitor_vlm_monitor_delete + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin /faces: get: tags: - Classification summary: Get all registered faces description: |- + **Access:** Admin role required. + Returns a dictionary mapping face names to lists of image filenames. Each key represents a registered face name, and the value is a list of image files associated with that face. Supported image formats include .webp, .png, .jpg, and .jpeg. operationId: get_faces_faces_get responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/FacesResponse" + $ref: '#/components/schemas/FacesResponse' + security: + - frigateAdminAuth: [] + x-required-role: admin /faces/reprocess: post: tags: - Classification summary: Reprocess a face training image description: |- + **Access:** Admin role required. + Reprocesses a face training image to update the prediction. Requires face recognition to be enabled in the configuration. The training file must exist in the faces/train directory. Returns a success response or an error @@ -811,23 +980,28 @@ paths: type: object title: Body responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/faces/train/{name}/classify": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /faces/train/{name}/classify: post: tags: - Classification summary: Classify and save a face training image description: |- + **Access:** Admin role required. + Adds a training image to a specific face name for face recognition. Accepts either a training file from the train directory or an event_id to extract the face from. The image is saved to the face's directory and the face classifier @@ -849,24 +1023,29 @@ paths: type: object title: Body responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/faces/{name}/create": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /faces/{name}/create: post: tags: - Classification summary: Create a new face name description: |- + **Access:** Admin role required. + Creates a new folder for a face name in the faces directory. This is used to organize face training images. The face name is sanitized and spaces are replaced with underscores. Returns a success message or an error if @@ -880,26 +1059,30 @@ paths: type: string title: Name responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/faces/{name}/register": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /faces/{name}/register: post: tags: - Classification summary: Register a face image - description: >- - Registers a face image for a specific face name by uploading an image - file. + description: |- + **Access:** Admin role required. + + Registers a face image for a specific face name by uploading an image file. The uploaded image is processed and added to the face recognition system. Returns a success response with details about the registration, or an error if face recognition is not enabled or the image cannot be processed. @@ -916,27 +1099,31 @@ paths: content: multipart/form-data: schema: - $ref: >- - #/components/schemas/Body_register_face_faces__name__register_post + $ref: '#/components/schemas/Body_register_face_faces__name__register_post' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /faces/recognize: post: tags: - Classification summary: Recognize a face from an uploaded image description: |- + **Access:** Admin role required. + Recognizes a face from an uploaded image file by comparing it against registered faces in the system. Returns the recognized face name and confidence score, or an error if face recognition is not enabled or the image cannot be processed. @@ -946,28 +1133,74 @@ paths: content: multipart/form-data: schema: - $ref: "#/components/schemas/Body_recognize_face_faces_recognize_post" + $ref: '#/components/schemas/Body_recognize_face_faces_recognize_post' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/FaceRecognitionResponse" - "422": + $ref: '#/components/schemas/FaceRecognitionResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/faces/{name}/delete": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /faces/{name}/reclassify: + post: + tags: + - Classification + summary: Reclassify a face image to a different name + description: |- + **Access:** Admin role required. + + Moves a single face image from one person's folder to another. + The image is moved and renamed, and the face classifier is cleared to + incorporate the change. Returns a success message or an error if the + image or target name is invalid. + operationId: reclassify_face_image_faces__name__reclassify_post + parameters: + - name: name + in: path + required: true + schema: + type: string + title: Name + requestBody: + content: + application/json: + schema: + type: object + title: Body + 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' + security: + - frigateAdminAuth: [] + x-required-role: admin + /faces/{name}/delete: post: tags: - Classification summary: Delete face images - description: >- - Deletes specific face images for a given face name. The image IDs must - belong + description: |- + **Access:** Admin role required. + + Deletes specific face images for a given face name. The image IDs must belong to the specified face folder. To delete an entire face folder, all image IDs in that folder must be sent. Returns a success message or an error if face recognition is not enabled. operationId: deregister_faces_faces__name__delete_post @@ -983,26 +1216,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/DeleteFaceImagesBody" + $ref: '#/components/schemas/DeleteFaceImagesBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/faces/{old_name}/rename": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /faces/{old_name}/rename: put: tags: - Classification summary: Rename a face name description: |- + **Access:** Admin role required. + Renames a face name in the system. The old name must exist and the new name must be valid. Returns a success message or an error if face recognition is not enabled. operationId: rename_face_faces__old_name__rename_put @@ -1018,26 +1256,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/RenameFaceBody" + $ref: '#/components/schemas/RenameFaceBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /lpr/reprocess: put: tags: - Classification summary: Reprocess a license plate description: |- + **Access:** Admin role required. + Reprocesses a license plate image to update the plate. Requires license plate recognition to be enabled in the configuration. The event_id must exist in the database. Returns a success message or an error if license plate @@ -1051,39 +1294,49 @@ paths: type: string title: Event Id responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /reindex: put: tags: - Classification summary: Reindex embeddings description: |- + **Access:** Admin role required. + Reindexes the embeddings for all tracked objects. Requires semantic search to be enabled in the configuration. Returns a success message or an error if semantic search is not enabled. operationId: reindex_embeddings_reindex_put responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" + $ref: '#/components/schemas/GenericResponse' + security: + - frigateAdminAuth: [] + x-required-role: admin /audio/transcribe: put: tags: - Classification summary: Transcribe audio description: |- + **Access:** Admin role required. + Transcribes audio from a specific event. Requires audio transcription to be enabled in the configuration. The event_id must exist in the database. Returns a success message or an error if audio transcription is not enabled or the event_id is invalid. @@ -1093,26 +1346,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AudioTranscriptionBody" + $ref: '#/components/schemas/AudioTranscriptionBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/classification/{name}/dataset": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /classification/{name}/dataset: get: tags: - Classification summary: Get classification dataset description: |- + **Access:** Admin role required. + Gets the dataset for a specific classification model. The name must exist in the classification models. Returns a success message or an error if the name is invalid. operationId: get_classification_dataset_classification__name__dataset_get @@ -1124,23 +1382,28 @@ paths: type: string title: Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /classification/attributes: get: tags: - Classification summary: Get custom classification attributes description: |- + **Access:** Admin role required. + Returns custom classification attributes for a given object type. Only includes models with classification_type set to 'attribute'. By default returns a flat sorted list of all attribute labels. @@ -1161,23 +1424,28 @@ paths: default: false title: Group By Model responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/classification/{name}/train": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /classification/{name}/train: get: tags: - Classification summary: Get classification train images description: |- + **Access:** Admin role required. + Gets the train images for a specific classification model. The name must exist in the classification models. Returns a success message or an error if the name is invalid. operationId: get_classification_images_classification__name__train_get @@ -1189,22 +1457,27 @@ paths: type: string title: Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin post: tags: - Classification summary: Train a classification model description: |- + **Access:** Admin role required. + Trains a specific classification model. The name must exist in the classification models. Returns a success message or an error if the name is invalid. operationId: train_configured_model_classification__name__train_post @@ -1216,28 +1489,32 @@ paths: type: string title: Name responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/classification/{name}/dataset/{category}/delete": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /classification/{name}/dataset/{category}/delete: post: tags: - Classification summary: Delete classification dataset images - description: >- - Deletes specific dataset images for a given classification model and - category. + description: |- + **Access:** Admin role required. + + Deletes specific dataset images for a given classification model and category. The image IDs must belong to the specified category. Returns a success message or an error if the name or category is invalid. - operationId: >- + operationId: delete_classification_dataset_images_classification__name__dataset__category__delete_post parameters: - name: name @@ -1259,27 +1536,79 @@ paths: type: object title: Body responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/classification/{name}/dataset/{old_category}/rename": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /classification/{name}/dataset/{category}/reclassify: + post: + tags: + - Classification + summary: Reclassify a dataset image to a different category + description: |- + **Access:** Admin role required. + + Moves a single dataset image from one category to another. + The image is re-saved as PNG in the target category and removed from the source. + operationId: + reclassify_classification_image_classification__name__dataset__category__reclassify_post + parameters: + - name: name + in: path + required: true + schema: + type: string + title: Name + - name: category + in: path + required: true + schema: + type: string + title: Category + requestBody: + content: + application/json: + schema: + type: object + title: Body + 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' + security: + - frigateAdminAuth: [] + x-required-role: admin + /classification/{name}/dataset/{old_category}/rename: put: tags: - Classification summary: Rename a classification category description: |- + **Access:** Admin role required. + Renames a classification category for a given classification model. The old category must exist and the new name must be valid. Returns a success message or an error if the name is invalid. - operationId: >- + operationId: rename_classification_category_classification__name__dataset__old_category__rename_put parameters: - name: name @@ -1301,28 +1630,32 @@ paths: type: object title: Body responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/classification/{name}/dataset/categorize": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /classification/{name}/dataset/categorize: post: tags: - Classification summary: Categorize a classification image - description: >- - Categorizes a specific classification image for a given classification - model and category. + description: |- + **Access:** Admin role required. + + Categorizes a specific classification image for a given classification model and category. The image must exist in the specified category. Returns a success message or an error if the name or category is invalid. - operationId: >- + operationId: categorize_classification_image_classification__name__dataset_categorize_post parameters: - name: name @@ -1338,28 +1671,33 @@ paths: type: object title: Body responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/classification/{name}/dataset/{category}/create": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /classification/{name}/dataset/{category}/create: post: tags: - Classification summary: Create an empty classification category folder description: |- + **Access:** Admin role required. + Creates an empty folder for a classification category. This is used to create folders for categories that don't have images yet. Returns a success message or an error if the name is invalid. - operationId: >- + operationId: create_classification_category_classification__name__dataset__category__create_post parameters: - name: name @@ -1375,27 +1713,32 @@ paths: type: string title: Category responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/classification/{name}/train/delete": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /classification/{name}/train/delete: post: tags: - Classification summary: Delete classification train images description: |- + **Access:** Admin role required. + Deletes specific train images for a given classification model. The image IDs must belong to the specified train folder. Returns a success message or an error if the name is invalid. - operationId: >- + operationId: delete_classification_train_images_classification__name__train_delete_post parameters: - name: name @@ -1411,76 +1754,95 @@ paths: type: object title: Body responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /classification/generate_examples/state: post: tags: - Classification summary: Generate state classification examples - description: Generate examples for state classification. - operationId: generate_state_examples_classification_generate_examples_state_post + description: |- + **Access:** Admin role required. + + Generate examples for state classification. + operationId: + generate_state_examples_classification_generate_examples_state_post requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/GenerateStateExamplesBody" + $ref: '#/components/schemas/GenerateStateExamplesBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /classification/generate_examples/object: post: tags: - Classification summary: Generate object classification examples - description: Generate examples for object classification. - operationId: generate_object_examples_classification_generate_examples_object_post + description: |- + **Access:** Admin role required. + + Generate examples for object classification. + operationId: + generate_object_examples_classification_generate_examples_object_post requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/GenerateObjectExamplesBody" + $ref: '#/components/schemas/GenerateObjectExamplesBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/classification/{name}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /classification/{name}: delete: tags: - Classification summary: Delete a classification model description: |- + **Access:** Admin role required. + Deletes a specific classification model and all its associated data. Works even if the model is not in the config (e.g., partially created during wizard). Returns a success message. @@ -1493,18 +1855,21 @@ paths: type: string title: Name responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /review: get: tags: @@ -1549,7 +1914,7 @@ paths: in: query required: false schema: - $ref: "#/components/schemas/SeverityEnum" + $ref: '#/components/schemas/SeverityEnum' - name: before in: query required: false @@ -1563,21 +1928,25 @@ paths: type: number title: After responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/ReviewSegmentResponse" + $ref: '#/components/schemas/ReviewSegmentResponse' title: Response Review Review Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /review_ids: get: tags: @@ -1592,21 +1961,25 @@ paths: type: string title: Ids responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/ReviewSegmentResponse" + $ref: '#/components/schemas/ReviewSegmentResponse' title: Response Review Ids Review Ids Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' /review/summary: get: tags: @@ -1643,18 +2016,22 @@ paths: default: utc title: Timezone responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/ReviewSummaryResponse" - "422": + $ref: '#/components/schemas/ReviewSummaryResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /reviews/viewed: post: tags: @@ -1666,20 +2043,24 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ReviewModifyMultipleBody" + $ref: '#/components/schemas/ReviewModifyMultipleBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' /reviews/delete: post: tags: @@ -1691,26 +2072,33 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ReviewModifyMultipleBody" + $ref: '#/components/schemas/ReviewModifyMultipleBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + description: '**Access:** Admin role required.' /review/activity/motion: get: tags: - Review summary: Motion Activity - description: Get motion and audio activity. + description: |- + **Access:** Any authenticated user. + + Get motion and audio activity. operationId: motion_activity_review_activity_motion_get parameters: - name: cameras @@ -1740,22 +2128,25 @@ paths: default: 30 title: Scale responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/ReviewActivityMotionResponse" + $ref: '#/components/schemas/ReviewActivityMotionResponse' title: Response Motion Activity Review Activity Motion Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/review/event/{event_id}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + /review/event/{event_id}: get: tags: - Review @@ -1769,19 +2160,23 @@ paths: type: string title: Event Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/ReviewSegmentResponse" - "422": + $ref: '#/components/schemas/ReviewSegmentResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/review/{review_id}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /review/{review_id}: get: tags: - Review @@ -1795,19 +2190,23 @@ paths: type: string title: Review Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/ReviewSegmentResponse" - "422": + $ref: '#/components/schemas/ReviewSegmentResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/review/{review_id}/viewed": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /review/{review_id}/viewed: delete: tags: - Review @@ -1821,25 +2220,32 @@ paths: type: string title: Review Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/review/summarize/start/{start_ts}/end/{end_ts}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' + /review/summarize/start/{start_ts}/end/{end_ts}: post: tags: - Review summary: Generate Review Summary - description: Use GenAI to summarize review items over a period of time. - operationId: >- + description: |- + **Access:** Admin role required. + + Use GenAI to summarize review items over a period of time. + operationId: generate_review_summary_review_summarize_start__start_ts__end__end_ts__post parameters: - name: start_ts @@ -1855,17 +2261,20 @@ paths: type: number title: End Ts responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /: get: tags: @@ -1873,12 +2282,15 @@ paths: summary: Is Healthy operationId: is_healthy__get responses: - "200": + '200': description: Successful Response content: text/plain: schema: type: string + security: [] + x-required-role: public + description: '**Access:** Public — no authentication required.' /config/schema.json: get: tags: @@ -1886,11 +2298,14 @@ paths: summary: Config Schema operationId: config_schema_config_schema_json_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: [] + x-required-role: public + description: '**Access:** Public — no authentication required.' /version: get: tags: @@ -1898,12 +2313,15 @@ paths: summary: Version operationId: version_version_get responses: - "200": + '200': description: Successful Response content: text/plain: schema: type: string + security: [] + x-required-role: public + description: '**Access:** Public — no authentication required.' /stats: get: tags: @@ -1911,11 +2329,15 @@ paths: summary: Stats operationId: stats_stats_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /stats/history: get: tags: @@ -1930,30 +2352,90 @@ paths: type: string title: Keys responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + description: '**Access:** Admin role required.' /metrics: get: tags: - App summary: Metrics - description: Expose Prometheus metrics endpoint and update metrics with latest stats + description: |- + **Access:** Any authenticated user. + + Expose Prometheus metrics endpoint and update metrics with latest stats operationId: metrics_metrics_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateUserAuth: [] + x-required-role: any + /genai/models: + get: + tags: + - App + summary: List available GenAI models + description: |- + **Access:** Admin role required. + + Returns available models for each configured GenAI provider. + operationId: genai_models_genai_models_get + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin + /genai/probe: + post: + tags: + - App + summary: Probe a GenAI provider without saving config + description: |- + **Access:** Admin role required. + + Builds a transient client from the request body and returns its available models. Used to validate provider credentials in the UI before saving the configuration. + operationId: genai_probe_genai_probe_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GenAIProbeBody' + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /config: get: tags: @@ -1961,65 +2443,91 @@ paths: summary: Config operationId: config_config_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /profiles: get: tags: - App summary: Get Profiles - description: List all available profiles and the currently active profile. + description: |- + **Access:** Any authenticated user. + + List all available profiles and the currently active profile. operationId: get_profiles_profiles_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateUserAuth: [] + x-required-role: any /profile/active: get: tags: - App summary: Get Active Profile - description: Get the currently active profile. + description: |- + **Access:** Admin role required. + + Get the currently active profile. operationId: get_active_profile_profile_active_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin /ffmpeg/presets: get: tags: - App summary: Ffmpeg Presets - description: Return available ffmpeg preset keys for config UI usage. + description: |- + **Access:** Admin role required. + + Return available ffmpeg preset keys for config UI usage. operationId: ffmpeg_presets_ffmpeg_presets_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin /config/raw_paths: get: tags: - App summary: Config Raw Paths - description: >- - Admin-only endpoint that returns camera paths and go2rtc streams without - credential masking. + description: |- + **Access:** Admin role required. + + Admin-only endpoint that returns camera paths and go2rtc streams without credential masking. operationId: config_raw_paths_config_raw_paths_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin /config/raw: get: tags: @@ -2027,11 +2535,15 @@ paths: summary: Config Raw operationId: config_raw_config_raw_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin + description: '**Access:** Admin role required.' /config/save: post: tags: @@ -2052,17 +2564,21 @@ paths: schema: title: Body responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + description: '**Access:** Admin role required.' /config/set: put: tags: @@ -2074,60 +2590,23 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AppConfigSetBody" + $ref: '#/components/schemas/AppConfigSetBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - /genai/models: - get: - tags: - - App - summary: List available GenAI models - description: Returns available models for each configured GenAI provider. - operationId: genai_models_genai_models_get - responses: - "200": - description: Successful Response - content: - application/json: - schema: {} - /genai/probe: - post: - tags: - - App - summary: Probe a GenAI provider without saving config - description: >- - Builds a transient client from the request body and returns its - available models. Used to validate provider credentials in the UI - before saving the configuration. Requires admin role. - operationId: genai_probe_genai_probe_post - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GenAIProbeBody" - responses: - "200": - description: Successful Response - content: - application/json: - schema: {} - "422": - description: Validation Error - content: - application/json: - schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + description: '**Access:** Admin role required.' /vainfo: get: tags: @@ -2135,11 +2614,15 @@ paths: summary: Vainfo operationId: vainfo_vainfo_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /nvinfo: get: tags: @@ -2147,18 +2630,25 @@ paths: summary: Nvinfo operationId: nvinfo_nvinfo_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "/logs/{service}": + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' + /logs/{service}: get: tags: - App - Logs summary: Logs - description: Get logs for the requested service (frigate/nginx/go2rtc) + description: |- + **Access:** Admin role required. + + Get logs for the requested service (frigate/nginx/go2rtc) operationId: logs_logs__service__get parameters: - name: service @@ -2177,7 +2667,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Download - name: stream in: query @@ -2185,7 +2675,7 @@ paths: schema: anyOf: - type: boolean - - type: "null" + - type: 'null' default: false title: Stream - name: start @@ -2194,7 +2684,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' default: 0 title: Start - name: end @@ -2203,20 +2693,23 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: End responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /restart: post: tags: @@ -2224,19 +2717,24 @@ paths: summary: Restart operationId: restart_restart_post responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin + description: '**Access:** Admin role required.' /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. + description: |- + **Access:** Admin role required. + + 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: @@ -2244,43 +2742,51 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/MediaSyncBody" + $ref: '#/components/schemas/MediaSyncBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /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 + description: |- + **Access:** Admin role required. + + 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": + '200': description: Successful Response content: application/json: schema: {} - "/media/sync/status/{job_id}": + security: + - frigateAdminAuth: [] + x-required-role: admin + /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 + description: |- + **Access:** Admin role required. + + 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: @@ -2291,17 +2797,20 @@ paths: type: string title: Job Id responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /labels: get: tags: @@ -2314,20 +2823,24 @@ paths: required: false schema: type: string - default: "" + default: '' title: Camera responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /sub_labels: get: tags: @@ -2341,20 +2854,24 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Split Joined responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /audio_labels: get: tags: @@ -2362,11 +2879,15 @@ paths: summary: Get Audio Labels operationId: get_audio_labels_audio_labels_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin + description: '**Access:** Admin role required.' /plus/models: get: tags: @@ -2382,17 +2903,21 @@ paths: default: false title: Filterbycurrentmodeldetector responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /recognized_license_plates: get: tags: @@ -2406,20 +2931,24 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Split Joined responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /timeline: get: tags: @@ -2447,26 +2976,33 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Source Id responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' /timeline/hourly: get: tags: - App summary: Hourly Timeline - description: Get hourly summary for timeline. + description: |- + **Access:** Any authenticated user. + + Get hourly summary for timeline. operationId: hourly_timeline_timeline_hourly_get parameters: - name: cameras @@ -2475,7 +3011,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Cameras - name: labels @@ -2484,7 +3020,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Labels - name: after @@ -2493,7 +3029,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: After - name: before in: query @@ -2501,7 +3037,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Before - name: limit in: query @@ -2509,7 +3045,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' default: 200 title: Limit - name: timezone @@ -2518,32 +3054,38 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: utc title: Timezone responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/preview/{camera_name}/start/{start_ts}/end/{end_ts}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + /preview/{camera_name}/start/{start_ts}/end/{end_ts}: get: tags: - Preview summary: Get preview clips for time range description: |- + **Access:** Any authenticated user. + Gets all preview clips for a specified camera and time range. Returns a list of preview video clips that overlap with the requested time period, ordered by start time. Use camera_name='all' to get previews from all cameras. Returns an error if no previews are found. - operationId: preview_ts_preview__camera_name__start__start_ts__end__end_ts__get + operationId: + preview_ts_preview__camera_name__start__start_ts__end__end_ts__get parameters: - name: camera_name in: path @@ -2564,34 +3106,38 @@ paths: type: number title: End Ts responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/PreviewModel" - title: >- - Response Preview Ts Preview Camera Name Start Start Ts + $ref: '#/components/schemas/PreviewModel' + title: Response Preview Ts Preview Camera Name Start Start Ts End End Ts Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/preview/{year_month}/{day}/{hour}/{camera_name}/{tz_name}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + /preview/{year_month}/{day}/{hour}/{camera_name}/{tz_name}: get: tags: - Preview summary: Get preview clips for specific hour description: |- + **Access:** Any authenticated user. + Gets all preview clips for a specific hour in a given timezone. Converts the provided date/time from the specified timezone to UTC and retrieves all preview clips for that hour. Use camera_name='all' to get previews from all cameras. The tz_name should be a timezone like 'America/New_York' (use commas instead of slashes). - operationId: >- + operationId: preview_hour_preview__year_month___day___hour___camera_name___tz_name__get parameters: - name: year_month @@ -2625,34 +3171,37 @@ paths: type: string title: Tz Name responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/PreviewModel" - title: >- - Response Preview Hour Preview Year Month Day Hour + $ref: '#/components/schemas/PreviewModel' + title: Response Preview Hour Preview Year Month Day Hour Camera Name Tz Name Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/preview/{camera_name}/start/{start_ts}/end/{end_ts}/frames": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + /preview/{camera_name}/start/{start_ts}/end/{end_ts}/frames: get: tags: - Preview summary: Get cached preview frame filenames - description: >- - Gets a list of cached preview frame filenames for a specific camera and - time range. + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Gets a list of cached preview frame filenames for a specific camera and time range. Returns an array of filenames for preview frames that fall within the specified time period, sorted in chronological order. These are individual frame images cached for quick preview display. - operationId: >- + operationId: get_preview_frames_from_cache_preview__camera_name__start__start_ts__end__end_ts__frames_get parameters: - name: camera_name @@ -2661,7 +3210,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: start_ts in: path @@ -2676,7 +3225,7 @@ paths: type: number title: End Ts responses: - "200": + '200': description: Successful Response content: application/json: @@ -2684,36 +3233,45 @@ paths: type: array items: type: string - title: >- - Response Get Preview Frames From Cache Preview Camera Name - Start Start Ts End End Ts Frames Get - "422": + title: Response Get Preview Frames From Cache Preview Camera + Name Start Start Ts End End Ts Frames Get + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera /notifications/pubkey: get: tags: - Notifications summary: Get VAPID public key description: |- + **Access:** Any authenticated user. + Gets the VAPID public key for the notifications. Returns the public key or an error if notifications are not enabled. operationId: get_vapid_pub_key_notifications_pubkey_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateUserAuth: [] + x-required-role: any /notifications/register: post: tags: - Notifications summary: Register notifications description: |- + **Access:** Any authenticated user. + Registers a notifications subscription. Returns a success message or an error if the subscription is not provided. operationId: register_notifications_notifications_register_post @@ -2724,23 +3282,28 @@ paths: type: object title: Body responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any /exports: get: tags: - Export summary: Get exports description: |- + **Access:** Any authenticated user. + Gets all exports from the database for cameras the user has access to. Returns a list of exports ordered by date (most recent first). operationId: get_exports_exports_get @@ -2751,7 +3314,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Export Case Id - name: cameras in: query @@ -2759,7 +3322,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Cameras - name: start_date @@ -2768,7 +3331,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Start Date - name: end_date in: query @@ -2776,201 +3339,90 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: End Date responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/ExportModel" + $ref: '#/components/schemas/ExportModel' title: Response Get Exports Exports Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - /exports/batch: - post: - tags: - - Export - summary: Start recording export batch - description: >- - Starts recording exports for a batch of items, each with its own camera - and time range. Optionally assigns them to a new or existing export case. - When neither export_case_id nor new_case_name is provided, exports are - added as uncategorized. Attaching to an existing case is admin-only. - operationId: export_recordings_batch_exports_batch_post - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/BatchExportBody" - responses: - "202": - description: Successful Response - content: - application/json: - schema: - $ref: "#/components/schemas/BatchExportResponse" - "400": - description: Bad Request - content: - application/json: - schema: - $ref: "#/components/schemas/GenericResponse" - "403": - description: Forbidden - content: - application/json: - schema: - $ref: "#/components/schemas/GenericResponse" - "404": - description: Not Found - content: - application/json: - schema: - $ref: "#/components/schemas/GenericResponse" - "503": - description: Service Unavailable - content: - application/json: - schema: - $ref: "#/components/schemas/GenericResponse" - "422": - description: Validation Error - content: - application/json: - schema: - $ref: "#/components/schemas/HTTPValidationError" - /exports/delete: - post: - tags: - - Export - summary: Bulk delete exports - description: >- - Deletes one or more exports by ID. All IDs must exist and none can be - in-progress. Admin-only. - operationId: bulk_delete_exports_exports_delete_post - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ExportBulkDeleteBody" - responses: - "200": - description: Successful Response - content: - application/json: - schema: - $ref: "#/components/schemas/GenericResponse" - "400": - description: Bad Request - one or more exports are in-progress - content: - application/json: - schema: - $ref: "#/components/schemas/GenericResponse" - "404": - description: Not Found - one or more export IDs do not exist - content: - application/json: - schema: - $ref: "#/components/schemas/GenericResponse" - "422": - description: Validation Error - content: - application/json: - schema: - $ref: "#/components/schemas/HTTPValidationError" - /exports/reassign: - post: - tags: - - Export - summary: Bulk reassign exports to a case - description: >- - Assigns or unassigns one or more exports to/from a case. All IDs must - exist. Pass export_case_id as null to unassign (move to uncategorized). - Admin-only. - operationId: bulk_reassign_exports_exports_reassign_post - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ExportBulkReassignBody" - responses: - "200": - description: Successful Response - content: - application/json: - schema: - $ref: "#/components/schemas/GenericResponse" - "404": - description: Not Found - one or more export IDs or the target case do not exist - content: - application/json: - schema: - $ref: "#/components/schemas/GenericResponse" - "422": - description: Validation Error - content: - application/json: - schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any /cases: get: tags: - Export summary: Get export cases - description: Gets all export cases from the database. + description: |- + **Access:** Any authenticated user. + + Gets all export cases from the database. operationId: get_export_cases_cases_get responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/ExportCaseModel" + $ref: '#/components/schemas/ExportCaseModel' title: Response Get Export Cases Cases Get + security: + - frigateUserAuth: [] + x-required-role: any post: tags: - Export summary: Create export case - description: Creates a new export case. + description: |- + **Access:** Admin role required. + + Creates a new export case. operationId: create_export_case_cases_post requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/ExportCaseCreateBody" + $ref: '#/components/schemas/ExportCaseCreateBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/ExportCaseModel" - "422": + $ref: '#/components/schemas/ExportCaseModel' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/cases/{case_id}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /cases/{case_id}: get: tags: - Export summary: Get a single export case - description: Gets a specific export case by ID. + description: |- + **Access:** Any authenticated user. + + Gets a specific export case by ID. operationId: get_export_case_cases__case_id__get parameters: - name: case_id @@ -2980,23 +3432,29 @@ paths: type: string title: Case Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/ExportCaseModel" - "422": + $ref: '#/components/schemas/ExportCaseModel' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any patch: tags: - Export summary: Update export case - description: Updates an existing export case. + description: |- + **Access:** Admin role required. + + Updates an existing export case. operationId: update_export_case_cases__case_id__patch parameters: - name: case_id @@ -3010,25 +3468,30 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ExportCaseUpdateBody" + $ref: '#/components/schemas/ExportCaseUpdateBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin delete: tags: - Export summary: Delete export case description: |- + **Access:** Admin role required. + Deletes an export case. Exports that reference this case will have their export_case set to null. operationId: delete_export_case_cases__case_id__delete @@ -3039,30 +3502,162 @@ paths: schema: type: string title: Case Id + - name: delete_exports + in: query + required: false + schema: + type: boolean + default: false + title: Delete Exports responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/export/{camera_name}/start/{start_time}/end/{end_time}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /cases/{case_id}/download: + get: + tags: + - Export + summary: Download export case as zip + description: |- + **Access:** Any authenticated user. + + Streams a zip archive containing every completed export's mp4 for the given case. + operationId: download_export_case_cases__case_id__download_get + parameters: + - name: case_id + in: path + required: true + schema: + type: string + title: Case Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + /jobs/export: + get: + tags: + - Export + summary: Get active export jobs + description: |- + **Access:** Any authenticated user. + + Gets queued and running export jobs. + operationId: get_active_export_jobs_jobs_export_get + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ExportJobModel' + title: Response Get Active Export Jobs Jobs Export Get + security: + - frigateUserAuth: [] + x-required-role: any + /jobs/export/{export_id}: + get: + tags: + - Export + summary: Get export job status + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Gets queued, running, or completed status for a specific export job. + operationId: get_export_job_status_jobs_export__export_id__get + parameters: + - name: export_id + in: path + required: true + schema: + type: string + title: Export Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ExportJobModel' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /exports/batch: + post: + tags: + - Export + summary: Start recording export batch + description: |- + **Access:** Any authenticated user. + + Starts recording exports for a batch of items, each with its own camera and time range, and assigns them to a single export case. Attaching to an existing case is temporarily admin-only until case-level ACLs exist. + operationId: export_recordings_batch_exports_batch_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BatchExportBody' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/BatchExportResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + /export/{camera_name}/start/{start_time}/end/{end_time}: post: tags: - Export summary: Start recording export description: |- + **Access:** Authenticated user with access to the referenced camera. + Starts an export of a recording for the specified time range. The export can be from recordings or preview footage. Returns the export ID if successful, or an error message if the camera is invalid or no recordings/previews are found for the time range. - operationId: >- + operationId: export_recording_export__camera_name__start__start_time__end__end_time__post parameters: - name: camera_name @@ -3071,7 +3666,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: start_time in: path @@ -3090,26 +3685,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ExportRecordingsBody" + $ref: '#/components/schemas/ExportRecordingsBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/StartExportResponse" - "422": + $ref: '#/components/schemas/StartExportResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/export/{event_id}/rename": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /export/{event_id}/rename: patch: tags: - Export summary: Rename export description: |- + **Access:** Admin role required. + Renames an export. NOTE: This changes the friendly name of the export, not the filename. operationId: export_rename_export__event_id__rename_patch @@ -3125,33 +3725,37 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ExportRenameBody" + $ref: '#/components/schemas/ExportRenameBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/export/custom/{camera_name}/start/{start_time}/end/{end_time}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /export/custom/{camera_name}/start/{start_time}/end/{end_time}: post: tags: - Export summary: Start custom recording export - description: >- - Starts an export of a recording for the specified time range using - custom FFmpeg arguments. + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Starts an export of a recording for the specified time range using custom FFmpeg arguments. The export can be from recordings or preview footage. Returns the export ID if successful, or an error message if the camera is invalid or no recordings/previews are found for the time range. If ffmpeg_input_args and ffmpeg_output_args are not provided, defaults to timelapse export settings. - operationId: >- + operationId: export_recording_custom_export_custom__camera_name__start__start_time__end__end_time__post parameters: - name: camera_name @@ -3160,7 +3764,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: start_time in: path @@ -3179,26 +3783,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ExportRecordingsCustomBody" + $ref: '#/components/schemas/ExportRecordingsCustomBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/StartExportResponse" - "422": + $ref: '#/components/schemas/StartExportResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/exports/{export_id}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /exports/{export_id}: get: tags: - Export summary: Get a single export description: |- + **Access:** Authenticated user with access to the referenced camera. + Gets a specific export by ID. The user must have access to the camera associated with the export. operationId: get_export_exports__export_id__get @@ -3210,24 +3819,94 @@ paths: type: string title: Export Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/ExportModel" - "422": + $ref: '#/components/schemas/ExportModel' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /exports/delete: + post: + tags: + - Export + summary: Bulk delete exports + description: |- + **Access:** Admin role required. + + Deletes one or more exports by ID. All IDs must exist and none can be in-progress. + operationId: bulk_delete_exports_exports_delete_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ExportBulkDeleteBody' + 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' + security: + - frigateAdminAuth: [] + x-required-role: admin + /exports/reassign: + post: + tags: + - Export + summary: Bulk reassign exports to a case + description: |- + **Access:** Admin role required. + + Assigns or unassigns one or more exports to/from a case. All IDs must exist. + operationId: bulk_reassign_exports_exports_reassign_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ExportBulkReassignBody' + 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' + security: + - frigateAdminAuth: [] + x-required-role: admin /events: get: tags: - Events summary: Get events - description: Returns a list of events. + description: |- + **Access:** Any authenticated user. + + Returns a list of events. operationId: events_events_get parameters: - name: camera @@ -3236,7 +3915,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Camera - name: cameras @@ -3245,7 +3924,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Cameras - name: label @@ -3254,7 +3933,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Label - name: labels @@ -3263,7 +3942,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Labels - name: sub_label @@ -3272,7 +3951,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Sub Label - name: sub_labels @@ -3281,7 +3960,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Sub Labels - name: attributes @@ -3290,7 +3969,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Attributes - name: zone @@ -3299,7 +3978,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Zone - name: zones @@ -3308,7 +3987,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Zones - name: limit @@ -3317,7 +3996,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' default: 100 title: Limit - name: after @@ -3326,7 +4005,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: After - name: before in: query @@ -3334,7 +4013,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Before - name: time_range in: query @@ -3342,8 +4021,8 @@ paths: schema: anyOf: - type: string - - type: "null" - default: "00:00,24:00" + - type: 'null' + default: 00:00,24:00 title: Time Range - name: has_clip in: query @@ -3351,7 +4030,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Has Clip - name: has_snapshot in: query @@ -3359,7 +4038,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Has Snapshot - name: in_progress in: query @@ -3367,7 +4046,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: In Progress - name: include_thumbnails in: query @@ -3375,7 +4054,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' default: 1 title: Include Thumbnails - name: favorites @@ -3384,7 +4063,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Favorites - name: min_score in: query @@ -3392,7 +4071,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Min Score - name: max_score in: query @@ -3400,7 +4079,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Max Score - name: min_speed in: query @@ -3408,7 +4087,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Min Speed - name: max_speed in: query @@ -3416,7 +4095,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Max Speed - name: recognized_license_plate in: query @@ -3424,7 +4103,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Recognized License Plate - name: is_submitted @@ -3433,7 +4112,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Is Submitted - name: min_length in: query @@ -3441,7 +4120,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Min Length - name: max_length in: query @@ -3449,7 +4128,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Max Length - name: event_id in: query @@ -3457,7 +4136,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Event Id - name: sort in: query @@ -3465,7 +4144,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Sort - name: timezone in: query @@ -3473,31 +4152,36 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: utc title: Timezone responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/EventResponse" + $ref: '#/components/schemas/EventResponse' title: Response Events Events Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any /events/explore: get: tags: - Events summary: Get summary of objects description: |- + **Access:** Any authenticated user. + Gets a summary of objects from the database. Returns a list of objects with a max of `limit` objects for each label. operationId: events_explore_events_explore_get @@ -3510,27 +4194,32 @@ paths: default: 10 title: Limit responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/EventResponse" + $ref: '#/components/schemas/EventResponse' title: Response Events Explore Events Explore Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any /event_ids: get: tags: - Events summary: Get events by ids description: |- + **Access:** Authenticated user with access to the referenced camera. + Gets events by a list of ids. Returns a list of events. operationId: event_ids_event_ids_get @@ -3542,27 +4231,32 @@ paths: type: string title: Ids responses: - "200": + '200': description: Successful Response content: application/json: schema: type: array items: - $ref: "#/components/schemas/EventResponse" + $ref: '#/components/schemas/EventResponse' title: Response Event Ids Event Ids Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera /events/search: get: tags: - Events summary: Search events description: |- + **Access:** Any authenticated user. + Searches for events in the database. Returns a list of events. operationId: events_search_events_search_get @@ -3573,7 +4267,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Query - name: event_id in: query @@ -3581,7 +4275,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Event Id - name: search_type in: query @@ -3589,7 +4283,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: thumbnail title: Search Type - name: include_thumbnails @@ -3598,7 +4292,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' default: 1 title: Include Thumbnails - name: limit @@ -3607,7 +4301,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' default: 50 title: Limit - name: cameras @@ -3616,7 +4310,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Cameras - name: labels @@ -3625,7 +4319,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Labels - name: sub_labels @@ -3634,7 +4328,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Sub Labels - name: attributes @@ -3643,7 +4337,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Attributes - name: zones @@ -3652,7 +4346,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Zones - name: after @@ -3661,7 +4355,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: After - name: before in: query @@ -3669,7 +4363,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Before - name: time_range in: query @@ -3677,8 +4371,8 @@ paths: schema: anyOf: - type: string - - type: "null" - default: "00:00,24:00" + - type: 'null' + default: 00:00,24:00 title: Time Range - name: has_clip in: query @@ -3686,7 +4380,7 @@ paths: schema: anyOf: - type: boolean - - type: "null" + - type: 'null' title: Has Clip - name: has_snapshot in: query @@ -3694,7 +4388,7 @@ paths: schema: anyOf: - type: boolean - - type: "null" + - type: 'null' title: Has Snapshot - name: is_submitted in: query @@ -3702,7 +4396,7 @@ paths: schema: anyOf: - type: boolean - - type: "null" + - type: 'null' title: Is Submitted - name: timezone in: query @@ -3710,7 +4404,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: utc title: Timezone - name: min_score @@ -3719,7 +4413,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Min Score - name: max_score in: query @@ -3727,7 +4421,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Max Score - name: min_speed in: query @@ -3735,7 +4429,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Min Speed - name: max_speed in: query @@ -3743,7 +4437,7 @@ paths: schema: anyOf: - type: number - - type: "null" + - type: 'null' title: Max Speed - name: recognized_license_plate in: query @@ -3751,7 +4445,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Recognized License Plate - name: sort @@ -3760,20 +4454,23 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Sort responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any /events/summary: get: tags: @@ -3787,7 +4484,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: utc title: Timezone - name: has_clip @@ -3796,7 +4493,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Has Clip - name: has_snapshot in: query @@ -3804,26 +4501,33 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Has Snapshot responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + description: '**Access:** Any authenticated user.' + /events/{event_id}: get: tags: - Events summary: Get event by id - description: Gets an event by its id. + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Gets an event by its id. operationId: event_events__event_id__get parameters: - name: event_id @@ -3833,23 +4537,28 @@ paths: type: string title: Event Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/EventResponse" - "422": + $ref: '#/components/schemas/EventResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera delete: tags: - Events summary: Delete event description: |- + **Access:** Admin role required. + Deletes an event from the database. Returns a success message or an error if the event is not found. operationId: delete_event_events__event_id__delete @@ -3861,24 +4570,29 @@ paths: type: string title: Event Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/retain": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/retain: post: tags: - Events summary: Set event retain indefinitely. description: |- + **Access:** Admin role required. + Sets an event to retain indefinitely. Returns a success message or an error if the event is not found. NOTE: This is a legacy endpoint and is not supported in the frontend. @@ -3891,23 +4605,28 @@ paths: type: string title: Event Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin delete: tags: - Events summary: Stop event from being retained indefinitely description: |- + **Access:** Admin role required. + Stops an event from being retained indefinitely. Returns a success message or an error if the event is not found. NOTE: This is a legacy endpoint and is not supported in the frontend. @@ -3920,24 +4639,29 @@ paths: type: string title: Event Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/plus": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/plus: post: tags: - Events summary: Send event to Frigate+ description: |- + **Access:** Admin role required. + Sends an event to Frigate+. Returns a success message or an error if the event is not found. operationId: send_to_plus_events__event_id__plus_post @@ -3952,26 +4676,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/SubmitPlusBody" + $ref: '#/components/schemas/SubmitPlusBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/EventUploadPlusResponse" - "422": + $ref: '#/components/schemas/EventUploadPlusResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/false_positive": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/false_positive: put: tags: - Events summary: Submit false positive to Frigate+ description: |- + **Access:** Admin role required. + Submit an event as a false positive to Frigate+. This endpoint is the same as the standard Frigate+ submission endpoint, but is specifically for marking an event as a false positive. @@ -3984,24 +4713,29 @@ paths: type: string title: Event Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/EventUploadPlusResponse" - "422": + $ref: '#/components/schemas/EventUploadPlusResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/sub_label": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/sub_label: post: tags: - Events summary: Set event sub label description: |- + **Access:** Admin role required. + Sets an event's sub label. Returns a success message or an error if the event is not found. operationId: set_sub_label_events__event_id__sub_label_post @@ -4017,26 +4751,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/EventsSubLabelBody" + $ref: '#/components/schemas/EventsSubLabelBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/recognized_license_plate": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/recognized_license_plate: post: tags: - Events summary: Set event license plate description: |- + **Access:** Admin role required. + Sets an event's license plate. Returns a success message or an error if the event is not found. operationId: set_plate_events__event_id__recognized_license_plate_post @@ -4052,28 +4791,32 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/EventsLPRBody" + $ref: '#/components/schemas/EventsLPRBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/attributes": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/attributes: post: tags: - Events summary: Set custom classification attributes - description: >- - Sets an event's custom classification attributes for all attribute-type - models that apply to the event's object type. + description: |- + **Access:** Admin role required. + + Sets an event's custom classification attributes for all attribute-type models that apply to the event's object type. operationId: set_attributes_events__event_id__attributes_post parameters: - name: event_id @@ -4087,26 +4830,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/EventsAttributesBody" + $ref: '#/components/schemas/EventsAttributesBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/description": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/description: post: tags: - Events summary: Set event description description: |- + **Access:** Admin role required. + Sets an event's description. Returns a success message or an error if the event is not found. operationId: set_description_events__event_id__description_post @@ -4122,29 +4870,35 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/EventsDescriptionBody" + $ref: '#/components/schemas/EventsDescriptionBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/description/regenerate": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/description/regenerate: put: tags: - Events summary: Regenerate event description description: |- + **Access:** Admin role required. + Regenerates an event's description. Returns a success message or an error if the event is not found. - operationId: regenerate_description_events__event_id__description_regenerate_put + operationId: + regenerate_description_events__event_id__description_regenerate_put parameters: - name: event_id in: path @@ -4157,8 +4911,8 @@ paths: required: false schema: anyOf: - - $ref: "#/components/schemas/RegenerateDescriptionEnum" - - type: "null" + - $ref: '#/components/schemas/RegenerateDescriptionEnum' + - type: 'null' default: thumbnails title: Source - name: force @@ -4167,28 +4921,33 @@ paths: schema: anyOf: - type: boolean - - type: "null" + - type: 'null' default: false title: Force responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /description/generate: post: tags: - Events summary: Generate description embedding description: |- + **Access:** Admin role required. + Generates an embedding for an event's description. Returns a success message or an error if the event is not found. operationId: generate_description_embedding_description_generate_post @@ -4197,26 +4956,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/EventsDescriptionBody" + $ref: '#/components/schemas/EventsDescriptionBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /events/: delete: tags: - Events summary: Delete events description: |- + **Access:** Admin role required. + Deletes a list of events from the database. Returns a success message or an error if the events are not found. operationId: delete_events_events__delete @@ -4225,26 +4989,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/EventsDeleteBody" + $ref: '#/components/schemas/EventsDeleteBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/EventMultiDeleteResponse" - "422": + $ref: '#/components/schemas/EventMultiDeleteResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{camera_name}/{label}/create": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{camera_name}/{label}/create: post: tags: - Events summary: Create manual event description: |- + **Access:** Admin role required. + Creates a manual event in the database. Returns a success message or an error if the event is not found. NOTES: @@ -4268,31 +5037,36 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/EventsCreateBody" + $ref: '#/components/schemas/EventsCreateBody' default: - score: 0 + score: 0.0 duration: 30 include_recording: true draw: {} responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/EventCreateResponse" - "422": + $ref: '#/components/schemas/EventCreateResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/end": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/end: put: tags: - Events summary: End manual event description: |- + **Access:** Admin role required. + Ends a manual event. Returns a success message or an error if the event is not found. NOTE: This should only be used for manual events. @@ -4309,26 +5083,31 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/EventsEndBody" + $ref: '#/components/schemas/EventsEndBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /trigger/embedding: post: tags: - Events summary: Create trigger embedding description: |- + **Access:** Admin role required. + Creates a trigger embedding for a specific trigger. Returns a success message or an error if the trigger is not found. operationId: create_trigger_embedding_trigger_embedding_post @@ -4350,30 +5129,36 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/TriggerEmbeddingBody" + $ref: '#/components/schemas/TriggerEmbeddingBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: type: object title: Response Create Trigger Embedding Trigger Embedding Post - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/trigger/embedding/{camera_name}/{name}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /trigger/embedding/{camera_name}/{name}: put: tags: - Events summary: Update trigger embedding description: |- + **Access:** Admin role required. + Updates a trigger embedding for a specific trigger. Returns a success message or an error if the trigger is not found. - operationId: update_trigger_embedding_trigger_embedding__camera_name___name__put + operationId: + update_trigger_embedding_trigger_embedding__camera_name___name__put parameters: - name: camera_name in: path @@ -4392,31 +5177,36 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/TriggerEmbeddingBody" + $ref: '#/components/schemas/TriggerEmbeddingBody' responses: - "200": + '200': description: Successful Response content: application/json: schema: type: object - title: >- - Response Update Trigger Embedding Trigger Embedding Camera - Name Name Put - "422": + title: Response Update Trigger Embedding Trigger Embedding + Camera Name Name Put + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin delete: tags: - Events summary: Delete trigger embedding description: |- + **Access:** Admin role required. + Deletes a trigger embedding for a specific trigger. Returns a success message or an error if the trigger is not found. - operationId: delete_trigger_embedding_trigger_embedding__camera_name___name__delete + operationId: + delete_trigger_embedding_trigger_embedding__camera_name___name__delete parameters: - name: camera_name in: path @@ -4431,27 +5221,31 @@ paths: type: string title: Name responses: - "200": + '200': description: Successful Response content: application/json: schema: type: object - title: >- - Response Delete Trigger Embedding Trigger Embedding Camera - Name Name Delete - "422": + title: Response Delete Trigger Embedding Trigger Embedding + Camera Name Name Delete + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/triggers/status/{camera_name}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /triggers/status/{camera_name}: get: tags: - Events summary: Get triggers status description: |- + **Access:** Admin role required. + Gets the status of all triggers for a specific camera. Returns a success message or an error if the camera is not found. operationId: get_triggers_status_triggers_status__camera_name__get @@ -4463,20 +5257,24 @@ paths: type: string title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: type: object - title: Response Get Triggers Status Triggers Status Camera Name Get - "422": + title: Response Get Triggers Status Triggers Status Camera Name + Get + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /{camera_name}: get: tags: - Media @@ -4489,7 +5287,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: fps in: query @@ -4511,7 +5309,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Bbox - name: timestamp in: query @@ -4519,7 +5317,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Timestamp - name: zones in: query @@ -4527,7 +5325,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Zones - name: mask in: query @@ -4535,7 +5333,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Mask - name: motion in: query @@ -4543,7 +5341,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Motion - name: regions in: query @@ -4551,21 +5349,25 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Regions responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/ptz/info": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/ptz/info: get: tags: - Media @@ -4578,29 +5380,33 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/latest.{extension}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/latest.{extension}: get: tags: - Media summary: Latest Frame - description: >- - Returns the latest frame from the specified camera in the requested - format (jpg, png, webp). Falls back to preview frames if the camera is - offline. + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Returns the latest frame from the specified camera in the requested format (jpg, png, webp). Falls back to preview frames if the camera is offline. operationId: latest_frame__camera_name__latest__extension__get parameters: - name: camera_name @@ -4609,20 +5415,20 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: extension in: path required: true schema: - $ref: "#/components/schemas/Extension" + $ref: '#/components/schemas/Extension' - name: bbox in: query required: false schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Bbox - name: timestamp in: query @@ -4630,7 +5436,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Timestamp - name: zones in: query @@ -4638,7 +5444,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Zones - name: mask in: query @@ -4646,7 +5452,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Mask - name: motion in: query @@ -4654,7 +5460,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Motion - name: paths in: query @@ -4662,7 +5468,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Paths - name: regions in: query @@ -4670,7 +5476,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Regions - name: quality in: query @@ -4678,7 +5484,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' default: 70 title: Quality - name: height @@ -4687,7 +5493,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Height - name: store in: query @@ -4695,26 +5501,29 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Store responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/recordings/{frame_time}/snapshot.{format}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /{camera_name}/recordings/{frame_time}/snapshot.{format}: get: tags: - Media summary: Get Snapshot From Recording - operationId: >- + operationId: get_snapshot_from_recording__camera_name__recordings__frame_time__snapshot__format__get parameters: - name: camera_name @@ -4723,7 +5532,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: frame_time in: path @@ -4747,23 +5556,28 @@ paths: type: integer title: Height responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/plus/{frame_time}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/plus/{frame_time}: post: tags: - Media summary: Submit Recording Snapshot To Plus - operationId: submit_recording_snapshot_to_plus__camera_name__plus__frame_time__post + operationId: + submit_recording_snapshot_to_plus__camera_name__plus__frame_time__post parameters: - name: camera_name in: path @@ -4771,7 +5585,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: frame_time in: path @@ -4780,26 +5594,32 @@ paths: type: string title: Frame Time responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/start/{start_ts}/end/{end_ts}/clip.mp4": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{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. - operationId: recording_clip__camera_name__start__start_ts__end__end_ts__clip_mp4_get + description: |- + **Access:** Authenticated user with access to the referenced camera. + + 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 in: path @@ -4807,7 +5627,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: start_ts in: path @@ -4822,25 +5642,29 @@ paths: type: number title: End Ts responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/vod/{camera_name}/start/{start_ts}/end/{end_ts}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /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. + description: |- + **Access:** Authenticated user with access to the referenced camera. + + 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 @@ -4849,7 +5673,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: start_ts in: path @@ -4871,26 +5695,31 @@ paths: default: false title: Force Discontinuity responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/vod/{year_month}/{day}/{hour}/{camera_name}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /vod/{year_month}/{day}/{hour}/{camera_name}: get: tags: - Media summary: Vod Hour No Timezone - 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 + description: |- + **Access:** Authenticated user with access to the referenced camera. + + 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 in: path @@ -4916,30 +5745,34 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/vod/{year_month}/{day}/{hour}/{camera_name}/{tz_name}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /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 + description: |- + **Access:** Authenticated user with access to the referenced camera. + + 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 in: path @@ -4965,7 +5798,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: tz_name in: path @@ -4974,25 +5807,29 @@ paths: type: string title: Tz Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/vod/event/{event_id}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /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. + description: |- + **Access:** Authenticated user with access to the referenced camera. + + 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 @@ -5011,26 +5848,31 @@ paths: title: Padding description: Padding to apply to the vod. responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/vod/clip/{camera_name}/start/{start_ts}/end/{end_ts}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /vod/clip/{camera_name}/start/{start_ts}/end/{end_ts}: get: tags: - Media summary: Vod Clip - description: >- - Returns an HLS playlist for a timestamp range with HLS discontinuity - enabled. Append /master.m3u8 or /index.m3u8 for HLS playback. - operationId: vod_clip_vod_clip__camera_name__start__start_ts__end__end_ts__get + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Returns an HLS playlist for a timestamp range with HLS discontinuity enabled. Append /master.m3u8 or /index.m3u8 for HLS playback. + operationId: + vod_clip_vod_clip__camera_name__start__start_ts__end__end_ts__get parameters: - name: camera_name in: path @@ -5038,7 +5880,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: start_ts in: path @@ -5053,23 +5895,29 @@ paths: type: number title: End Ts responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/snapshot.jpg": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /events/{event_id}/snapshot.jpg: get: tags: - Media summary: Event Snapshot - description: Returns a snapshot image for the specified object id. + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Returns a snapshot image for the specified object id. operationId: event_snapshot_events__event_id__snapshot_jpg_get parameters: - name: event_id @@ -5084,7 +5932,7 @@ paths: schema: anyOf: - type: boolean - - type: "null" + - type: 'null' default: false title: Download - name: timestamp @@ -5093,7 +5941,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Timestamp - name: bbox in: query @@ -5101,7 +5949,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Bbox - name: crop in: query @@ -5109,7 +5957,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Crop - name: height in: query @@ -5117,7 +5965,7 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Height - name: quality in: query @@ -5125,21 +5973,24 @@ paths: schema: anyOf: - type: integer - - type: "null" + - type: 'null' title: Quality responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/thumbnail.{extension}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /events/{event_id}/thumbnail.{extension}: get: tags: - Media @@ -5156,7 +6007,7 @@ paths: in: path required: true schema: - $ref: "#/components/schemas/Extension" + $ref: '#/components/schemas/Extension' - name: max_cache_age in: query required: false @@ -5176,27 +6027,23 @@ paths: - android default: ios title: Format - - name: camera_name - in: query - required: false - schema: - anyOf: - - type: string - - type: "null" - title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/grid.jpg": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/grid.jpg: get: tags: - Media @@ -5209,7 +6056,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: color in: query @@ -5226,23 +6073,30 @@ paths: default: 0.5 title: Font Scale responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/region_grid": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/region_grid: delete: tags: - Media summary: Clear Region Grid - description: Clear the region grid for a camera. + description: |- + **Access:** Admin role required. + + Clear the region grid for a camera. operationId: clear_region_grid__camera_name__region_grid_delete parameters: - name: camera_name @@ -5252,23 +6106,27 @@ paths: type: string title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/snapshot-clean.webp": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /events/{event_id}/snapshot-clean.webp: get: tags: - Media summary: Event Snapshot Clean - operationId: event_snapshot_clean_events__event_id__snapshot_clean_webp_get + operationId: + event_snapshot_clean_events__event_id__snapshot_clean_webp_get parameters: - name: event_id in: path @@ -5283,27 +6141,23 @@ paths: type: boolean default: false title: Download - - name: camera_name - in: query - required: false - schema: - anyOf: - - type: string - - type: "null" - title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/clip.mp4": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /events/{event_id}/clip.mp4: get: tags: - Media @@ -5325,27 +6179,61 @@ paths: default: 0 title: Padding description: Padding to apply to clip. - - name: camera_name - in: query - required: false - schema: - anyOf: - - type: string - - type: "null" - title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/events/{event_id}/preview.gif": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /review/{review_id}/clip.mp4: + get: + tags: + - Media + summary: Review Clip + operationId: review_clip_review__review_id__clip_mp4_get + parameters: + - name: review_id + in: path + required: true + schema: + type: string + title: Review Id + - name: padding + in: query + required: false + schema: + type: integer + description: Padding to apply to clip. + default: 0 + title: Padding + description: Padding to apply to clip. + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /events/{event_id}/preview.gif: get: tags: - Media @@ -5358,32 +6246,29 @@ paths: schema: type: string title: Event Id - - name: camera_name - in: query - required: false - schema: - anyOf: - - type: string - - type: "null" - title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/start/{start_ts}/end/{end_ts}/preview.gif": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/start/{start_ts}/end/{end_ts}/preview.gif: get: tags: - Media summary: Preview Gif - operationId: preview_gif__camera_name__start__start_ts__end__end_ts__preview_gif_get + operationId: + preview_gif__camera_name__start__start_ts__end__end_ts__preview_gif_get parameters: - name: camera_name in: path @@ -5391,7 +6276,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: start_ts in: path @@ -5415,23 +6300,28 @@ paths: title: Max Cache Age description: Max cache age in seconds. Default 30 days in seconds. responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/start/{start_ts}/end/{end_ts}/preview.mp4": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/start/{start_ts}/end/{end_ts}/preview.mp4: get: tags: - Media summary: Preview Mp4 - operationId: preview_mp4__camera_name__start__start_ts__end__end_ts__preview_mp4_get + operationId: + preview_mp4__camera_name__start__start_ts__end__end_ts__preview_mp4_get parameters: - name: camera_name in: path @@ -5439,7 +6329,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: start_ts in: path @@ -5463,18 +6353,22 @@ paths: title: Max Cache Age description: Max cache age in seconds. Default 7 days in seconds. responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/review/{event_id}/preview": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /review/{event_id}/preview: get: tags: - Media @@ -5497,32 +6391,31 @@ paths: - mp4 default: gif title: Format - - name: camera_name - in: query - required: false - schema: - anyOf: - - type: string - - type: "null" - title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/preview/{file_name}/thumbnail.webp": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /preview/{file_name}/thumbnail.webp: get: tags: - Media summary: Preview Thumbnail - description: Get a thumbnail from the cached preview frames. + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Get a thumbnail from the cached preview frames. operationId: preview_thumbnail_preview__file_name__thumbnail_webp_get parameters: - name: file_name @@ -5531,32 +6424,30 @@ paths: schema: type: string title: File Name - - name: camera_name - in: query - required: false - schema: - anyOf: - - type: string - - type: "null" - title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/preview/{file_name}/thumbnail.jpg": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /preview/{file_name}/thumbnail.jpg: get: tags: - Media summary: Preview Thumbnail - description: Get a thumbnail from the cached preview frames. + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Get a thumbnail from the cached preview frames. operationId: preview_thumbnail_preview__file_name__thumbnail_jpg_get parameters: - name: file_name @@ -5565,27 +6456,22 @@ paths: schema: type: string title: File Name - - name: camera_name - in: query - required: false - schema: - anyOf: - - type: string - - type: "null" - title: Camera Name responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/{label}/thumbnail.jpg": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /{camera_name}/{label}/thumbnail.jpg: get: tags: - Media @@ -5598,7 +6484,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: label in: path @@ -5607,18 +6493,22 @@ paths: type: string title: Label responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/{label}/best.jpg": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/{label}/best.jpg: get: tags: - Media @@ -5631,7 +6521,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: label in: path @@ -5640,18 +6530,22 @@ paths: type: string title: Label responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/{label}/clip.mp4": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/{label}/clip.mp4: get: tags: - Media @@ -5664,7 +6558,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: label in: path @@ -5673,25 +6567,30 @@ paths: type: string title: Label responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/{label}/snapshot.jpg": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + description: '**Access:** Authenticated user with access to the referenced camera.' + /{camera_name}/{label}/snapshot.jpg: get: tags: - Media summary: Label Snapshot - description: >- - Returns the snapshot image from the latest event for the given camera - and label combo + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Returns the snapshot image from the latest event for the given camera and label combo operationId: label_snapshot__camera_name___label__snapshot_jpg_get parameters: - name: camera_name @@ -5700,7 +6599,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: label in: path @@ -5709,23 +6608,28 @@ paths: type: string title: Label responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/search/motion": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /{camera_name}/search/motion: post: tags: - Motion Search summary: Start motion search job description: |- + **Access:** Authenticated user with access to the referenced camera. + Starts an asynchronous search for significant motion changes within a user-defined Region of Interest (ROI) over a specified time range. Returns a job_id that can be used to poll for results. @@ -5737,34 +6641,40 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/MotionSearchRequest" + $ref: '#/components/schemas/MotionSearchRequest' responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/MotionSearchStartResponse" - "422": + $ref: '#/components/schemas/MotionSearchStartResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/search/motion/{job_id}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /{camera_name}/search/motion/{job_id}: get: tags: - Motion Search summary: Get motion search job status - description: Returns the status and results (if complete) of a motion search job. - operationId: >- + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Returns the status and results (if complete) of a motion search job. + operationId: get_motion_search_status_endpoint__camera_name__search_motion__job_id__get parameters: - name: camera_name @@ -5773,7 +6683,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: job_id in: path @@ -5782,25 +6692,31 @@ paths: type: string title: Job Id responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/MotionSearchStatusResponse" - "422": + $ref: '#/components/schemas/MotionSearchStatusResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/search/motion/{job_id}/cancel": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /{camera_name}/search/motion/{job_id}/cancel: post: tags: - Motion Search summary: Cancel motion search job - description: Cancels an active motion search job if it is still processing. - operationId: >- + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Cancels an active motion search job if it is still processing. + operationId: cancel_motion_search_endpoint__camera_name__search_motion__job_id__cancel_post parameters: - name: camera_name @@ -5809,7 +6725,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: job_id in: path @@ -5818,17 +6734,20 @@ paths: type: string title: Job Id responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera /recordings/storage: get: tags: @@ -5836,17 +6755,24 @@ paths: summary: Get Recordings Storage Usage operationId: get_recordings_storage_usage_recordings_storage_get responses: - "200": + '200': description: Successful Response content: application/json: schema: {} + security: + - frigateAdminAuth: [] + x-required-role: admin + description: '**Access:** Admin role required.' /recordings/summary: get: tags: - Recordings summary: All Recordings Summary - description: Returns true/false by day indicating if recordings exist + description: |- + **Access:** Any authenticated user. + + Returns true/false by day indicating if recordings exist operationId: all_recordings_summary_recordings_summary_get parameters: - name: timezone @@ -5862,27 +6788,33 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Cameras responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/recordings/summary": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + /{camera_name}/recordings/summary: get: tags: - Recordings summary: Recordings Summary - description: Returns hourly summary for recordings of given camera + description: |- + **Access:** Authenticated user with access to the referenced camera. + + Returns hourly summary for recordings of given camera operationId: recordings_summary__camera_name__recordings_summary_get parameters: - name: camera_name @@ -5891,7 +6823,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: timezone in: query @@ -5901,25 +6833,29 @@ paths: default: utc title: Timezone responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/{camera_name}/recordings": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera + /{camera_name}/recordings: get: tags: - Recordings summary: Recordings - description: >- - Return specific camera recordings between the given 'after'/'end' times. - If not provided the last hour will be used + description: |- + **Access:** Authenticated user with access to the referenced camera. + + 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: - name: camera_name @@ -5928,40 +6864,44 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera Name - name: after in: query required: false schema: type: number - default: 1774023877.74743 title: After - name: before in: query required: false schema: type: number - default: 1774027477.74744 title: Before responses: - "200": + '200': description: Successful Response content: application/json: schema: {} - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: camera /recordings/unavailable: get: tags: - Recordings summary: No Recordings - description: Get time ranges with no recordings. + description: |- + **Access:** Any authenticated user. + + Get time ranges with no recordings. operationId: no_recordings_recordings_unavailable_get parameters: - name: cameras @@ -5991,7 +6931,7 @@ paths: default: 30 title: Scale responses: - "200": + '200': description: Successful Response content: application/json: @@ -6000,18 +6940,23 @@ paths: items: type: object title: Response No Recordings Recordings Unavailable Get - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" - "/recordings/start/{start}/end/{end}": + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateUserAuth: [] + x-required-role: any + /recordings/start/{start}/end/{end}: delete: tags: - Recordings summary: Delete recordings description: |- + **Access:** Admin role required. + Deletes recordings within the specified time range. Recordings can be filtered by cameras and kept based on motion, objects, or audio attributes. operationId: delete_recordings_recordings_start__start__end__end__delete @@ -6038,7 +6983,7 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' title: Keep - name: cameras in: query @@ -6046,83 +6991,140 @@ paths: schema: anyOf: - type: string - - type: "null" + - type: 'null' default: all title: Cameras responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/GenericResponse" - "422": + $ref: '#/components/schemas/GenericResponse' + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /debug_replay/start: post: tags: - App summary: Start debug replay - description: - Start a debug replay session from camera recordings. Returns - immediately while clip generation runs as a background job; subscribe - to the 'debug_replay' job_state WS topic to track progress. + description: |- + **Access:** Admin role required. + + Start a debug replay session from camera recordings. Returns immediately while clip generation runs as a background job; subscribe to the 'debug_replay' job_state WS topic to track progress. operationId: start_debug_replay_debug_replay_start_post requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/DebugReplayStartBody" + $ref: '#/components/schemas/DebugReplayStartBody' responses: - "202": + '202': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/DebugReplayStartResponse" - "400": + $ref: '#/components/schemas/DebugReplayStartResponse' + '400': description: Invalid camera, time range, or no recordings - "409": + '409': description: A replay session is already active - "422": + '422': description: Validation Error content: application/json: schema: - $ref: "#/components/schemas/HTTPValidationError" + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin + /debug_replay/start_from_export: + post: + tags: + - App + summary: Start debug replay from an export + description: |- + **Access:** Admin role required. + + Start a debug replay session covering an existing export's time range. The end time is derived from the export's video duration. + operationId: + start_debug_replay_from_export_debug_replay_start_from_export_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DebugReplayStartFromExportBody' + responses: + '202': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DebugReplayStartResponse' + '400': + description: Invalid export, time range, or no recordings + '404': + description: Export not found + '409': + description: A replay session is already active + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + security: + - frigateAdminAuth: [] + x-required-role: admin /debug_replay/status: get: tags: - App summary: Get debug replay status - description: Get the status of the current debug replay session. + description: |- + **Access:** Admin role required. + + Get the status of the current debug replay session. operationId: get_debug_replay_status_debug_replay_status_get responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/DebugReplayStatusResponse" + $ref: '#/components/schemas/DebugReplayStatusResponse' + security: + - frigateAdminAuth: [] + x-required-role: admin /debug_replay/stop: post: tags: - App summary: Stop debug replay - description: Stop the active debug replay session and clean up all artifacts. + description: |- + **Access:** Admin role required. + + Stop the active debug replay session and clean up all artifacts. operationId: stop_debug_replay_debug_replay_stop_post responses: - "200": + '200': description: Successful Response content: application/json: schema: - $ref: "#/components/schemas/DebugReplayStopResponse" + $ref: '#/components/schemas/DebugReplayStopResponse' + security: + - frigateAdminAuth: [] + x-required-role: admin components: schemas: AppConfigSetBody: @@ -6134,12 +7136,12 @@ components: update_topic: anyOf: - type: string - - type: "null" + - type: 'null' title: Update Topic config_data: anyOf: - type: object - - type: "null" + - type: 'null' title: Config Data skip_save: type: boolean @@ -6171,7 +7173,7 @@ components: role: anyOf: - type: string - - type: "null" + - type: 'null' title: Role default: viewer type: object @@ -6187,7 +7189,7 @@ components: old_password: anyOf: - type: string - - type: "null" + - type: 'null' title: Old Password type: object required: @@ -6212,6 +7214,155 @@ components: required: - event_id title: AudioTranscriptionBody + BatchExportBody: + properties: + items: + items: + $ref: '#/components/schemas/BatchExportItem' + type: array + maxItems: 50 + minItems: 1 + title: Items + description: List of export items. Each item has its own camera and + time range. + export_case_id: + anyOf: + - type: string + maxLength: 30 + - type: 'null' + title: Export case ID + description: Existing export case ID to assign all exports to. + Attaching to an existing case is temporarily admin-only until + case-level ACLs exist. + new_case_name: + anyOf: + - type: string + maxLength: 100 + - type: 'null' + title: New case name + description: Name of a new export case to create when export_case_id + is omitted + new_case_description: + anyOf: + - type: string + - type: 'null' + title: New case description + description: Optional description for a newly created export case + type: object + required: + - items + title: BatchExportBody + BatchExportItem: + properties: + camera: + type: string + title: Camera name + start_time: + type: number + title: Start time + end_time: + type: number + title: End time + image_path: + anyOf: + - type: string + - type: 'null' + title: Existing thumbnail path + description: Optional existing image to use as the export thumbnail + friendly_name: + anyOf: + - type: string + maxLength: 256 + - type: 'null' + title: Friendly name + description: Optional friendly name for this specific export item + client_item_id: + anyOf: + - type: string + maxLength: 128 + - type: 'null' + title: Client item ID + description: Optional opaque client identifier echoed back in results + type: object + required: + - camera + - start_time + - end_time + title: BatchExportItem + BatchExportResponse: + properties: + export_case_id: + anyOf: + - type: string + - type: 'null' + title: Export Case Id + description: Export case ID associated with the batch + export_ids: + items: + type: string + type: array + title: Export Ids + description: Export IDs successfully queued + results: + items: + $ref: '#/components/schemas/BatchExportResultModel' + type: array + title: Results + description: Per-item batch export results + type: object + required: + - export_ids + - results + title: BatchExportResponse + description: Response model for starting an export batch. + BatchExportResultModel: + properties: + camera: + type: string + title: Camera + description: Camera name for this export attempt + export_id: + anyOf: + - type: string + - type: 'null' + title: Export Id + description: The export ID when the export was successfully queued + success: + type: boolean + title: Success + description: Whether the export was successfully queued + status: + anyOf: + - type: string + - type: 'null' + title: Status + description: Queue status for this camera export + error: + anyOf: + - type: string + - type: 'null' + title: Error + description: Validation or queueing error for this item, if any + item_index: + anyOf: + - type: integer + - type: 'null' + title: Item Index + description: Zero-based index of this result within the request items + list + client_item_id: + anyOf: + - type: string + - type: 'null' + title: Client Item Id + description: Opaque client-supplied item identifier echoed from the + request + type: object + required: + - camera + - success + title: BatchExportResultModel + description: Per-item result for a batch export request. Body_recognize_face_faces_recognize_post: properties: file: @@ -6246,24 +7397,31 @@ components: properties: messages: items: - $ref: "#/components/schemas/ChatMessage" + $ref: '#/components/schemas/ChatMessage' type: array title: Messages description: List of messages in the conversation max_tool_iterations: type: integer - maximum: 10 - minimum: 1 + maximum: 10.0 + minimum: 1.0 title: Max Tool Iterations - description: "Maximum number of tool call iterations (default: 5)" + description: 'Maximum number of tool call iterations (default: 5)' default: 5 stream: type: boolean title: Stream - description: >- - If true, stream the final assistant response in the body as - newline-delimited JSON. + description: If true, stream the final assistant response in the body + as newline-delimited JSON. default: false + enable_thinking: + anyOf: + - type: boolean + - type: 'null' + title: Enable Thinking + description: Per-request thinking toggle. None means use the provider + default. Ignored by providers that do not expose a per-request + thinking switch. type: object required: - messages @@ -6276,25 +7434,39 @@ components: title: Role description: "Message role: 'user', 'assistant', 'system', or 'tool'" content: - type: string + anyOf: + - {} + - type: 'null' title: Content - description: Message content + description: Message content. Usually a string, but may be a + multimodal content list (e.g. text + image_url) or null for + assistant turns that only request tool calls. tool_call_id: anyOf: - type: string - - type: "null" + - type: 'null' title: Tool Call Id - description: "For tool messages, the ID of the tool call" + description: For tool messages, the ID of the tool call name: anyOf: - type: string - - type: "null" + - type: 'null' title: Name - description: "For tool messages, the tool name" + description: For tool messages, the tool name + tool_calls: + anyOf: + - items: + type: object + type: array + - type: 'null' + title: Tool Calls + description: For assistant messages replayed from prior turns, the + OpenAI-format tool calls the model previously requested. Replaying + these verbatim keeps the conversation prefix byte-for-byte identical + so the model server's prompt cache hits on follow-up turns. type: object required: - role - - content title: ChatMessage description: A single message in a chat conversation. DayReview: @@ -6341,6 +7513,17 @@ components: - end_time title: DebugReplayStartBody description: Request body for starting a debug replay session. + DebugReplayStartFromExportBody: + properties: + export_id: + type: string + title: Export id + type: object + required: + - export_id + title: DebugReplayStartFromExportBody + description: Request body for starting a debug replay session from an + export. DebugReplayStartResponse: properties: success: @@ -6367,22 +7550,22 @@ components: replay_camera: anyOf: - type: string - - type: "null" + - type: 'null' title: Replay Camera source_camera: anyOf: - type: string - - type: "null" + - type: 'null' title: Source Camera start_time: anyOf: - type: number - - type: "null" + - type: 'null' title: Start Time end_time: anyOf: - type: number - - type: "null" + - type: 'null' title: End Time live_ready: type: boolean @@ -6392,7 +7575,13 @@ components: required: - active title: DebugReplayStatusResponse - description: Response for debug replay status. + description: |- + Response for debug replay status. + + Returns only session-presence fields. Startup progress and error + details flow through the job_state WebSocket topic via the + debug_replay job (see frigate.jobs.debug_replay); the + Replay page subscribes there with useJobStatus("debug_replay"). DebugReplayStopResponse: properties: success: @@ -6464,7 +7653,7 @@ components: sub_label: anyOf: - type: string - - type: "null" + - type: 'null' title: Sub Label camera: type: string @@ -6475,12 +7664,12 @@ components: end_time: anyOf: - type: number - - type: "null" + - type: 'null' title: End Time false_positive: anyOf: - type: boolean - - type: "null" + - type: 'null' title: False Positive zones: items: @@ -6490,7 +7679,7 @@ components: thumbnail: anyOf: - type: string - - type: "null" + - type: 'null' title: Thumbnail has_clip: type: boolean @@ -6504,22 +7693,22 @@ components: plus_id: anyOf: - type: string - - type: "null" + - type: 'null' title: Plus Id model_hash: anyOf: - type: string - - type: "null" + - type: 'null' title: Model Hash detector_type: anyOf: - type: string - - type: "null" + - type: 'null' title: Detector Type model_type: anyOf: - type: string - - type: "null" + - type: 'null' title: Model Type data: type: object @@ -6571,36 +7760,36 @@ components: sub_label: anyOf: - type: string - - type: "null" + - type: 'null' title: Sub Label score: anyOf: - type: number - - type: "null" + - type: 'null' title: Score default: 0 duration: anyOf: - type: integer - - type: "null" + - type: 'null' title: Duration default: 30 include_recording: anyOf: - type: boolean - - type: "null" + - type: 'null' title: Include Recording default: true draw: anyOf: - type: object - - type: "null" + - type: 'null' title: Draw default: {} pre_capture: anyOf: - type: integer - - type: "null" + - type: 'null' title: Pre Capture type: object title: EventsCreateBody @@ -6620,7 +7809,7 @@ components: description: anyOf: - type: string - - type: "null" + - type: 'null' title: The description of the event type: object required: @@ -6631,7 +7820,7 @@ components: end_time: anyOf: - type: number - - type: "null" + - type: 'null' title: End Time type: object title: EventsEndBody @@ -6644,157 +7833,14 @@ components: recognizedLicensePlateScore: anyOf: - type: number - maximum: 1 - exclusiveMinimum: 0 - - type: "null" + maximum: 1.0 + exclusiveMinimum: 0.0 + - type: 'null' title: Score for recognized license plate type: object required: - recognizedLicensePlate title: EventsLPRBody - BatchExportBody: - properties: - items: - items: - $ref: "#/components/schemas/BatchExportItem" - type: array - minItems: 1 - maxItems: 50 - title: Items - description: List of export items. Each item has its own camera and time range. - export_case_id: - anyOf: - - type: string - maxLength: 30 - - type: "null" - title: Export case ID - description: Existing export case ID to assign all exports to. Attaching to an existing case is temporarily admin-only until case-level ACLs exist. - new_case_name: - anyOf: - - type: string - maxLength: 100 - - type: "null" - title: New case name - description: Name of a new export case to create when export_case_id is omitted - new_case_description: - anyOf: - - type: string - - type: "null" - title: New case description - description: Optional description for a newly created export case - type: object - required: - - items - title: BatchExportBody - BatchExportItem: - properties: - camera: - type: string - title: Camera name - start_time: - type: number - title: Start time - end_time: - type: number - title: End time - image_path: - anyOf: - - type: string - - type: "null" - title: Existing thumbnail path - description: Optional existing image to use as the export thumbnail - friendly_name: - anyOf: - - type: string - maxLength: 256 - - type: "null" - title: Friendly name - description: Optional friendly name for this specific export item - client_item_id: - anyOf: - - type: string - maxLength: 128 - - type: "null" - title: Client item ID - description: Optional opaque client identifier echoed back in results - type: object - required: - - camera - - start_time - - end_time - title: BatchExportItem - BatchExportResponse: - properties: - export_case_id: - anyOf: - - type: string - - type: "null" - title: Export Case Id - description: Export case ID associated with the batch - export_ids: - items: - type: string - type: array - title: Export Ids - description: Export IDs successfully queued - results: - items: - $ref: "#/components/schemas/BatchExportResultModel" - type: array - title: Results - description: Per-item batch export results - type: object - required: - - export_ids - - results - title: BatchExportResponse - description: Response model for starting an export batch. - BatchExportResultModel: - properties: - camera: - type: string - title: Camera - description: Camera name for this export attempt - export_id: - anyOf: - - type: string - - type: "null" - title: Export Id - description: The export ID when the export was successfully queued - success: - type: boolean - title: Success - description: Whether the export was successfully queued - status: - anyOf: - - type: string - - type: "null" - title: Status - description: Queue status for this camera export - error: - anyOf: - - type: string - - type: "null" - title: Error - description: Validation or queueing error for this item, if any - item_index: - anyOf: - - type: integer - - type: "null" - title: Item Index - description: Zero-based index of this result within the request items list - client_item_id: - anyOf: - - type: string - - type: "null" - title: Client Item Id - description: Opaque client-supplied item identifier echoed from the request - type: object - required: - - camera - - success - title: BatchExportResultModel - description: Per-item result for a batch export request. EventsSubLabelBody: properties: subLabel: @@ -6804,14 +7850,14 @@ components: subLabelScore: anyOf: - type: number - maximum: 1 - exclusiveMinimum: 0 - - type: "null" + maximum: 1.0 + exclusiveMinimum: 0.0 + - type: 'null' title: Score for sub label camera: anyOf: - type: string - - type: "null" + - type: 'null' title: Camera this object is detected on. type: object required: @@ -6844,9 +7890,10 @@ components: anyOf: - type: string maxLength: 30 - - type: "null" + - type: 'null' title: Export Case Id - description: "Case ID to assign to, or null to unassign from current case" + description: Case ID to assign to, or null to unassign from current + case type: object required: - ids @@ -6862,7 +7909,7 @@ components: description: anyOf: - type: string - - type: "null" + - type: 'null' title: Description description: Optional description of the export case type: object @@ -6883,7 +7930,7 @@ components: description: anyOf: - type: string - - type: "null" + - type: 'null' title: Description description: Optional description of the export case created_at: @@ -6908,18 +7955,101 @@ components: anyOf: - type: string maxLength: 100 - - type: "null" + - type: 'null' title: Name description: Updated friendly name of the export case description: anyOf: - type: string - - type: "null" + - type: 'null' title: Description description: Updated description of the export case type: object title: ExportCaseUpdateBody description: Request body for updating an existing export case. + ExportJobModel: + properties: + id: + type: string + title: Id + description: Unique identifier for the export job + job_type: + type: string + title: Job Type + description: Job type + status: + type: string + title: Status + description: Current job status + camera: + type: string + title: Camera + description: Camera associated with this export job + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: Friendly name for the export + export_case_id: + anyOf: + - type: string + - type: 'null' + title: Export Case Id + description: ID of the export case this export belongs to + request_start_time: + type: number + title: Request Start Time + description: Requested export start time + request_end_time: + type: number + title: Request End Time + description: Requested export end time + start_time: + anyOf: + - type: number + - type: 'null' + title: Start Time + description: Unix timestamp when execution started + end_time: + anyOf: + - type: number + - type: 'null' + title: End Time + description: Unix timestamp when execution completed + error_message: + anyOf: + - type: string + - type: 'null' + title: Error Message + description: Error message for failed jobs + results: + anyOf: + - type: object + - type: 'null' + title: Results + description: Result metadata for completed jobs + current_step: + type: string + title: Current Step + description: Current execution step (queued, preparing, encoding, + encoding_retry, finalizing) + default: queued + progress_percent: + type: number + title: Progress Percent + description: Progress percentage of the current step (0.0 - 100.0) + default: 0.0 + type: object + required: + - id + - job_type + - status + - camera + - request_start_time + - request_end_time + title: ExportJobModel + description: Model representing a queued or running export job. ExportModel: properties: id: @@ -6953,7 +8083,7 @@ components: export_case_id: anyOf: - type: string - - type: "null" + - type: 'null' title: Export Case Id description: ID of the export case this export belongs to type: object @@ -6970,14 +8100,14 @@ components: ExportRecordingsBody: properties: source: - $ref: "#/components/schemas/PlaybackSourceEnum" + $ref: '#/components/schemas/PlaybackSourceEnum' title: Playback source default: recordings name: anyOf: - type: string maxLength: 256 - - type: "null" + - type: 'null' title: Friendly name image_path: type: string @@ -6986,7 +8116,7 @@ components: anyOf: - type: string maxLength: 30 - - type: "null" + - type: 'null' title: Export case ID description: ID of the export case to assign this export to type: object @@ -6994,7 +8124,7 @@ components: ExportRecordingsCustomBody: properties: source: - $ref: "#/components/schemas/PlaybackSourceEnum" + $ref: '#/components/schemas/PlaybackSourceEnum' title: Playback source default: recordings name: @@ -7008,31 +8138,28 @@ components: anyOf: - type: string maxLength: 30 - - type: "null" + - type: 'null' title: Export case ID description: ID of the export case to assign this export to ffmpeg_input_args: anyOf: - type: string - - type: "null" + - type: 'null' title: FFmpeg input arguments - description: >- - Custom FFmpeg input arguments. If not provided, defaults to - timelapse input args. + description: Custom FFmpeg input arguments. If not provided, defaults + to timelapse input args. ffmpeg_output_args: anyOf: - type: string - - type: "null" + - type: 'null' title: FFmpeg output arguments - description: >- - Custom FFmpeg output arguments. If not provided, defaults to - timelapse output args. + description: Custom FFmpeg output arguments. If not provided, defaults + to timelapse output args. cpu_fallback: type: boolean title: CPU Fallback - description: >- - If true, retry export without hardware acceleration if the initial - export fails. + description: If true, retry export without hardware acceleration if + the initial export fails. default: false type: object title: ExportRecordingsCustomBody @@ -7063,25 +8190,23 @@ components: score: anyOf: - type: number - - type: "null" + - type: 'null' title: Score description: Confidence score of the recognition (0-1) face_name: anyOf: - type: string - - type: "null" + - type: 'null' title: Face Name description: The recognized face name if successful type: object required: - success title: FaceRecognitionResponse - description: >- + description: |- Response model for face recognition endpoint. - - Returns the result of attempting to recognize a face from an uploaded - image. + Returns the result of attempting to recognize a face from an uploaded image. FacesResponse: additionalProperties: items: @@ -7104,36 +8229,33 @@ components: GenAIProbeBody: properties: provider: - type: string - enum: - - openai - - azure_openai - - gemini - - ollama - - llamacpp - title: Provider - description: GenAI provider to probe + $ref: '#/components/schemas/GenAIProviderEnum' api_key: anyOf: - type: string - - type: "null" - title: API Key - description: API key for the provider (when applicable) + - type: 'null' + title: Api Key base_url: anyOf: - type: string - - type: "null" - title: Base URL - description: Base URL for self-hosted or compatible providers + - type: 'null' + title: Base Url provider_options: type: object title: Provider Options - description: Additional provider-specific options - default: {} type: object required: - provider title: GenAIProbeBody + GenAIProviderEnum: + type: string + enum: + - openai + - azure_openai + - gemini + - ollama + - llamacpp + title: GenAIProviderEnum GenerateObjectExamplesBody: properties: model_name: @@ -7143,7 +8265,8 @@ components: label: type: string title: Label - description: "Object label to collect examples for (e.g., 'person', 'car')" + description: Object label to collect examples for (e.g., 'person', + 'car') type: object required: - model_name @@ -7167,9 +8290,8 @@ components: minItems: 4 type: object title: Cameras - description: >- - Dictionary mapping camera names to normalized crop coordinates in - [x1, y1, x2, y2] format (values 0-1) + description: Dictionary mapping camera names to normalized crop + coordinates in [x1, y1, x2, y2] format (values 0-1) type: object required: - model_name @@ -7192,7 +8314,7 @@ components: properties: detail: items: - $ref: "#/components/schemas/ValidationError" + $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object @@ -7223,28 +8345,26 @@ components: dry_run: type: boolean title: Dry Run - description: "If True, only report orphans without deleting them" + description: If True, only report orphans without deleting them default: true media_types: items: type: string type: array title: Media Types - description: >- - Types of media to sync: 'all', 'event_snapshots', - 'event_thumbnails', 'review_thumbnails', 'previews', 'exports', - 'recordings' + description: "Types of media to sync: 'all', 'event_snapshots', 'event_thumbnails', + 'review_thumbnails', 'previews', 'exports', 'recordings'" default: - all force: type: boolean title: Force - description: "If True, bypass safety threshold checks" + description: If True, bypass safety threshold checks default: false verbose: type: boolean title: Verbose - description: "If True, write full orphan file list to /config/media_sync/.txt" + description: If True, write full orphan file list to disk default: false type: object title: MediaSyncBody @@ -7277,7 +8397,7 @@ components: wall_time_seconds: type: number title: Wall Time Seconds - default: 0 + default: 0.0 segments_with_errors: type: integer title: Segments With Errors @@ -7302,21 +8422,22 @@ components: type: array type: array title: Polygon Points - description: "List of [x, y] normalized coordinates (0-1) defining the ROI polygon" + description: List of [x, y] normalized coordinates (0-1) defining the + ROI polygon threshold: type: integer - maximum: 255 - minimum: 1 + maximum: 255.0 + minimum: 1.0 title: Threshold description: Pixel difference threshold (1-255) default: 30 min_area: type: number - maximum: 100 + maximum: 100.0 minimum: 0.1 title: Min Area description: Minimum change area as a percentage of the ROI - default: 5 + default: 5.0 parallel: type: boolean title: Parallel @@ -7324,8 +8445,8 @@ components: default: false max_results: type: integer - maximum: 200 - minimum: 1 + maximum: 200.0 + minimum: 1.0 title: Max Results description: Maximum number of search results to return default: 25 @@ -7384,33 +8505,33 @@ components: results: anyOf: - items: - $ref: "#/components/schemas/MotionSearchResult" + $ref: '#/components/schemas/MotionSearchResult' type: array - - type: "null" + - type: 'null' title: Results total_frames_processed: anyOf: - type: integer - - type: "null" + - type: 'null' title: Total Frames Processed error_message: anyOf: - type: string - - type: "null" + - type: 'null' title: Error Message metrics: anyOf: - - $ref: "#/components/schemas/MotionSearchMetricsResponse" - - type: "null" + - $ref: '#/components/schemas/MotionSearchMetricsResponse' + - type: 'null' scanning_timestamp: anyOf: - type: number - - type: "null" + - type: 'null' title: Scanning Timestamp progress: anyOf: - type: number - - type: "null" + - type: 'null' title: Progress type: object required: @@ -7526,7 +8647,7 @@ components: type: boolean title: Has Been Reviewed severity: - $ref: "#/components/schemas/SeverityEnum" + $ref: '#/components/schemas/SeverityEnum' thumb_path: type: string title: Thumb Path @@ -7546,10 +8667,10 @@ components: ReviewSummaryResponse: properties: last24Hours: - $ref: "#/components/schemas/Last24HoursReview" + $ref: '#/components/schemas/Last24HoursReview' root: additionalProperties: - $ref: "#/components/schemas/DayReview" + $ref: '#/components/schemas/DayReview' type: object title: Root type: object @@ -7576,9 +8697,15 @@ components: export_id: anyOf: - type: string - - type: "null" + - type: 'null' title: Export Id description: The export ID if successfully started + status: + anyOf: + - type: string + - type: 'null' + title: Status + description: Queue status for the export job type: object required: - success @@ -7610,14 +8737,14 @@ components: TriggerEmbeddingBody: properties: type: - $ref: "#/components/schemas/TriggerType" + $ref: '#/components/schemas/TriggerType' data: type: string title: Data threshold: type: number - maximum: 1 - minimum: 0 + maximum: 1.0 + minimum: 0.0 title: Threshold default: 0.5 type: object @@ -7631,6 +8758,36 @@ components: - thumbnail - description title: TriggerType + VLMMonitorRequest: + properties: + camera: + type: string + title: Camera + condition: + type: string + title: Condition + max_duration_minutes: + type: integer + title: Max Duration Minutes + default: 60 + labels: + items: + type: string + type: array + title: Labels + default: [] + zones: + items: + type: string + type: array + title: Zones + default: [] + type: object + required: + - camera + - condition + title: VLMMonitorRequest + description: Request model for starting a VLM watch job. ValidationError: properties: loc: @@ -7652,3 +8809,19 @@ components: - msg - type title: ValidationError + securitySchemes: + frigateAdminAuth: + type: apiKey + in: cookie + name: frigate_token + description: Authenticated session whose resolved role is 'admin'. The + session is established via the JWT cookie issued by POST /login, or via + proxy auth headers (remote-user / remote-role) when Frigate runs behind + an authenticating reverse proxy. + frigateUserAuth: + type: apiKey + in: cookie + name: frigate_token + description: Any authenticated session (role 'viewer' or higher), + established via the JWT cookie issued by POST /login, or via proxy auth + headers when Frigate runs behind an authenticating reverse proxy. diff --git a/generate_api_auth_spec.py b/generate_api_auth_spec.py new file mode 100644 index 0000000000..5768a6db64 --- /dev/null +++ b/generate_api_auth_spec.py @@ -0,0 +1,606 @@ +"""Generate the OpenAPI spec from the app, annotated with auth requirements. + +This generator builds the FastAPI application, exports its OpenAPI document via +``app.openapi()``, and enriches every operation with authentication metadata: + + * a ``components.securitySchemes`` block, + * a per-operation ``security`` requirement (so the docs render a lock badge), + * an ``x-required-role`` extension for machine readers, and + * a short bold ``Access:`` note prepended to each operation description. + +The committed docs/static/frigate-api.yaml is the output of this script. It is +generated rather than hand-maintained so it stays complete and current; the docs +build (docusaurus-plugin-openapi-docs) consumes it as-is. + +The access level for an endpoint is determined by BOTH its route-level +dependency (``require_role``/``allow_any_authenticated``/``allow_public``/ +``require_camera_access``) AND the global "secure by default" admin dependency, +which is bypassed only for the paths listed in ``require_admin_by_default``. +Those exempt lists are read directly from the function's closure so this script +stays in lockstep with ``frigate/api/auth.py`` instead of duplicating them. + +Many handlers enforce per-camera access by calling ``require_camera_access`` +inside the handler body rather than as a route dependency, which dependency +introspection cannot see. We recover those from the handler's bytecode (see +``_handler_enforces_camera``) and promote an otherwise "any authenticated" +operation to camera-scoped. + +Usage (from the repository root): + + python3 generate_api_auth_spec.py # write the spec + python3 generate_api_auth_spec.py --check # CI guard: fail if stale + +The process exits non-zero if the generated document fails structural +validation, or (in --check mode) if the committed spec is out of date. +""" + +import argparse +import difflib +import inspect +import io +import logging +import sys +from pathlib import Path + +from fastapi import FastAPI +from fastapi.routing import APIRoute +from ruamel.yaml import YAML +from ruamel.yaml.scalarstring import LiteralScalarString + +from frigate.api import app as main_app +from frigate.api import ( + auth, + camera, + chat, + classification, + debug_replay, + event, + export, + media, + motion_search, + notification, + preview, + record, + review, +) +from frigate.api.auth import require_admin_by_default + +logging.basicConfig(level=logging.INFO, format="%(message)s") +logger = logging.getLogger("generate_api_auth_spec") + +REPO_ROOT = Path(__file__).resolve().parent +OUTPUT_SPEC = REPO_ROOT / "docs" / "static" / "frigate-api.yaml" + +HTTP_METHODS = {"get", "post", "put", "delete", "patch"} + +# Banner written at the top of the generated spec. +HEADER = ( + "# Generated by generate_api_auth_spec.py — do not edit by hand.\n" + "# Regenerate with: python3 generate_api_auth_spec.py\n" + "# The empty info.title is intentional: a docusaurus-openapi-docs convention\n" + "# that suppresses the generated API introduction page.\n" +) + +# Post-processing applied on top of the raw app.openapi() export. These live +# only in the published spec, not in the app, so they are reproduced here. +SPEC_TITLE = "" +SPEC_SERVERS = [ + {"url": "https://demo.frigate.video/api"}, + {"url": "http://localhost:5001/api"}, +] + +# Access levels, ordered from least to most privileged. The string values are +# also what we emit as ``x-required-role``. +PUBLIC = "public" +AUTHENTICATED = "any" +CAMERA = "camera" +ADMIN = "admin" + +ADMIN_SCHEME = "frigateAdminAuth" +USER_SCHEME = "frigateUserAuth" + +SECURITY_SCHEMES = { + ADMIN_SCHEME: { + "type": "apiKey", + "in": "cookie", + "name": "frigate_token", + "description": ( + "Authenticated session whose resolved role is 'admin'. The session " + "is established via the JWT cookie issued by POST /login, or via " + "proxy auth headers (remote-user / remote-role) when Frigate runs " + "behind an authenticating reverse proxy." + ), + }, + USER_SCHEME: { + "type": "apiKey", + "in": "cookie", + "name": "frigate_token", + "description": ( + "Any authenticated session (role 'viewer' or higher), established " + "via the JWT cookie issued by POST /login, or via proxy auth " + "headers when Frigate runs behind an authenticating reverse proxy." + ), + }, +} + +# How each access level maps to a rendered note. +ACCESS_NOTES = { + PUBLIC: "**Access:** Public — no authentication required.", + AUTHENTICATED: "**Access:** Any authenticated user.", + CAMERA: "**Access:** Authenticated user with access to the referenced camera.", + ADMIN: "**Access:** Admin role required.", +} + + +def build_app() -> FastAPI: + """Build a bare app with every router mounted. + + This mirrors the router set wired up in frigate.api.fastapi_app. It omits + the global admin dependency and all runtime state; the OpenAPI route table + and the per-route dependencies are all we need to export and classify. + """ + app = FastAPI() + routers = [ + auth.router, + camera.router, + chat.router, + classification.router, + review.router, + main_app.router, + preview.router, + notification.router, + export.router, + event.router, + media.router, + motion_search.router, + record.router, + debug_replay.router, + ] + for router in routers: + app.include_router(router) + return app + + +def read_exempt_rules() -> tuple[set[str], tuple[str, ...]]: + """Read the admin-exemption lists straight from the auth dependency closure. + + Reading them here (rather than copying) keeps this generator in sync with + frigate/api/auth.py automatically. + """ + closure = inspect.getclosurevars(require_admin_by_default()).nonlocals + exempt_paths = set(closure["EXEMPT_PATHS"]) + exempt_prefixes = tuple(closure["EXEMPT_PREFIXES"]) + return exempt_paths, exempt_prefixes + + +def _first_segment(path: str) -> str: + return path.split("/", 2)[1] if path.startswith("/") and len(path) > 1 else "" + + +def _route_markers(route: APIRoute) -> tuple[set[str], list[str] | None]: + """Return the set of recognized auth markers on a route's dependencies.""" + markers: set[str] = set() + admin_roles: list[str] | None = None + + for dep in route.dependant.dependencies: + call = dep.call + qualname = getattr(call, "__qualname__", "") or "" + name = getattr(call, "__name__", "") or "" + + if "role_checker" in qualname: + markers.add(ADMIN) + try: + roles = inspect.getclosurevars(call).nonlocals.get("required_roles") + if roles: + admin_roles = list(roles) + except (TypeError, ValueError): + pass + elif name in ("require_camera_access", "require_go2rtc_stream_access"): + markers.add(CAMERA) + elif "auth_checker" in qualname: + markers.add(AUTHENTICATED) + elif "public_checker" in qualname: + markers.add(PUBLIC) + + return markers, admin_roles + + +def _handler_enforces_camera(route: APIRoute) -> bool: + """True if the route handler calls require_camera_access in its body. + + Such calls are invisible to dependency introspection. We detect them from + the handler's compiled bytecode: a global name referenced anywhere in the + function appears in ``__code__.co_names``. This catches direct calls (all of + them, currently); a call hidden behind a helper function would be missed. + """ + code = getattr(route.endpoint, "__code__", None) + return bool(code and "require_camera_access" in code.co_names) + + +def classify_route( + route: APIRoute, + exempt_paths: set[str], + exempt_prefixes: tuple[str, ...], +) -> tuple[str, list[str] | None, str | None]: + """Resolve the effective access level for a route. + + Returns (access_level, roles, flag). ``flag`` is a human-readable note when + the result needed inference or revealed a possible inconsistency. + """ + level, roles, flag = _classify_base(route, exempt_paths, exempt_prefixes) + + # In-body require_camera_access enforcement is invisible to dependency + # introspection. When the effective access would otherwise be "any + # authenticated", the handler's per-camera check is the real constraint, so + # promote it to camera-scoped. Admin/public are left alone: for admin the + # role is the binding requirement and the camera check is only defensive. + if level == AUTHENTICATED and _handler_enforces_camera(route): + return CAMERA, None, None + + return level, roles, flag + + +def _classify_base( + route: APIRoute, + exempt_paths: set[str], + exempt_prefixes: tuple[str, ...], +) -> tuple[str, list[str] | None, str | None]: + """Resolve the access level from route-level dependencies and exempt rules.""" + markers, admin_roles = _route_markers(route) + path = route.path + is_camera_path = _first_segment(path) == "{camera_name}" + exempt = path in exempt_paths or path.startswith(exempt_prefixes) or is_camera_path + + # Explicit route-level markers win, in order of specificity. + if ADMIN in markers: + return ADMIN, admin_roles or ["admin"], None + if CAMERA in markers: + return CAMERA, None, None + if AUTHENTICATED in markers: + if exempt: + return AUTHENTICATED, None, None + # The route opts in to any-authenticated, but the global admin check is + # not bypassed for this path, so admin is what actually gets enforced. + return ( + ADMIN, + ["admin"], + ( + "route declares allow_any_authenticated but path is not exempt from " + "the global admin check; admin is effectively enforced" + ), + ) + if PUBLIC in markers: + if exempt: + return PUBLIC, None, None + return ( + ADMIN, + ["admin"], + ( + "route declares allow_public but path is not exempt from the global " + "admin check; admin is effectively enforced" + ), + ) + + # No explicit auth marker: governed purely by the global default. + if not exempt: + return ADMIN, ["admin"], None + + # Exempt with no route dependency: the global admin check is bypassed and + # there is no route-level gate, so authorization (if any) happens inside the + # handler. Infer from the path shape and flag for confirmation. + if is_camera_path: + return ( + CAMERA, + None, + ( + "no route-level dependency; camera-scoped path, authorization " + "assumed to be enforced in the handler" + ), + ) + return ( + AUTHENTICATED, + None, + ( + "path is exempt from the global admin check but has no route-level " + "dependency; confirm authorization is enforced in the handler" + ), + ) + + +def build_access_map( + app: FastAPI, + exempt_paths: set[str], + exempt_prefixes: tuple[str, ...], +) -> dict[tuple[str, str], dict]: + """Map (path, lowercase method) -> classification details.""" + access_map: dict[tuple[str, str], dict] = {} + for route in app.routes: + if not isinstance(route, APIRoute): + continue + level, roles, flag = classify_route(route, exempt_paths, exempt_prefixes) + for method in route.methods: + if method in ("HEAD", "OPTIONS"): + continue + access_map[(route.path, method.lower())] = { + "level": level, + "roles": roles, + "flag": flag, + "path": route.path, + "method": method, + } + return access_map + + +def security_for(level: str) -> list: + """Build the OpenAPI ``security`` value for an access level.""" + if level == PUBLIC: + return [] + if level == ADMIN: + return [{ADMIN_SCHEME: []}] + # AUTHENTICATED and CAMERA both require any authenticated session; the + # camera-specific scoping is conveyed in the note and x-required-role. + return [{USER_SCHEME: []}] + + +def required_role_value(level: str, roles: list[str] | None): + if level == ADMIN and roles and roles != ["admin"]: + return roles + return level + + +def annotate_description(operation: dict, note: str) -> None: + existing = operation.get("description") + if not existing: + operation["description"] = note + return + operation["description"] = LiteralScalarString( + f"{note}\n\n{str(existing).rstrip()}" + ) + + +def base_document(raw: dict) -> dict: + """Apply the docs pipeline post-processing with a stable top-level order.""" + info = dict(raw.get("info", {})) + info["title"] = SPEC_TITLE + return { + "openapi": raw["openapi"], + "info": info, + "servers": [dict(server) for server in SPEC_SERVERS], + "paths": raw["paths"], + "components": raw.get("components", {}), + } + + +def enrich(spec: dict, access_map: dict) -> tuple[dict, list, list]: + """Add security schemes and per-operation auth metadata in place.""" + components = spec.setdefault("components", {}) + components["securitySchemes"] = dict(SECURITY_SCHEMES) + + counts: dict[str, int] = {} + flagged: list[dict] = [] + unmatched: list[tuple[str, str]] = [] + + for path, path_item in spec["paths"].items(): + for method, operation in path_item.items(): + if method.lower() not in HTTP_METHODS: + continue + details = access_map.get((path, method.lower())) + if details is None: + unmatched.append((method.upper(), path)) + continue + + level = details["level"] + counts[level] = counts.get(level, 0) + 1 + operation["security"] = security_for(level) + operation["x-required-role"] = required_role_value(level, details["roles"]) + annotate_description(operation, ACCESS_NOTES[level]) + + if details["flag"]: + flagged.append(details) + + return counts, flagged, unmatched + + +# Numeric defaults at or above this magnitude are treated as live Unix +# timestamps baked into the schema at import time (e.g. the /{camera_name} +# /recordings after/before params default to datetime.now()). They make the +# export non-deterministic and document a meaningless frozen epoch, so they are +# stripped. The proper fix is to default those route params to None and resolve +# "now" inside the handler. +VOLATILE_DEFAULT_THRESHOLD = 1_000_000_000 + + +def strip_volatile_defaults(node, trail: str = "") -> list[tuple[str, float]]: + """Remove epoch-like numeric ``default`` values so the export is stable. + + Returns the (location, value) pairs that were removed, for reporting. + """ + removed: list[tuple[str, float]] = [] + if isinstance(node, dict): + default = node.get("default") + if ( + isinstance(default, (int, float)) + and not isinstance(default, bool) + and default >= VOLATILE_DEFAULT_THRESHOLD + ): + removed.append((trail, default)) + del node["default"] + for key, value in node.items(): + removed.extend(strip_volatile_defaults(value, f"{trail}/{key}")) + elif isinstance(node, list): + for index, value in enumerate(node): + removed.extend(strip_volatile_defaults(value, f"{trail}[{index}]")) + return removed + + +def to_block_scalars(node): + """Recursively render multi-line strings as literal block scalars. + + Produces readable, deterministic YAML (``|-`` blocks) instead of long + double-quoted lines with escaped newlines. + """ + if isinstance(node, dict): + return {key: to_block_scalars(value) for key, value in node.items()} + if isinstance(node, list): + return [to_block_scalars(value) for value in node] + if isinstance(node, str) and "\n" in node: + return LiteralScalarString(node) + return node + + +def _iter_refs(node): + if isinstance(node, dict): + for key, value in node.items(): + if key == "$ref" and isinstance(value, str): + yield value + else: + yield from _iter_refs(value) + elif isinstance(node, list): + for value in node: + yield from _iter_refs(value) + + +def validate(spec: dict) -> list[str]: + """Structural sanity checks on the generated document.""" + problems: list[str] = [] + schemas = set(spec.get("components", {}).get("schemas", {})) + defined_schemes = set(spec.get("components", {}).get("securitySchemes", {})) + + for ref in _iter_refs(spec): + if ref.startswith("#/components/schemas/"): + name = ref.rsplit("/", 1)[-1] + if name not in schemas: + problems.append(f"dangling $ref: {ref}") + + for path, path_item in spec.get("paths", {}).items(): + for method, operation in path_item.items(): + if method.lower() not in HTTP_METHODS or not isinstance(operation, dict): + continue + location = f"{method.upper()} {path}" + if "x-required-role" not in operation: + problems.append(f"missing x-required-role: {location}") + if "security" not in operation: + problems.append(f"missing security: {location}") + continue + for requirement in operation["security"]: + for scheme in requirement: + if scheme not in defined_schemes: + problems.append( + f"undefined security scheme {scheme}: {location}" + ) + + return sorted(set(problems)) + + +def render(spec: dict) -> str: + """Serialize the spec to the canonical YAML string (with the header).""" + yaml = YAML() + yaml.width = 80 + yaml.indent(mapping=2, sequence=4, offset=2) + stream = io.StringIO() + yaml.dump(spec, stream) + return HEADER + stream.getvalue() + + +def build_spec() -> tuple[dict, dict, list, list, list]: + app = build_app() + exempt_paths, exempt_prefixes = read_exempt_rules() + access_map = build_access_map(app, exempt_paths, exempt_prefixes) + + spec = base_document(app.openapi()) + normalized = strip_volatile_defaults(spec) + counts, flagged, unmatched = enrich(spec, access_map) + spec = to_block_scalars(spec) + return spec, counts, flagged, unmatched, normalized + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description="Generate the annotated OpenAPI spec.") + parser.add_argument( + "--check", + action="store_true", + help="verify the committed spec is up to date without writing; " + "exit non-zero if it would change", + ) + args = parser.parse_args(argv) + + spec, counts, flagged, unmatched, normalized = build_spec() + problems = validate(spec) + rendered = render(spec) + + if args.check: + return _check(rendered, problems) + + if problems: + logger.error("Refusing to write — generated spec failed validation:") + for problem in problems: + logger.error(" %s", problem) + return 1 + + OUTPUT_SPEC.write_text(rendered) + _report(counts, flagged, unmatched, normalized) + logger.info("\nWrote %s", OUTPUT_SPEC.relative_to(REPO_ROOT)) + return 0 + + +def _check(rendered: str, problems: list[str]) -> int: + name = OUTPUT_SPEC.relative_to(REPO_ROOT) + if problems: + logger.error("Generated spec failed validation:") + for problem in problems: + logger.error(" %s", problem) + return 1 + + current = OUTPUT_SPEC.read_text() if OUTPUT_SPEC.exists() else "" + if current == rendered: + logger.info("%s is up to date", name) + return 0 + + logger.error( + "%s is out of date. Regenerate with: python3 %s", + name, + Path(__file__).name, + ) + diff = difflib.unified_diff( + current.splitlines(), + rendered.splitlines(), + fromfile=f"{name} (committed)", + tofile=f"{name} (generated)", + lineterm="", + n=2, + ) + for shown, line in enumerate(diff): + if shown >= 60: + logger.error(" ... (diff truncated)") + break + logger.error(" %s", line) + return 1 + + +def _report(counts, flagged, unmatched, normalized) -> None: + logger.info("Access levels applied:") + for level in (PUBLIC, AUTHENTICATED, CAMERA, ADMIN): + logger.info(" %-14s %d", level, counts.get(level, 0)) + logger.info(" %-14s %d", "total", sum(counts.values())) + + if normalized: + logger.info("\nStripped volatile timestamp defaults (%d):", len(normalized)) + for location, value in normalized: + logger.info(" %s = %s", location.lstrip("/"), value) + + if flagged: + logger.info("\nFlagged for manual confirmation (%d):", len(flagged)) + for item in flagged: + logger.info(" %-6s %s", item["method"], item["path"]) + logger.info(" -> %s (%s)", item["level"], item["flag"]) + + if unmatched: + logger.info( + "\nOperations with no classification (%d) [unexpected]:", len(unmatched) + ) + for method, path in unmatched: + logger.info(" %-6s %s", method, path) + + +if __name__ == "__main__": + sys.exit(main())