File API - davidmarsoni/llog GitHub Wiki
This page documents the File Management APIs, which handle both adding new content to the system and viewing/managing existing content.
The following endpoints handle adding new content to the system:
-
/files/add- Renders the page for adding new content -
/files/add/upload-document- Handles the upload and processing of document files (PDF, TXT, MD) -
/files/add/cache-notion- Handles caching content from a Notion page or database
Renders the page for adding new content.
QUERY: GET /files/add
ARGS: (Optional Query Parameters for preserving state across redirects)
- page: Current page number for pagination
- per_page: Items per page for pagination
- filter_title: Current title filter
- filter_type: Current type filter
RETURN: The rendered 'add_files.html' page.
Handles the upload and processing of document files (PDF, TXT, MD).
QUERY: POST /files/add/upload-document
ARGS (Form Data):
- document: The uploaded file
- document_name: (Optional) Custom name for the document
- folder_path: (Optional) Path of the folder to store the item in
ARGS (Query Parameters for redirect):
- page, per_page, filter_title, filter_type, folder: To preserve view state
RETURN: Redirects to `/files/view` with appropriate query parameters. Flashes success or error message.
Handles caching content from a Notion page or database.
QUERY: POST /files/add/cache-notion
ARGS (Form Data):
- page_id: ID of the Notion page (or database)
- database_id: (Optional) ID of the Notion database (takes precedence over page_id if both provided)
- custom_name: (Optional) Custom name for the Notion content
- folder_path: (Optional) Path of the folder to store the item in
ARGS (Query Parameters for redirect):
- page, per_page, filter_title, filter_type, folder: To preserve view state
RETURN: Redirects to `/files/view` with appropriate query parameters. Flashes success or error message.
The following endpoints handle viewing, refreshing, and managing existing content:
-
/files/view- Renders the page for viewing cached content (knowledge base) -
/files/view/delete/<path:filename>- Deletes a specific cached item (document or Notion content) -
/files/view/list-cached-content- API endpoint to get a list of cached items, primarily for dynamic updates -
/files/view/refresh-cache- Forces a refresh of the file index cache -
/files/view/refresh-item- Refreshes a single cached Notion page or database -
/files/view/move-item- Moves a cached item to a specified folder -
/files/view/filtered-content- Returns the filtered and paginated content table HTML, used for HTMX updates
Renders the page for viewing cached content (knowledge base).
QUERY: GET /files/view
ARGS: (Optional Query Parameters)
- page: Page number for pagination (default: 1)
- per_page: Items per page (default: 10)
- title: Filter content by title (substring match, case-insensitive)
- type: Filter content by type (e.g., 'pdf', 'page', 'database')
- folder: Filter content by folder path
RETURN: The rendered 'view_files.html' page with filtered and paginated content.
Deletes a specific cached item (document or Notion content).
QUERY: POST /files/view/delete/<path:file_id>
ARGS (URL Path):
- file_id: The unique ID or path of the item to delete (can contain slashes)
ARGS (Query Parameters for redirect):
- page, per_page, filter_title, filter_type, folder: To preserve view state
RETURN: Redirects to `/files/view` with potentially adjusted pagination and preserved filters. Flashes success or error message.
API endpoint to get a list of cached items, primarily for dynamic updates.
QUERY: GET /files/view/list-cached-content
ARGS (Query Parameters):
- folder: (Optional) Filter items by folder path
RETURN: JSON response containing:
- cached_items: A list of dictionaries, each representing a cached item with its metadata.
- is_loading: Boolean indicating if the cache is currently being loaded/refreshed.
Forces a refresh of the file index cache.
QUERY: POST /files/view/refresh-cache
ARGS (Query Parameters for redirect):
- page, per_page, filter_title, filter_type, folder: To preserve view state
RETURN: Redirects to `/files/view` with preserved filters. Flashes success or error message.
Refreshes a single cached Notion page or database.
QUERY: POST /files/view/refresh-item
ARGS (Form Data):
- item_id: Internal UUID of the item
- item_notion_id: Actual Notion ID of the page or database
- item_type: 'page' or 'database'
- custom_name: (Optional) Custom name for the item
ARGS (Query Parameters for redirect):
- page, per_page, filter_title, filter_type, folder: To preserve view state
RETURN (HTMX Request): JSON response with status ('success' or 'error'), message, and title.
RETURN (Regular Request): Redirects to `/files/view` with preserved filters. Flashes success or error message.
Moves a cached item to a specified folder.
QUERY: POST /files/view/move-item
ARGS (Form Data):
- item_id: The ID of the item to move
- folder_path: The destination folder path (empty string for root)
ARGS (Query Parameters for redirect/HTMX update):
- page, per_page, filter_title, filter_type, folder: To preserve view state
RETURN (HTMX Request): Renders and returns the 'components/content_table.html' template with updated content for the *current* folder.
RETURN (Regular Request): Redirects to `/files/view` targeting the *destination* folder. Flashes success or error message.
Returns the filtered and paginated content table HTML, used for HTMX updates.
QUERY: GET /files/view/filtered-content
ARGS (Query Parameters):
- page: Page number for pagination (default: 1)
- per_page: Items per page (default: 10)
- title: Filter content by title
- type: Filter content by type
- folder: Filter content by folder path
RETURN: Renders and returns the 'components/content_table.html' template with filtered/paginated data.
Checks if the background cache loading process is active.
QUERY: GET /files/view/check-content-loading
RETURN: JSON response:
- is_loading: Boolean indicating if the cache is currently being loaded/refreshed.