Storylinez LogoStorylinez
Documentation

Files API

/storage
27 endpoints

Endpoints for managing files and folders within an organization. This includes uploading files, organizing them into folders, retrieving file details and analysis results, searching, and managing storage usage.

Endpoint Base

https://api.storylinezads.com/storage

All endpoints in this section are relative to this base path. Use this prefix for all requests to the Files API.

File Upload & Processing

Endpoints related to the file upload workflow, from generating secure upload links to confirming uploads and triggering analysis.

Generate Upload Link - GET /storage/upload/create_link

Generates a secure, time-limited pre-signed URL for uploading a file directly to S3 storage. It also creates an internal record to track the upload.

Parameters:

  • org_id: The unique identifier for the organization where the file will be stored.
  • filename: The desired name for the file, including its extension. The extension must be one of the allowed types.
  • file_size: Optional. Estimated size of the file in bytes. If provided (> 0), a preliminary check against the organization's storage quota is performed.
  • folder_path: Optional. The logical folder path within the organization where the file should be placed upon completion. Defaults to the root folder ('/').
POST

Mark Upload Complete

/storage/upload/complete

Mark Upload Complete - POST /storage/upload/complete

Confirms that a file upload to the pre-signed URL was successful. This endpoint registers the file in the database, verifies its size, updates storage usage, and triggers the background analysis process.

Parameters:

  • org_id: The unique identifier for the organization. Must match the org_id associated with the upload record.
  • upload_id: The unique ID received from `/upload/create_link`. Preferred method for identifying the upload.
  • key: The S3 key (path) where the file was uploaded, received from `/upload/create_link`. Required if `upload_id` is not provided. Must start with 'userdata/'.
  • filename: Optional. Override the display name for the file. If omitted, uses the filename from the upload record.
  • mimetype: Optional. Specify the MIME type (e.g., 'video/mp4'). If omitted, it's guessed from the filename, defaulting to 'application/octet-stream'.
  • folder_path: Optional. Override the logical folder path for the file. If omitted, uses the path from the upload record. Path will be normalized.
  • context: Optional. Provide context to the AI about the file's content or purpose to improve analysis quality.
  • tags: Optional. Add tags for categorization or to guide AI focus during analysis.
  • brand_related_details: **Deprecated.** Use `company_details` or rely on `auto_company_details`. Provides brand context if `auto_company_details` is false.
  • company_details: Optional. Explicitly provide brand-related details for analysis. This is ignored if `auto_company_details` is true.
  • auto_company_details: If true (default), the system automatically fetches company details associated with the organization to provide brand context for analysis, overriding the `company_details` field.
  • company_details_id: Optional. Specify the ID of a particular company details profile to use when `auto_company_details` is true. If omitted, the organization's default profile is used.
  • deepthink: Optional. Enable deeper, more detailed AI analysis (may increase processing time).
  • overdrive: Optional. Use significantly more computational resources for the most thorough analysis possible (increases processing time and cost).
  • web_search: Optional. Allow the AI to perform web searches to gather additional context about entities identified in the file.
  • eco: Optional. Use a faster, lower-power analysis mode (may result in less detail).
  • temperature: Optional. Controls AI creativity (0.0=deterministic, 1.0=max creativity). Affects summaries, descriptions, etc.
  • analyze_audio: Optional. If true (default), audio tracks in video or audio files will be transcribed and analyzed. Set to false to skip audio analysis (e.g., for silent videos) and potentially reduce processing time.
  • advanced_detection: Optional. Enables richer scene/object detection pipelines. Leave true to capture the most metadata.
  • model: Optional. Select a specific analysis model alias. Allowed values: 'auto', 'storylinez-1-reasoning', 'storylinez-1-turbo', 'storylinez-1-lumina'. Supplying a concrete alias requires `eco=false`.
  • model_override: Deprecated. Legacy field for selecting analysis models; use `model` instead.
POST

Reprocess File

/storage/file/reprocess

Reprocess File - POST /storage/file/reprocess

Triggers a new analysis job for an existing file. This allows updating analysis parameters (like context, tags, or AI settings) and generating new results without re-uploading the file.

Parameters:

  • file_id: The unique identifier of the file to be reprocessed.
  • context: Optional. New context for the analysis. Overwrites previous context.
  • tags: Optional. New list of tags. Overwrites previous tags.
  • company_details: Optional. Explicitly provide new brand details. Ignored if `auto_company_details` is true.
  • auto_company_details: Optional. Change the setting for automatically fetching company details. If set to true, fetches details again.
  • company_details_id: Optional. Specify a different company details profile ID to use if `auto_company_details` is true.
  • deepthink: Optional. Change the enhanced analysis setting.
  • overdrive: Optional. Change the intensive processing setting.
  • web_search: Optional. Change the web search integration setting.
  • eco: Optional. Change the eco-friendly processing setting.
  • temperature: Optional. Change the AI creativity temperature (0.0-1.0).
  • analyze_audio: Optional. Change the setting for analyzing audio content.
POST

Import YouTube Download

/storage/youtube-import

Import YouTube Download - POST /storage/youtube-import

Import a previously downloaded YouTube asset into storage and optionally trigger analysis.

Parameters:

  • org_id: Organization ID that will own the imported file.
  • s3_key: Source S3 key produced by YouTube download processing.
  • title: Display title for the imported asset.
  • original_url: Original YouTube URL for attribution/tracing.
  • folder_path: Destination folder path in storage.
  • analyze: If true, starts analysis after import.
  • context: Optional analysis context.
  • tags: Optional tags for categorization.
  • analyze_audio: Analyze audio track if present.
  • advanced_detection: Enable enhanced detection pipeline.
  • trim_enabled: Optional trim toggle.
  • trim_start_seconds: Optional trim start time.
  • trim_end_seconds: Optional trim end time.

Folder Management

Endpoints for creating folders, browsing folder contents, and searching within folders.

GET

Get Folder Contents

/storage/folder/contents

Get Folder Contents - GET /storage/folder/contents

Retrieves a list of files and direct subfolders within a specified folder path. Can optionally retrieve files recursively from subfolders.

Parameters:

  • org_id: The unique identifier for the organization.
  • path: The folder path whose contents are to be retrieved. Defaults to the root folder ('/'). Path is automatically normalized.
  • recursive: If true, the `files` list will include files from the specified path *and* all its subfolders. The `folders` list always contains only direct subfolders of `path`.
  • detailed: If true, includes the full `analysis_data` and `analysis_params` objects for each file where processing is complete. Can significantly increase response size.
  • generate_thumbnail: If true (default), generates and includes temporary thumbnail URLs in the `urls` object for each file.
  • generate_streamable: If true, generates and includes temporary streamable URLs (e.g., for video playback) in the `urls` object.
  • generate_download: If true, generates and includes temporary download URLs (preferring processed versions) in the `urls` object.
  • include_protected: Optional. If true, includes internal system folders or files (rarely needed for typical use).
  • page: The page number for pagination. Must be >= 1.
  • page_size: Number of files per page. Must be between 1-200. Folders are not paginated.
  • sort_by: Field to sort files by. Valid values: 'upload_date', 'filename', 'size', 'rating'.
  • sort_direction: Sort direction. Valid values: 'desc' (descending) or 'asc' (ascending).
POST

Create Folder

/storage/folder/create

Create Folder - POST /storage/folder/create

Creates a new, empty folder within a specified parent folder.

Parameters:

  • org_id: The unique identifier for the organization where the folder will be created.
  • folder_name: The name for the new folder. Cannot contain '/' characters.
  • parent_path: The full path of the existing folder where the new folder should be created. Defaults to the root folder ('/'). Path is normalized.
GET

Search Files by Name

/storage/folder/search-by-name

Search Files by Name - GET /storage/folder/search-by-name

Performs a case-insensitive text search for files based on their filenames within a specified folder path. Can optionally search recursively through subfolders.

Parameters:

  • org_id: The unique identifier for the organization.
  • path: The folder path to search within. Defaults to the root folder ('/'). Path is normalized.
  • query: The text string to search for within filenames. The search is case-insensitive and matches any part of the filename.
  • recursive: If true, the search includes files in the specified path and all its subfolders.
  • detailed: If true (default), includes full file details (`analysis_data`, `analysis_params`) for matching files. Set to false for faster results with less data.
  • generate_thumbnail: If true (default), generates and includes temporary thumbnail URLs for matching files.
  • generate_streamable: If true, generates and includes temporary streamable URLs for matching files.
  • generate_download: If true, generates and includes temporary download URLs for matching files.
  • page: The page number for pagination. Must be >= 1.
  • page_size: Number of results per page. Must be between 1-200.
  • sort_by_rating: If true, sorts the files by their average rating. For search endpoints, this defaults to true to show the most relevant and highly-rated content first.
  • rating_sort_dir: Sort direction for rating-based sorting. Valid values: 'desc' (highest rated first) or 'asc' (lowest rated first). Only applies when sort_by_rating is true.
POST

Vector Search in Folder

/storage/folder/vector-search

Vector Search in Folder - POST /storage/folder/vector-search

Performs a semantic search using natural language queries to find files based on their content and metadata. Searches across vector embeddings generated during analysis.

Parameters:

  • org_id: The unique identifier for the organization. Results are filtered by this ID.
  • path: IMPORTANT: To search across ALL files in the organization, do NOT supply this parameter at all or provide an empty string. If a path is provided, the search will be restricted to only files in that folder path. Path is normalized.
  • detailed: If true (default), includes full file details (`analysis_data`, `analysis_params`) for matching files.
  • generate_thumbnail: If true (default), generates and includes temporary thumbnail URLs for matching files.
  • generate_streamable: If true, generates and includes temporary streamable URLs for matching files.
  • generate_download: If true, generates and includes temporary download URLs for matching files.
  • num_results: The maximum number of results to retrieve *per query* from the vector database before combining and ranking. Must be > 0.
  • similarity_threshold: The minimum similarity score (between 0.0 and 1.0) required for a result to be included. Higher values yield more relevant but potentially fewer results.
  • orientation: Optional. Filter video results by orientation. Valid values: 'landscape', 'portrait'. Only applies when searching video types.
  • file_types: Optional. Comma-separated list of media types to search within (e.g., 'video,image'). Valid types: 'all', 'video', 'audio', 'image'. Determines which vector collections are queried.
  • page: The page number for pagination. Must be >= 1.
  • page_size: Number of results per page. Must be between 1-200.
  • sort_by_rating: If true, sorts the files by their average rating after vector similarity ranking. For search endpoints, this defaults to true to show the most relevant and highly-rated content first.
  • rating_sort_dir: Sort direction for rating-based sorting. Valid values: 'desc' (highest rated first) or 'asc' (lowest rated first). Only applies when sort_by_rating is true.
  • queries: An array containing one or more natural language search queries (strings).
DELETE

Delete Folder

/storage/folder/delete

Delete Folder - DELETE /storage/folder/delete

Deletes a folder. Can optionally delete all files and subfolders contained within it recursively.

Parameters:

  • folder_id: The unique identifier of the folder to be deleted.
  • delete_contents: If true, recursively deletes all files and subfolders within this folder before deleting the folder itself. Defaults to false.
PUT

Rename Folder

/storage/folder/rename

Rename Folder - PUT /storage/folder/rename

Renames a folder. This operation also updates the paths of all contained files and subfolders recursively to reflect the new folder name.

Parameters:

  • folder_id: The unique identifier of the folder to rename.
  • new_name: The desired new name for the folder. Cannot contain '/' characters.
PUT

Move Folder

/storage/folder/move

Move Folder - PUT /storage/folder/move

Moves an existing folder to a different parent path without changing its folder_id.

Parameters:

  • folder_id: Folder identifier to move.
  • target_parent_path: Destination parent folder path.
GET

Get Folder Tree

/storage/tree

Get Folder Tree - GET /storage/tree

Generates and retrieves a hierarchical tree structure representing folders and files, starting from a specified root path.

Parameters:

  • org_id: The unique identifier for the organization.
  • path: The root path from which to build the tree. Defaults to the root folder ('/'). Path is normalized.
  • include_protected: Optional. If true, includes internal system folders or files (rarely needed).
GET

List Folders

/storage/folder/list

List Folders - GET /storage/folder/list

Retrieves a list of folder objects under a specified parent path. Can optionally list all descendant folders recursively.

Parameters:

  • org_id: The unique identifier for the organization.
  • path: The parent path whose child folders are to be listed. Defaults to the root folder ('/'). Path is normalized.
  • recursive: If true, includes all descendant folders at any depth below the specified `path`.
GET

Browse Folders (Paginated)

/storage/folders/browse

Browse Folders (Paginated) - GET /storage/folders/browse

List folder entries at a given path with server-side pagination and sorting.

Parameters:

  • org_id: Organization ID.
  • path: Folder path to browse.
  • page: Page number (>= 1).
  • page_size: Results per page (1-200).
  • sort_by: Sort field: name, created_at, updated_at.
  • sort_direction: Sort direction: asc or desc.

File Management

Endpoints for managing individual files, including deletion, renaming, moving, downloading, and retrieving analysis results.

DELETE

Delete File

/storage/file/delete

Delete File - DELETE /storage/file/delete

Permanently deletes a file, including its S3 object(s), associated analysis data, and vector embeddings. Reclaims storage space.

Parameters:

  • file_id: The unique identifier of the file to be deleted.
PUT

Rename File

/storage/file/rename

Rename File - PUT /storage/file/rename

Updates the display name (`filename`) of a file. This is a logical change and does not affect the file's S3 key or its physical storage location.

Parameters:

  • file_id: The unique identifier of the file to rename.
  • new_name: The desired new display name for the file, including the extension.
PUT

Move File

/storage/file/move

Move File - PUT /storage/file/move

Moves a file to a different logical folder within the organization by updating its `folder_path`. This does not change the file's physical S3 location.

Parameters:

  • file_id: The unique identifier of the file to move.
  • target_folder_path: The full path of the existing destination folder. Use '/' to move the file to the root folder. Path is normalized.

Generate Download Link - GET /storage/file/download

Generates a temporary, secure pre-signed URL for downloading a file. It prioritizes providing a link to a processed version if available, otherwise falls back to the original file.

Parameters:

  • file_id: The unique identifier of the file for which to generate a download link.
GET

Get File Analysis

/storage/file/analysis

Get File Analysis - GET /storage/file/analysis

Retrieves comprehensive details about a single file, including its metadata, current processing status, the parameters used for analysis, the analysis results (if completed), and generated URLs (thumbnail, streamable, download).

Parameters:

  • file_id: The unique identifier of the file whose analysis data is requested.
  • detailed: If true (default), includes the full `analysis_data` object containing detailed results (scenes, transcript, objects, etc.) if processing is complete. Set to false to omit this potentially large object.
  • generate_thumbnail: If true (default), generates and includes a temporary thumbnail URL in the `urls` object.
  • generate_streamable: If true (default), generates and includes a temporary streamable URL (e.g., for video playback) in the `urls` object.
  • generate_download: If true (default), generates and includes temporary download URLs (processed and original) in the `urls` object.
GET

Get Reference Video

/storage/reference/get

Get Reference Video - GET /storage/reference/get

Fetches a reference video by file_id with optional generated links and lightweight payload defaults.

Parameters:

  • file_id: Reference file identifier.
  • detailed: Include expanded metadata.
  • generate_thumbnail: Generate thumbnail link.
  • generate_streamable: Generate streamable link.
  • generate_download: Generate download link.
POST

Get Files by IDs

/storage/files/get_by_ids

Get Files by IDs - POST /storage/files/get_by_ids

Retrieves detailed information for multiple files simultaneously, based on a provided list of file IDs. Useful for batch operations.

Parameters:

  • org_id: The unique identifier for the organization. Files must belong to this organization.
  • detailed: If true, includes full file details (`analysis_data`, `analysis_params`) for retrieved files.
  • generate_thumbnail: If true (default), generates and includes temporary thumbnail URLs for retrieved files.
  • generate_streamable: If true, generates and includes temporary streamable URLs for retrieved files.
  • generate_download: If true, generates and includes temporary download URLs for retrieved files.
  • sort_by_rating: If true, sorts the files by their average rating instead of maintaining the input order. For direct file fetching, this defaults to false to preserve the requested order.
  • rating_sort_dir: Sort direction for rating-based sorting. Valid values: 'desc' (highest rated first) or 'asc' (lowest rated first). Only applies when sort_by_rating is true.
  • file_ids: An array containing the unique identifiers (`file_id`) of the files to retrieve. Maximum of 100 IDs per request.
GET

Download Original File

/storage/file/download/original

Download Original File - GET /storage/file/download/original

Generates a temporary, secure pre-signed URL specifically for downloading the original, unprocessed file exactly as it was uploaded.

Parameters:

  • file_id: The unique identifier of the file whose original version is requested.
POST

Rate File

/storage/file/rate

Rate File - POST /storage/file/rate

Allows users to rate a file on a scale of 1-5 stars. Updates existing rating if the user has already rated the file.

Parameters:

  • file_id: The unique identifier of the file to rate.
  • rating: The rating value (1-5 stars inclusive).
POST

Remove File Rating

/storage/file/remove_rating

Remove File Rating - POST /storage/file/remove_rating

Removes the authenticated user's rating from a file. Does not affect other users' ratings.

Parameters:

  • file_id: The unique identifier of the file to remove rating from.
GET

Get File Rating

/storage/file/get_rating

Get File Rating - GET /storage/file/get_rating

Retrieves rating information for a specific file, including average rating, total count, and the authenticated user's rating (if any).

Parameters:

  • file_id: The unique identifier of the file to get rating information for.

Storage Management

Endpoints related to monitoring storage and processing usage against subscription limits.

GET

Get Storage Usage

/storage/storage/usage

Get Storage Usage - GET /storage/storage/usage

Retrieves detailed information about the organization's current storage usage, storage limits, and content processing usage relative to their subscription plan.

Parameters:

  • org_id: The unique identifier for the organization whose usage is being queried.
GET

List Unused Files

/storage/files/unused

List Unused Files - GET /storage/files/unused

Returns files in an organization that are not attached to any project.

Parameters:

  • org_id: Organization ID.
  • detailed: Include expanded analysis fields.
  • generate_thumbnail: Generate thumbnail URLs.
  • generate_streamable: Generate streamable URLs.
  • generate_download: Generate download URLs.
  • page: Page number (>= 1).
  • page_size: Results per page (1-200).
  • sort_by: Sort by upload_date, filename, size, rating, updated_at, or created_at.
  • sort_direction: Sort direction: asc or desc.
  • cursor_value: Optional cursor for deep scans.
  • cursor_id: Optional cursor id for tie-breaking scans.
  • max_scan_batches: Safety cap for backend scan batches.