{ "openapi": "3.0.0", "info": { "title": "Cloudglue API", "description": "API for Cloudglue", "license": { "name": "Apache License 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "0.7.33" }, "servers": [ { "url": "https://api.cloudglue.dev/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/tags": { "post": { "tags": ["Tags"], "summary": "Create a new tag", "operationId": "createTag", "description": "Create a new tag", "requestBody": { "description": "Tag creation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoTagRequest" } } }, "required": true }, "responses": { "200": { "description": "Tag created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTag" } } } }, "400": { "description": "Invalid request or missing required label/value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (total tags per file or segment) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Tags"], "summary": "List all tags", "operationId": "listTags", "description": "List all tags", "parameters": [ { "name": "type", "in": "query", "description": "Filter tags by type: 'file' or 'segment'", "required": false, "schema": { "type": "string", "enum": ["file", "segment"] } }, { "name": "limit", "in": "query", "description": "Maximum number of tags to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of tags to skip", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of tags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVideoTagsResponse" } } } } } } }, "/tags/{tag_id}": { "get": { "tags": ["Tags"], "summary": "Get a tag", "operationId": "getTag", "description": "Get a tag", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "description": "The ID of the tag", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTag" } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Tags"], "summary": "Delete a tag", "operationId": "deleteTag", "description": "Delete a tag", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "description": "The ID of the tag", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tag deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the tag" } }, "required": ["id"] } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": ["Tags"], "summary": "Update a tag", "operationId": "updateTag", "description": "Update a tag", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "description": "The ID of the tag", "schema": { "type": "string" } } ], "requestBody": { "description": "Tag update parameters. At least one of label or value is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVideoTagRequest" } } }, "required": true }, "responses": { "200": { "description": "Tag updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoTag" } } } } } } }, "/extract": { "post": { "tags": ["Extract"], "summary": "Create a new extract job", "operationId": "createExtract", "description": "Extract structured data from a video", "requestBody": { "description": "Extract job parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewExtract" } } }, "required": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Extract" } } } }, "400": { "description": "Invalid request or missing required prompt/schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly extract jobs, or the file limits when given a new URL) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Extract job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Extract"], "summary": "List all extract jobs", "operationId": "listExtracts", "description": "List all extract jobs with optional filtering", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of extract jobs to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of extract jobs to skip", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter extract jobs by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ] } }, { "name": "created_before", "in": "query", "description": "Filter extract jobs created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter extract jobs created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "url", "in": "query", "description": "Filter extract jobs by the input URL used for extraction", "required": false, "schema": { "type": "string" } }, { "name": "include_data", "in": "query", "description": "Include the data in the response. If false, the response will only include the job information and not the data to minimize the response size.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of extract jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractList" } } } }, "400": { "description": "Invalid request or extract config requires at least one option enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Extract job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/extract/{job_id}": { "get": { "tags": ["Extract"], "summary": "Retrieve the current state of an extraction job", "operationId": "getExtract", "description": "Retrieve the current state of an extraction job. Results are paginated with a default limit of 50 segment entities per request (maximum 100). Use limit and offset parameters to paginate through all segment entities.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The unique identifier of the extraction job", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of segment entities to return", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Number of segment entities to skip", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "include_thumbnails", "in": "query", "description": "When true, include a file-level thumbnail_url in the data object and a per-segment thumbnail_url on each segment entity", "required": false, "schema": { "type": "boolean" } }, { "name": "include_chapters", "in": "query", "description": "Include narrative chapters in the response (when segmentation strategy is 'narrative')", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_shots", "in": "query", "description": "Include shot boundaries in the response (when segmentation strategy is 'shot-detector')", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response with job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Extract" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Extract"], "summary": "Delete an extraction job", "operationId": "deleteExtract", "description": "Delete an extraction job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The unique identifier of the extraction job", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the extract job" } }, "required": ["id"] } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files": { "post": { "tags": ["Files"], "summary": "Upload a video, audio, or image file that can be used with Cloudglue services", "operationId": "uploadFile", "description": "Upload a video, audio, or image file that can be used with Cloudglue services", "requestBody": { "description": "Upload a video, audio, or image file", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FileUpload" } } }, "required": true }, "responses": { "200": { "description": "Successful file upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid request, missing file, invalid metadata, or video duration exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly uploads, total duration, total file size, or total files) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported file type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Files"], "summary": "List files that have been uploaded to Cloudglue", "operationId": "listFiles", "description": "List files that have been uploaded to Cloudglue", "parameters": [ { "name": "status", "in": "query", "description": "Filter files by processing status", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ] } }, { "name": "created_before", "in": "query", "description": "Filter files created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter files created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Limit the number of files to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of files to skip", "required": false, "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Order the files by a specific field", "required": false, "schema": { "type": "string", "enum": ["created_at", "filename"] } }, { "name": "sort", "in": "query", "description": "Sort the files in ascending or descending order", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "filter", "in": "query", "description": "JSON string containing filter criteria to constrain file search results. This is the JSON string version of the SearchFilter object used in the search API.\n\n**Supported Filter Types:**\n\n• **metadata** - Filter by file metadata using JSON path expressions (e.g., 'metadata.speaker', 'metadata.category.subcategory')\n• **video_info** - Filter by video information properties. Supports optional `scope` ('file' or 'segment', default 'file')\n - `duration_seconds` - Video/segment duration in seconds (supports file and segment scope)\n - `has_audio` - Whether the video has audio (true/false, file scope only)\n\n• **file** - Filter by file properties\n - `filename` - File name (string)\n - `uri` - File URI (string)\n - `id` - File ID (UUID string)\n - `created_at` - Creation timestamp (ISO 8601 string)\n - `bytes` - File size in bytes (number)\n\n**Supported Operators:**\n• **Equal** - Exact match (requires valueText)\n• **NotEqual** - Not equal to value (requires valueText)\n• **LessThan** - Less than value (requires valueText)\n• **GreaterThan** - Greater than value (requires valueText)\n• **Like** - Case-insensitive pattern matching with wildcards (requires valueText)\n• **In** - Value is in array (requires valueTextArray)\n• **ContainsAny** - Array contains any of the values (requires valueTextArray)\n• **ContainsAll** - Array contains all of the values (requires valueTextArray)\n\n**Examples:**\n\n**Metadata filtering:**\n```json\n{\"metadata\":[{\"path\":\"speaker\",\"operator\":\"Like\",\"valueText\":\"YO%\"}]}\n```\n\n**Video info filtering (file-level):**\n```json\n{\"video_info\":[{\"path\":\"duration_seconds\",\"operator\":\"GreaterThan\",\"valueText\":\"60\"}]}\n```\n\n**Video info filtering (segment-level):**\n```json\n{\"video_info\":[{\"path\":\"duration_seconds\",\"operator\":\"LessThan\",\"valueText\":\"30\",\"scope\":\"segment\"}]}\n```\n\n**File property filtering:**\n```json\n{\"file\":[{\"path\":\"filename\",\"operator\":\"Like\",\"valueText\":\"%.mp4\"}]}\n```\n```json\n{\"file\":[{\"path\":\"bytes\",\"operator\":\"GreaterThan\",\"valueText\":\"1048576\"}]}\n```\n```json\n{\"file\":[{\"path\":\"created_at\",\"operator\":\"GreaterThan\",\"valueText\":\"2024-01-01T00:00:00Z\"}]}\n```\n\n**Combined filtering:**\n```json\n{\"metadata\":[{\"path\":\"speaker\",\"operator\":\"Equal\",\"valueText\":\"John\"}],\"video_info\":[{\"path\":\"has_audio\",\"operator\":\"Equal\",\"valueText\":\"true\"}],\"file\":[{\"path\":\"filename\",\"operator\":\"Like\",\"valueText\":\"%.mp4\"}]}\n```", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileList" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/sync": { "post": { "tags": ["Files"], "summary": "Sync a public URL into a file", "operationId": "syncFileFromUrl", "description": "Materialize a publicly accessible URL into a Cloudglue file without a data connector or a collection. Accepts direct http(s) video/audio file URLs (e.g. `.mp4`), public Dropbox share links, TikTok video URLs, and Loom share URLs. Idempotent: syncing the same URL returns the existing file. YouTube URLs are not supported here — add them to a collection via the add-media endpoint instead. Connector-native URIs (e.g. `s3://`, `gs://`, `gdrive://`, Zoom/Gong/Recall/Grain links) require the matching data connector — use POST /data-connectors/{id}/sync.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Publicly accessible URL to sync. Accepted forms — direct http(s) file URL: `https://example.com/video.mp4` · Dropbox share link: `https://www.dropbox.com/scl/fi/...` or `https://www.dropbox.com/s/...` · TikTok: `https://www.tiktok.com/@user/video/` (and `vm.tiktok.com`/`vt.tiktok.com` short links) · Loom: `https://www.loom.com/share/`.", "example": "https://example.com/video.mp4" }, "metadata": { "type": "object", "description": "Optional metadata to associate with the file. Ignored if the URL was already synced (the existing file is returned unchanged).", "additionalProperties": true }, "enable_segment_thumbnails": { "type": "boolean", "description": "Whether to generate per-segment thumbnails for the file. Defaults to true, matching file upload.", "default": true } }, "required": ["url"] } } } }, "responses": { "200": { "description": "The synced file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Bad request (e.g. an unsupported URL such as YouTube or a connector-native URI, a page link from an unsupported host, a file exceeding size or duration limits, or a URL that does not serve a media file)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance (TikTok URLs consume scrape credits)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The source file is not accessible (e.g. a login-gated, expired, or restricted share link). Also returned when a usage limit is reached (monthly uploads, total duration, total file size, or total files) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The URL was not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The URL does not serve a supported video or audio content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_id}": { "get": { "tags": ["Files"], "summary": "Retrieve details about a specific file", "operationId": "getFile", "description": "Retrieve details about a specific file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Files"], "summary": "Delete a file", "operationId": "deleteFile", "description": "Delete a file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDelete" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": ["Files"], "summary": "Update a file", "operationId": "updateFile", "description": "Update a file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to update", "schema": { "type": "string" } } ], "requestBody": { "description": "File update parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successful file update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid request or malformed file update parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_id}/sync": { "post": { "tags": ["Files"], "summary": "Refresh a file's connector source metadata", "operationId": "syncFileSourceMetadata", "description": "Re-fetches the file's source_metadata live from its data connector (google-drive, dropbox, zoom, gong, recall, grain, or iconik) and updates the stored value. If the file belongs to any metadata collections, their search documents are re-indexed with the refreshed metadata. For iconik files without a thumbnail, the asset's poster keyframe is also copied and set as the file's thumbnail_url. Works for both metadata-only files and fully ingested connector files. Free — no media is downloaded or processed.", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to sync", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "File with refreshed source metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "File has no connector URI, the source does not support metadata lookup, or the account has no connector of that type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_id}/segmentations": { "post": { "tags": ["Files"], "summary": "Create a new segmentation for a file", "operationId": "createFileSegmentation", "description": "Create a new segmentation for a file using the specified segmentation configuration", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to segment", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Segmentation configuration", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SegmentationConfig" } ], "type": "object", "properties": { "thumbnails_config": { "$ref": "#/components/schemas/ThumbnailsConfig", "description": "Configuration for segment thumbnails. Optional." } }, "description": "Segmentation configuration (root level) with optional thumbnails configuration." } } }, "required": true }, "responses": { "200": { "description": "Segmentation created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segmentation" } } } }, "400": { "description": "Invalid request or file duration is less than window size", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Files"], "summary": "List segmentations for a file", "operationId": "listFileSegmentations", "description": "List all segmentations for a specific file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of segmentations to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the list", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of segmentations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentationList" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_id}/thumbnails": { "get": { "tags": ["Files", "Thumbnails"], "summary": "Get thumbnails for a file", "operationId": "getThumbnails", "description": "Get all thumbnails for a file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } }, { "name": "is_default", "in": "query", "description": "Filter thumbnails by default status. If true, will only return the default thumbnail for the file", "required": false, "schema": { "type": "boolean" } }, { "name": "segmentation_id", "in": "query", "description": "Filter thumbnails by segmentation ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of thumbnails to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the list", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "type", "in": "query", "description": "Filter thumbnails by type", "required": false, "schema": { "$ref": "#/components/schemas/ThumbnailType" } } ], "responses": { "200": { "description": "List of thumbnails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThumbnailList" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_id}/tags": { "get": { "tags": ["Files", "Tags"], "summary": "List tags for a file", "operationId": "listFileTags", "description": "List all tags for a specific file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of tags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVideoTagsResponse" } } } } } } }, "/files/{file_id}/segments": { "get": { "tags": ["Files", "File Segments"], "summary": "List file segments", "operationId": "listFileSegments", "description": "List all segments for a specific file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } }, { "name": "start_time_after", "in": "query", "description": "Filter segments by start time", "required": false, "schema": { "type": "number", "minimum": 0 } }, { "name": "end_time_before", "in": "query", "description": "Filter segments by end time", "required": false, "schema": { "type": "number", "minimum": 0 } }, { "name": "min_duration", "in": "query", "description": "Filter segments with duration greater than or equal to this value (in seconds)", "required": false, "schema": { "type": "number", "minimum": 0 } }, { "name": "max_duration", "in": "query", "description": "Filter segments with duration less than or equal to this value (in seconds). Must be greater than or equal to min_duration when both are provided.", "required": false, "schema": { "type": "number", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Number of segments to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the list", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "400": { "description": "Invalid query parameters (e.g., min_duration > max_duration, start_time_after >= end_time_before)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "List of segments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileSegmentListResponse" } } } } } } }, "/files/{file_id}/segments/{segment_id}": { "get": { "tags": ["Files", "File Segments"], "summary": "Get a file segment", "operationId": "getFileSegment", "description": "Get a file segment", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the segment", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "File segment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileSegment" } } } }, "404": { "description": "File segment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": ["Files", "File Segments"], "summary": "Update a file segment", "operationId": "updateFileSegment", "description": "Update a file segment", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the segment", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "File segment update parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "description": "The user defined metadata for the segment. Nullable" } } } } } }, "responses": { "200": { "description": "File segment updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileSegment" } } } }, "400": { "description": "Invalid request or malformed file segment update parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File segment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_id}/segments/{segment_id}/tags": { "get": { "tags": ["Files", "File Segments", "Tags"], "summary": "List tags for a file segment", "operationId": "listFileSegmentTags", "description": "List all tags for a specific file segment", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the segment", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of tags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVideoTagsResponse" } } } } } } }, "/files/{file_id}/segments/{segment_id}/describes": { "get": { "tags": ["Files", "File Segments", "Describe"], "summary": "List describes for a file segment", "operationId": "listFileSegmentDescribes", "description": "List all describe outputs for a specific file segment", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the segment", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by job status. Supports comma-separated values (e.g., 'completed,processing'). Defaults to 'completed'.", "required": false, "schema": { "type": "string" } }, { "name": "response_format", "in": "query", "description": "Output format for the describe data", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } }, { "name": "include_data", "in": "query", "description": "Include the describe data in the response. If false, only job information is returned. Defaults to false.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Number of items to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the list", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of describes for the segment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentDescribeListResponse" } } } }, "404": { "description": "File or segment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_id}/segments/{segment_id}/describes/{job_id}": { "get": { "tags": ["Files", "File Segments", "Describe"], "summary": "Get describe for a file segment", "operationId": "getFileSegmentDescribe", "description": "Get a specific describe output for a file segment by job ID", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the segment", "schema": { "type": "string", "format": "uuid" } }, { "name": "job_id", "in": "path", "required": true, "description": "The ID of the describe job", "schema": { "type": "string", "format": "uuid" } }, { "name": "response_format", "in": "query", "description": "Output format for the describe data", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } } ], "responses": { "200": { "description": "Describe for the segment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentDescribe" } } } }, "404": { "description": "File, segment, or describe job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections": { "post": { "tags": ["Collections"], "summary": "Create a new collection to organize and process video files", "operationId": "createCollection", "description": "Create a new collection to organize and process video files. Collections are used to group files together and process them in a consistent way.", "requestBody": { "description": "Collection creation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewCollection" } } }, "required": true }, "responses": { "200": { "description": "Successful collection creation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "description": "Invalid request or malformed YouTube URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (total collections) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Collection name already exists for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Collections"], "summary": "List all collections", "operationId": "listCollections", "description": "List all collections", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of collections to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of collections to skip", "required": false, "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Order the collections by a specific field", "required": false, "schema": { "type": "string", "enum": ["name", "created_at"] } }, { "name": "sort", "in": "query", "description": "Sort the collections in ascending or descending order", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "collection_type", "in": "query", "description": "Filter collections by type", "required": false, "schema": { "type": "string", "enum": [ "media-descriptions", "entities", "rich-transcripts", "face-analysis", "metadata", "moments" ] } }, { "name": "created_after", "in": "query", "description": "Filter collections created after this date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Filter collections created before this date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A list of collections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionList" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}": { "get": { "tags": ["Collections"], "summary": "Retrieve details about a specific collection", "operationId": "getCollection", "description": "Retrieve details about a specific collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collection details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Collections"], "summary": "Delete a collection", "operationId": "deleteCollection", "description": "Delete a collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionDelete" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": ["Collections"], "summary": "Update a collection", "operationId": "updateCollection", "description": "Update a collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection to update", "schema": { "type": "string" } } ], "requestBody": { "description": "Collection update parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successful collection update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/videos": { "post": { "tags": ["Collections"], "summary": "[Deprecated] Add a video to a collection", "operationId": "addVideo", "description": "**DEPRECATED: Use POST /collections/\\{collection_id\\}/media instead.**\n\nAdd a video to a collection. This endpoint is deprecated - use the /media endpoint which supports both video and audio files.", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection to add the video file to", "schema": { "type": "string" } } ], "requestBody": { "description": "File association parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCollectionFile" } } }, "required": true }, "responses": { "200": { "description": "Successful file addition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionFile" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (files per collection, or the file limits when adding by URL) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "deprecated": true }, "get": { "tags": ["Collections"], "summary": "List all files in a collection", "operationId": "listVideos", "description": "List all files in a collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of files to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of files to skip", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by processing status", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ] } }, { "name": "added_before", "in": "query", "description": "Filter files added before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "added_after", "in": "query", "description": "Filter files added after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "order", "in": "query", "description": "Order the files by a specific field", "required": false, "schema": { "type": "string", "enum": ["added_at", "filename"] } }, { "name": "sort", "in": "query", "description": "Sort the files in ascending or descending order", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "filter", "in": "query", "description": "JSON string containing filter criteria to constrain file search results. This is the JSON string version of the SearchFilter object used in the search API.\n\n**Supported Filter Types:**\n\n• **metadata** - Filter by file metadata using JSON path expressions (e.g., 'metadata.speaker', 'metadata.category.subcategory')\n• **video_info** - Filter by video information properties. Supports optional `scope` ('file' or 'segment', default 'file')\n - `duration_seconds` - Video/segment duration in seconds (supports file and segment scope)\n - `has_audio` - Whether the video has audio (true/false, file scope only)\n\n• **file** - Filter by file properties\n - `filename` - File name (string)\n - `uri` - File URI (string)\n - `id` - File ID (UUID string)\n - `created_at` - Creation timestamp (ISO 8601 string)\n - `bytes` - File size in bytes (number)\n\n**Supported Operators:**\n• **Equal** - Exact match (requires valueText)\n• **NotEqual** - Not equal to value (requires valueText)\n• **LessThan** - Less than value (requires valueText)\n• **GreaterThan** - Greater than value (requires valueText)\n• **Like** - Case-insensitive pattern matching with wildcards (requires valueText)\n• **In** - Value is in array (requires valueTextArray)\n• **ContainsAny** - Array contains any of the values (requires valueTextArray)\n• **ContainsAll** - Array contains all of the values (requires valueTextArray)\n\n**Examples:**\n\n**Metadata filtering:**\n```json\n{\"metadata\":[{\"path\":\"speaker\",\"operator\":\"Like\",\"valueText\":\"YO%\"}]}\n```\n\n**Video info filtering (file-level):**\n```json\n{\"video_info\":[{\"path\":\"duration_seconds\",\"operator\":\"GreaterThan\",\"valueText\":\"60\"}]}\n```\n\n**Video info filtering (segment-level):**\n```json\n{\"video_info\":[{\"path\":\"duration_seconds\",\"operator\":\"LessThan\",\"valueText\":\"30\",\"scope\":\"segment\"}]}\n```\n\n**File property filtering:**\n```json\n{\"file\":[{\"path\":\"filename\",\"operator\":\"Like\",\"valueText\":\"%.mp4\"}]}\n```\n```json\n{\"file\":[{\"path\":\"bytes\",\"operator\":\"GreaterThan\",\"valueText\":\"1048576\"}]}\n```\n```json\n{\"file\":[{\"path\":\"created_at\",\"operator\":\"GreaterThan\",\"valueText\":\"2024-01-01T00:00:00Z\"}]}\n```\n\n**Combined filtering:**\n```json\n{\"metadata\":[{\"path\":\"speaker\",\"operator\":\"Equal\",\"valueText\":\"John\"}],\"video_info\":[{\"path\":\"has_audio\",\"operator\":\"Equal\",\"valueText\":\"true\"}],\"file\":[{\"path\":\"filename\",\"operator\":\"Like\",\"valueText\":\"%.mp4\"}]}\n```", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of files in the collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionFileList" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/videos/{file_id}": { "get": { "tags": ["Collections"], "summary": "Retrieve information about a specific video file in a collection", "operationId": "getVideo", "description": "Retrieve information about a specific video file in a collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File details within the collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionFile" } } } }, "404": { "description": "Collection or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Collections"], "summary": "Remove a video file from a collection", "operationId": "deleteVideo", "description": "Remove a video file from a collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to remove", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful removal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionFileDelete" } } } }, "404": { "description": "Collection or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/videos/{file_id}/entities": { "get": { "tags": ["Collections"], "summary": "Retrieve extracted entities for a specific file in a collection", "operationId": "getEntities", "description": "Retrieve extracted entities for a specific file in a collection. Results are paginated with a default limit of 50 segment entities per request (maximum 100). Use limit and offset parameters to paginate through all results. This API is only available when the collection is created with collection_type 'entities'", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of segment entities to return", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Number of segment entities to skip", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "include_thumbnails", "in": "query", "description": "When true, include a file-level thumbnail_url in the response and a per-segment thumbnail_url on each segment entity", "required": false, "schema": { "type": "boolean" } }, { "name": "include_chapters", "in": "query", "description": "Include narrative chapters in the response (when segmentation strategy is 'narrative')", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_shots", "in": "query", "description": "Include shot boundaries in the response (when segmentation strategy is 'shot-detector')", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "File entities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileEntities" } } } }, "400": { "description": "Collection type is not 'entities'", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/videos/{file_id}/rich-transcripts": { "get": { "tags": ["Collections"], "summary": "Retrieve rich transcription data for a specific file in a collection", "operationId": "getTranscripts", "description": "Retrieve rich transcription data for a specific file in a collection. This API is only available when the a collection is created with collection_type 'rich-transcripts'", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string" } }, { "name": "response_format", "in": "query", "description": "Format for the response", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } }, { "name": "start_time_seconds", "in": "query", "description": "Start time in seconds to filter out results by", "required": false, "schema": { "type": "number" } }, { "name": "end_time_seconds", "in": "query", "description": "End time in seconds to filter out results by", "required": false, "schema": { "type": "number" } }, { "name": "modalities", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ModalitiesSchema" } }, { "name": "include_word_timestamps", "in": "query", "description": "When true, include a words array on each speech entry with word-level start_time and end_time. Not available for YouTube sources. Only applies when response_format=json.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_metadata", "in": "query", "description": "Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Rich transcription data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RichTranscript" } } } }, "400": { "description": "Collection type is not 'rich-transcripts'", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/youtube": { "post": { "tags": ["Collections"], "summary": "Add a YouTube video to a collection", "operationId": "addYouTubeVideo", "description": "Add a YouTube video to a collection by URL", "deprecated": true, "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection to add the YouTube video to", "schema": { "type": "string" } } ], "requestBody": { "description": "YouTube video URL parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddYouTubeCollectionFile" } } }, "required": true }, "responses": { "200": { "description": "Successful video addition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionFile" } } } }, "400": { "description": "Invalid request or YouTube URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/entities": { "get": { "tags": ["Collections"], "summary": "List all extracted entities for files in a collection", "operationId": "listCollectionEntities", "description": "List all extracted entities for files in a collection. This API is only available when a collection is created with collection_type 'entities'", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of files to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of files to skip", "required": false, "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Order the files by a specific field", "required": false, "schema": { "type": "string", "enum": ["added_at", "filename"] } }, { "name": "sort", "in": "query", "description": "Sort the files in ascending or descending order", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "added_before", "in": "query", "description": "Filter files added before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "added_after", "in": "query", "description": "Filter files added after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "A list of file entities in the collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionEntitiesList" } } } }, "400": { "description": "Collection type is not 'entities'", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/rich-transcripts": { "get": { "tags": ["Collections"], "summary": "List all rich transcription data for files in a collection", "operationId": "listCollectionRichTranscripts", "description": "List all rich transcription data for files in a collection. This API is only available when a collection is created with collection_type 'rich-transcripts'", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of files to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of files to skip", "required": false, "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Order the files by a specific field", "required": false, "schema": { "type": "string", "enum": ["added_at", "filename"] } }, { "name": "sort", "in": "query", "description": "Sort the files in ascending or descending order", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "added_before", "in": "query", "description": "Filter files added before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "added_after", "in": "query", "description": "Filter files added after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "response_format", "in": "query", "description": "Format for the response", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } }, { "name": "modalities", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ModalitiesSchema" } }, { "name": "include_metadata", "in": "query", "description": "Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A list of rich transcription data in the collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionRichTranscriptsList" } } } }, "400": { "description": "Collection type is not 'rich-transcripts'", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/media-descriptions": { "get": { "tags": ["Collections"], "summary": "List all media description data for files in a collection", "operationId": "listCollectionMediaDescriptions", "description": "List all media description data for files in a collection. This API is only available when a collection is created with collection_type 'media-descriptions'", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of files to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of files to skip", "required": false, "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Order the files by a specific field", "required": false, "schema": { "type": "string", "enum": ["added_at", "filename"] } }, { "name": "sort", "in": "query", "description": "Sort the files in ascending or descending order", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } }, { "name": "added_before", "in": "query", "description": "Filter files added before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "added_after", "in": "query", "description": "Filter files added after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "response_format", "in": "query", "description": "Format for the response", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } }, { "name": "modalities", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ModalitiesSchema" } }, { "name": "include_metadata", "in": "query", "description": "Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A list of media description data in the collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionMediaDescriptionsList" } } } }, "400": { "description": "Collection type is not 'media-descriptions'", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/videos/{file_id}/media-descriptions": { "get": { "tags": ["Collections"], "summary": "Retrieve media description data for a specific file in a collection", "operationId": "getMediaDescriptions", "description": "Retrieve media description data for a specific file in a collection. This API is only available when the collection is created with collection_type 'media-descriptions'", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string" } }, { "name": "response_format", "in": "query", "description": "Format for the response", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } }, { "name": "start_time_seconds", "in": "query", "description": "Start time in seconds to filter out results by", "required": false, "schema": { "type": "number" } }, { "name": "end_time_seconds", "in": "query", "description": "End time in seconds to filter out results by", "required": false, "schema": { "type": "number" } }, { "name": "modalities", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ModalitiesSchema" } }, { "name": "include_thumbnails", "in": "query", "description": "When true, include a file-level thumbnail_url on the response and per-segment thumbnail_url on each segment_summary entry", "required": false, "schema": { "type": "boolean" } }, { "name": "include_word_timestamps", "in": "query", "description": "When true, include a words array on each speech entry with word-level start_time and end_time. Not available for YouTube sources. Only applies when response_format=json.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_chapters", "in": "query", "description": "Include narrative chapters in the response (when segmentation strategy is 'narrative')", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_shots", "in": "query", "description": "Include shot boundaries in the response (when segmentation strategy is 'shot-detector')", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_metadata", "in": "query", "description": "Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Media description data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaDescription" } } } }, "400": { "description": "Collection type is not 'media-descriptions'", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chat/completions": { "post": { "tags": ["Chat"], "summary": "Generate a model response to a conversation that can include references to video content", "operationId": "createCompletion", "description": "Generate a model response to a conversation that can include references to video content", "requestBody": { "description": "Chat completion parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly or daily chat completions) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collections not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Chat"], "summary": "List all chat completions", "operationId": "listChatCompletions", "description": "List all chat completions with optional filtering", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of chat completions to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of chat completions to skip", "required": false, "schema": { "type": "integer" } }, { "name": "created_before", "in": "query", "description": "Filter chat completions created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter chat completions created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "A list of chat completions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionList" } } } } } } }, "/chat/completions/{id}": { "get": { "tags": ["Chat"], "summary": "Retrieve a chat completion", "operationId": "getChatCompletion", "description": "Retrieve a chat completion", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the chat completion", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } } }, "404": { "description": "Chat completion not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transcribe": { "post": { "tags": ["Transcribe"], "summary": "Create a new transcription job", "operationId": "createTranscribe", "description": "Creates a new transcription job for video content.\n\nNote: For most use cases, you should use the `/describe` endpoint instead. This API will be deprecated in the future and only supports speech level understanding.", "requestBody": { "description": "Transcription job parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewTranscribe" } } }, "required": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcribe" } } } }, "400": { "description": "Invalid request or missing required url/file_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly describe jobs, or the file limits when given a new URL) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "509": { "description": "Monthly transcription jobs limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Transcribe"], "summary": "List all transcription jobs", "operationId": "listTranscribes", "description": "List all transcription jobs with optional filtering", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of transcription jobs to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of transcription jobs to skip", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter transcription jobs by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ] } }, { "name": "created_before", "in": "query", "description": "Filter transcription jobs created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter transcription jobs created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "url", "in": "query", "description": "Filter transcription jobs by the input URL used for transcription", "required": false, "schema": { "type": "string" } }, { "name": "response_format", "in": "query", "description": "Format for the response", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } }, { "name": "include_metadata", "in": "query", "description": "Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A list of transcription jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscribeList" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transcribe/{job_id}": { "get": { "tags": ["Transcribe"], "summary": "Retrieve the current state of a transcription job", "operationId": "getTranscribe", "description": "Retrieve the current state of a transcription job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The unique identifier of the transcription job", "schema": { "type": "string" } }, { "name": "response_format", "in": "query", "description": "Format for the response", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } }, { "name": "include_metadata", "in": "query", "description": "Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response with job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcribe" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/describe": { "post": { "tags": ["Describe"], "summary": "Create a new media description job", "operationId": "createDescribe", "description": "Get a comprehensive multimodal description of a video", "requestBody": { "description": "Media description job parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewDescribe" } } }, "required": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Describe" } } } }, "400": { "description": "Invalid request or missing required url/file_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly describe jobs, or the file limits when given a new URL) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "509": { "description": "Monthly description jobs limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Describe"], "summary": "List all media description jobs", "operationId": "listDescribes", "description": "List all media description jobs with optional filtering", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of description jobs to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of description jobs to skip", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter description jobs by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ] } }, { "name": "created_before", "in": "query", "description": "Filter description jobs created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter description jobs created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "url", "in": "query", "description": "Filter description jobs by the input URL used for description", "required": false, "schema": { "type": "string" } }, { "name": "response_format", "in": "query", "description": "Format for the response", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } }, { "name": "include_data", "in": "query", "description": "Include the data in the response. If false, the response will only include the job information and not the data to minimize the response size.", "required": false, "schema": { "type": "boolean" } }, { "name": "modalities", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ModalitiesSchema" } }, { "name": "include_metadata", "in": "query", "description": "Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A list of description jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DescribeList" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/describe/{job_id}": { "get": { "tags": ["Describe"], "summary": "Retrieve the current state of a media description job", "operationId": "getDescribe", "description": "Retrieve the current state of a media description job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The unique identifier of the description job", "schema": { "type": "string" } }, { "name": "response_format", "in": "query", "description": "Format for the response. Use speech_srt or speech_vtt for subtitle formats, speech_markdown for a diarized transcript, or speech_text for plain timestamped text.", "required": false, "schema": { "type": "string", "enum": [ "json", "markdown", "speech_srt", "speech_vtt", "speech_markdown", "speech_text" ] } }, { "name": "start_time_seconds", "in": "query", "description": "Start time in seconds to filter out results by", "required": false, "schema": { "type": "number" } }, { "name": "end_time_seconds", "in": "query", "description": "End time in seconds to filter out results by", "required": false, "schema": { "type": "number" } }, { "name": "modalities", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ModalitiesSchema" } }, { "name": "include_thumbnails", "in": "query", "description": "When true, include a file-level thumbnail_url on the response, per-segment thumbnail_url on each segment_summary entry, and inject thumbnail images into markdown output", "required": false, "schema": { "type": "boolean" } }, { "name": "include_word_timestamps", "in": "query", "description": "When true, include a words array on each speech entry with word-level start_time and end_time. Not available for YouTube sources. Only applies when response_format=json.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_chapters", "in": "query", "description": "Include narrative chapters in the response (when segmentation strategy is 'narrative')", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_shots", "in": "query", "description": "Include shot boundaries in the response (when segmentation strategy is 'shot-detector')", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_metadata", "in": "query", "description": "Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response with job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Describe" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Describe"], "summary": "Delete a media description job", "operationId": "deleteDescribe", "description": "Delete a media description job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The unique identifier of the description job", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the describe job" } }, "required": ["id"] } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": ["Describe"], "summary": "Update describe job", "operationId": "updateDescribe", "description": "Toggle the `use_in_default_index` flag on an existing describe job. Enabling this makes the file searchable by default in the deep search and response APIs.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The unique identifier of the description job", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["use_in_default_index"], "properties": { "use_in_default_index": { "type": "boolean", "description": "When true, the video's search documents will be added to the account's default index. When false, existing default index search documents are removed." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Describe" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/data-connectors": { "get": { "tags": ["Data Connectors"], "summary": "List all data connectors", "operationId": "listDataConnectors", "description": "List all active data connectors configured for your account", "responses": { "200": { "description": "A list of data connectors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnectorList" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data-connectors/{id}/files": { "get": { "tags": ["Data Connectors"], "summary": "List files in a data connector", "operationId": "listDataConnectorFiles", "description": "Browse files available in a connected data source. Returns URIs compatible with Cloudglue's file import system, and per-file provider metadata (see the `metadata` field) so you can inspect participants, hosts, durations, and AI summaries before importing. Supports pagination and filtering: `from`/`to` and `title_search` are shared filters honored by every connector that can (see each parameter's support matrix); parameters a connector can't honor are silently ignored. When filters are applied, a page may contain fewer than `limit` items — even zero — while `has_more` is still true: continue paginating until `next_page_token` is null rather than stopping at the first short or empty page.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the data connector", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Maximum number of files to return (1-100)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page_token", "in": "query", "description": "Opaque cursor for pagination. Use the `next_page_token` from a previous response. Tokens are only valid with the same filter parameters they were issued under.", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start date for filtering (YYYY-MM-DD, inclusive UTC day bound). Native for Zoom and Gong (call start; both default to a 6-month lookback when omitted), Grain and Recall (recording start/created time), iconik (asset date_created), and Google Drive (createdTime); matched while listing for Dropbox (client_modified). Ignored for S3/GCS.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End date for filtering (YYYY-MM-DD, inclusive UTC day bound). Same per-connector support as `from`. Ignored for S3/GCS.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "folder_id", "in": "query", "description": "Google Drive folder ID to list contents of. Applies to Google Drive connectors only.", "required": false, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Dropbox folder path to list contents of (default: root). Applies to Dropbox connectors only.", "required": false, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "required": false, "schema": { "type": "string", "enum": ["true", "false"] }, "description": "Dropbox only: 'true' lists the whole subtree under `path` (or the whole account when no `path` is given) instead of its direct children. Ignored by every other connector. Built for bulk metadata imports; interactive browsing should stay non-recursive." }, { "name": "bucket", "in": "query", "description": "Bucket name. Required for S3 and GCS connectors.", "required": false, "schema": { "type": "string" } }, { "name": "prefix", "in": "query", "description": "Key prefix filter. Applies to S3 and GCS connectors only.", "required": false, "schema": { "type": "string" } }, { "name": "title_search", "in": "query", "description": "Case-insensitive title filter. Native for Grain (title_search), Google Drive (name contains), and iconik (full-text title search); matched while listing for Zoom (topic), Gong (call title), and Dropbox (filename). Ignored for Recall (no title is available when listing) and S3/GCS.", "required": false, "schema": { "type": "string" } }, { "name": "team", "in": "query", "description": "Team filter. Applies to Grain connectors only. See the [Grain documentation](https://developers.grain.com/#recording-filter) for more details.", "required": false, "schema": { "type": "string" } }, { "name": "meeting_type", "in": "query", "description": "Meeting type filter. Applies to Grain connectors only. See the [Grain documentation](https://developers.grain.com/#recording-filter) for more details.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of files and folders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnectorFileList" } } } }, "400": { "description": "Bad request (e.g. missing required bucket parameter, unsupported connector type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Data connector not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error communicating with the external service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data-connectors/{id}/sync": { "post": { "tags": ["Data Connectors"], "summary": "Sync a data connector URI into a file", "operationId": "syncDataConnectorFile", "description": "Materialize a connector URI (e.g. `grain://recording/`) into a Cloudglue file without starting a downstream job. Idempotent: syncing the same URI returns the existing file. For Grain, Zoom, Recall, Google Drive, Dropbox, and Gong the file's `source_metadata` is populated from the provider (see the SourceMetadata schema). Plain http(s), TikTok, and Loom URLs are not connector-syncable; ingest those via POST /files/sync instead. YouTube URLs can only be added to a collection via the add-media endpoint.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the data connector", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Connector URI to sync. Must match the connector's type. Accepted forms per connector — s3: `s3:///` · gcs: `gs:///` · google-drive: `gdrive://file/` or a `https://drive.google.com/file/d//...` link · dropbox: `dropbox://` (as returned by GET /data-connectors/{id}/files) or a `https://www.dropbox.com/scl/fi/...` share link · zoom: `zoom://uuid/`, `zoom://id/`, or a `https://*.zoom.us` join, recording-detail, or rec/share link · grain: `grain://recording/` · gong: `gong://call/` · recall: `recall://recording/` · iconik: `iconik://asset/`.", "example": "grain://recording/abc123" } }, "required": ["url"] } } } }, "responses": { "200": { "description": "The synced file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Bad request (e.g. URL source does not match the connector type, or the link points to a folder)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The source file is not accessible (e.g. a login-gated, expired, or restricted Dropbox share link). Also returned when a usage limit is reached (monthly uploads, total duration, total file size, or total files) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Data connector not found, or the referenced file/recording was not found at the source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The external service rate-limited the request (e.g. Dropbox or Zoom); retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error communicating with the external service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data-connectors/{id}/source-metadata": { "get": { "tags": ["Data Connectors"], "summary": "Look up source metadata for a connector URI", "operationId": "getDataConnectorSourceMetadata", "description": "Fetch source metadata for a connector URI directly from the upstream source, without creating a Cloudglue file. Supported for Grain, Zoom, Recall, Google Drive, Dropbox, and Gong; S3/GCS return 501 (plain object stores have no richer metadata). Returns 502 when the upstream provider's response can't be validated.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the data connector", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "url", "in": "query", "description": "Connector URI to look up. Must match the connector's type.", "required": true, "schema": { "type": "string" }, "example": "grain://recording/abc123" } ], "responses": { "200": { "description": "Source metadata for the URI", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceMetadataResponse" } } } }, "400": { "description": "Bad request (e.g. URL source does not match the connector type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Data connector not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Source metadata lookup is not implemented for this connector type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error communicating with the external service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "tags": ["Webhooks"], "summary": "List all webhooks", "operationId": "listWebhooks", "description": "List all webhooks", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of webhooks to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of webhooks to skip", "required": false, "schema": { "type": "integer" } }, { "name": "order", "in": "query", "description": "Order the webhooks by a specific field", "required": false, "schema": { "type": "string", "enum": ["created_at"] } }, { "name": "sort", "in": "query", "description": "Sort the webhooks in ascending or descending order", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "A list of webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": ["Webhooks"], "summary": "Create a webhook", "operationId": "createWebhook", "description": "Create a webhook", "requestBody": { "description": "Webhook creation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "403": { "description": "Usage limit reached (total webhook endpoints) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{webhook_id}": { "get": { "tags": ["Webhooks"], "summary": "Get a webhook by ID", "operationId": "getWebhookById", "description": "Get a webhook by ID", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "The ID of the webhook to get", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Webhooks"], "summary": "Delete a webhook", "operationId": "deleteWebhook", "description": "Delete a webhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "The ID of the webhook to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful removal of webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeleteResponse" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": ["Webhooks"], "summary": "Update a webhook", "operationId": "updateWebhook", "description": "Update a webhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "The ID of the webhook to update", "schema": { "type": "string" } } ], "requestBody": { "description": "Webhook update parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search": { "post": { "tags": ["Search"], "summary": "Search across video files and segments to find relevant content", "operationId": "searchContent", "description": "Search for videos or video segments in collections to find relevant videos or moments/clips in a video", "requestBody": { "description": "Search parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Search"], "summary": "Get a list of search responses", "operationId": "getSearch", "description": "Get a list of search responses. Order by `created_at` in descending order by default.", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of search responses to return", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Number of search responses to skip", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "created_before", "in": "query", "description": "Filter search responses created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter search responses created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "A search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponseList" } } } }, "404": { "description": "Search not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search/{search_id}": { "get": { "tags": ["Search"], "summary": "Get a search response by ID", "operationId": "getSearchById", "description": "Get a search response by search_id. ", "parameters": [ { "name": "search_id", "in": "path", "required": true, "description": "The ID of the search response to get", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "404": { "description": "Search response not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/responses": { "post": { "tags": ["Response"], "summary": "Create a response", "operationId": "createResponse", "description": "Create a new response using the Response API. This endpoint provides an OpenAI Responses-compatible interface for chat completions with video collections.\n\nThe response can be processed synchronously (default) or asynchronously using the `background` parameter.", "requestBody": { "description": "Response creation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponseRequest" } } }, "required": true }, "responses": { "200": { "description": "Response created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly or daily chat completions) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Response"], "summary": "List responses", "operationId": "listResponses", "description": "List all responses with pagination and filtering options.", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of responses to return", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Number of responses to skip", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "status", "in": "query", "description": "Filter by response status", "required": false, "schema": { "type": "string", "enum": ["in_progress", "completed", "failed", "cancelled"] } }, { "name": "created_before", "in": "query", "description": "Filter responses created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter responses created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "List of responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseList" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/responses/{id}": { "get": { "tags": ["Response"], "summary": "Get a response by ID", "operationId": "getResponse", "description": "Retrieve a specific response by its ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the response to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Response not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Response"], "summary": "Delete a response", "operationId": "deleteResponse", "description": "Delete a response by ID. This operation is idempotent - deleting a non-existent response returns success.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the response to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponseResult" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/responses/{id}/cancel": { "post": { "tags": ["Response"], "summary": "Cancel a response", "operationId": "cancelResponse", "description": "Cancel a background response that is in progress. If the response is already completed, failed, or cancelled, this returns the response as-is.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the response to cancel", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response cancelled or current status returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Response not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deepSearch": { "post": { "tags": ["Deep Search"], "summary": "Create a deep search", "operationId": "createDeepSearch", "description": "Create a new deep search over one or more collections. Deep search uses agentic retrieval and LLM summarization to find specific moments across your video data.\n\nThe search can be processed synchronously (default), streamed via SSE, or run in the background.", "requestBody": { "description": "Deep search creation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeepSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "Deep search created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSearch" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly or daily chat completions) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Deep Search"], "summary": "List deep searches", "operationId": "listDeepSearches", "description": "List all deep searches with pagination and filtering options.", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of deep searches to return", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Number of deep searches to skip", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "status", "in": "query", "description": "Filter by deep search status", "required": false, "schema": { "type": "string", "enum": ["in_progress", "completed", "failed", "cancelled"] } }, { "name": "created_before", "in": "query", "description": "Filter deep searches created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter deep searches created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "List of deep searches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSearchList" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deepSearch/{id}": { "get": { "tags": ["Deep Search"], "summary": "Get a deep search by ID", "operationId": "getDeepSearch", "description": "Retrieve a specific deep search by its ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the deep search to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deep search details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSearch" } } } }, "404": { "description": "Deep search not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Deep Search"], "summary": "Delete a deep search", "operationId": "deleteDeepSearch", "description": "Delete a deep search by ID. This operation is idempotent - deleting a non-existent deep search returns success.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the deep search to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deep search deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDeepSearchResult" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deepSearch/{id}/cancel": { "post": { "tags": ["Deep Search"], "summary": "Cancel a deep search", "operationId": "cancelDeepSearch", "description": "Cancel a background deep search that is in progress. If the deep search is already completed, failed, or cancelled, this returns the deep search as-is.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the deep search to cancel", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deep search cancelled or current status returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSearch" } } } }, "404": { "description": "Deep search not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/videos/{file_id}/face-detections": { "get": { "tags": ["Collections"], "summary": "Retrieve face detections for a specific file in a collection", "operationId": "getFaceDetections", "description": "Retrieve face detections for a specific file in a collection. Results are paginated with a default limit of 50 faces per request (maximum 100). Use limit and offset parameters to paginate through all results. This API is only available when the collection is created with collection_type 'face-analysis'", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of faces to return", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Number of faces to skip", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "File face detections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileFaceDetections" } } } }, "400": { "description": "Collection type is not 'face-analysis'", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection, file, or face detection job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segmentations/{segmentation_id}": { "get": { "tags": ["Segmentations"], "summary": "Get a specific segmentation", "operationId": "getSegmentation", "description": "Retrieve details about a specific segmentation including its segments", "parameters": [ { "name": "segmentation_id", "in": "path", "required": true, "description": "The ID of the segmentation to retrieve", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of segments to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the segments list", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Segmentation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segmentation" } } } }, "404": { "description": "Segmentation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Segmentations"], "summary": "Delete a segmentation", "operationId": "deleteSegmentation", "description": "Delete a specific segmentation", "parameters": [ { "name": "segmentation_id", "in": "path", "required": true, "description": "The ID of the segmentation to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Segmentation deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted segmentation" } }, "required": ["id"] } } } }, "404": { "description": "Segmentation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_id}/frames": { "post": { "tags": ["Files"], "summary": "Create a new frame extraction for a file", "operationId": "createFileFrameExtraction", "description": "Create a new frame extraction for a file using the specified frame extraction configuration. This is an async operation that returns immediately with a 'pending' status. Results are cached, so identical requests will return the same frame extraction.", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file to extract frames from", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Frame extraction configuration", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/FrameExtractionConfig" } ], "type": "object", "properties": { "thumbnails_config": { "$ref": "#/components/schemas/FrameExtractionThumbnailsConfig", "description": "Configuration for frame thumbnails. Optional." } }, "description": "Frame extraction configuration (root level) with optional thumbnails configuration." } } }, "required": true }, "responses": { "200": { "description": "Frame extraction created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameExtraction" } } } }, "400": { "description": "Invalid request or file duration is less than specified time range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Files"], "summary": "List frame extractions for a file", "operationId": "listFileFrameExtractions", "description": "List all frame extractions for a specific file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The ID of the file", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of frame extractions to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the list", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List of frame extractions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameExtractionList" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/frames/{frame_extraction_id}": { "get": { "tags": ["Frames"], "summary": "Get a specific frame extraction", "operationId": "getFrameExtraction", "description": "Retrieve details about a specific frame extraction including its frames", "parameters": [ { "name": "frame_extraction_id", "in": "path", "required": true, "description": "The ID of the frame extraction to retrieve", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of frames to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the frames list", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Frame extraction details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameExtraction" } } } }, "404": { "description": "Frame extraction not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Frames"], "summary": "Delete a frame extraction", "operationId": "deleteFrameExtraction", "description": "Delete a specific frame extraction", "parameters": [ { "name": "frame_extraction_id", "in": "path", "required": true, "description": "The ID of the frame extraction to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Frame extraction deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted frame extraction" } }, "required": ["id"] } } } }, "404": { "description": "Frame extraction not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segments": { "post": { "tags": ["Segments"], "summary": "Create a new segmentation job", "operationId": "createSegments", "description": "Create intelligent segments for video or audio files based on shot detection or narrative analysis.\n\n**Audio File Support:**\n\n- Audio files support **narrative** criteria only (shot detection is not available for audio).\n- Audio files default to the 'balanced' strategy and may opt into 'transcript'.\n\n**Note: YouTube URLs and audio files are supported for narrative-based segmentation only.** Shot-based segmentation requires direct video file access. Use Cloudglue Files, HTTP URLs, or files from data connectors for shot-based segmentation.\n\n**Narrative Segmentation Strategies:**\n\n- **comprehensive** (default for non-YouTube/non-audio files): Uses a VLM to deeply analyze logical segments of video. Only available for video files (not YouTube or audio).\n- **balanced** (default for YouTube videos and audio files): Balanced analysis approach using multiple modalities. Supports YouTube URLs and audio files.\n- **transcript**: Cheap and fast speech-transcript-based segmentation. Requires a transcript and returns an error when none is available — use `balanced` for silent or visual-only content (or `comprehensive` for non-YouTube/non-audio video files).\n\n**YouTube URLs and Audio Files**: Only the 'balanced' and 'transcript' strategies are accepted. 'comprehensive' will be rejected with an error.\n\n**Chapter Count Parameters:**\n\n- **number_of_chapters**: Target number of chapters. If only this is provided, min_chapters and max_chapters are calculated automatically.\n- **min_chapters**: Minimum number of chapters. If provided with number_of_chapters and max, validates min is less than or equal to number_of_chapters which is less than or equal to max.\n- **max_chapters**: Maximum number of chapters. If provided with number_of_chapters and min, validates min is less than or equal to number_of_chapters which is less than or equal to max.\n- If none are provided, chapter counts are calculated automatically based on file duration.", "requestBody": { "description": "Segmentation job parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewSegments" } } }, "required": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segments" } } } }, "400": { "description": "Invalid request, missing required parameters, unsupported URL type (e.g., YouTube URLs with shot-based segmentation), or unsupported strategy for YouTube URLs and audio files (only 'balanced' and 'transcript' are accepted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly segments jobs, or the file limits when given a new URL) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Segments"], "summary": "List all segmentation jobs", "operationId": "listSegments", "description": "List all segmentation jobs with optional filtering", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of segmentation jobs to return", "required": false, "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of segmentation jobs to skip", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter segmentation jobs by status", "required": false, "schema": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] } }, { "name": "criteria", "in": "query", "description": "Filter segmentation jobs by criteria type", "required": false, "schema": { "type": "string", "enum": ["shot", "narrative"] } }, { "name": "created_before", "in": "query", "description": "Filter segmentation jobs created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter segmentation jobs created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "url", "in": "query", "description": "Filter segmentation jobs by the input URL used for segmentation", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of segmentation jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentsList" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segments/{job_id}": { "get": { "tags": ["Segments"], "summary": "Retrieve the current state of a segmentation job", "operationId": "getSegments", "description": "Retrieve the current state of a segmentation job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The unique identifier of the segmentation job", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response with job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segments" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Segments"], "summary": "Delete a segments job", "operationId": "deleteSegments", "description": "Delete a specific segments job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The ID of the segments job to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Segments job deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted segments job" } }, "required": ["id"] } } } }, "404": { "description": "Segments job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segmentations/{segmentation_id}/thumbnails": { "get": { "tags": ["Segmentations", "Thumbnails"], "summary": "Get thumbnails for a segmentation", "operationId": "getSegmentationThumbnails", "description": "Get all thumbnails for a segmentation", "parameters": [ { "name": "segmentation_id", "in": "path", "required": true, "description": "The ID of the segmentation to retrieve thumbnails for", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_ids", "in": "query", "description": "Filter thumbnails by segment IDs. If provided, will only return thumbnails for the specified segments. Comma separated list of segment IDs.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of thumbnails to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the list", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "type", "in": "query", "description": "Filter thumbnails by type", "required": false, "schema": { "$ref": "#/components/schemas/ThumbnailType" } } ], "responses": { "200": { "description": "Segmentation thumbnails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThumbnailList" } } } }, "404": { "description": "Segmentation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segmentations/{segmentation_id}/describes": { "get": { "tags": ["Segmentations", "Describe"], "summary": "List describe jobs for a segmentation", "operationId": "listSegmentationDescribes", "description": "List all describe jobs that referenced the specified segmentation. Returns describe job records associated with the segmentation.", "parameters": [ { "name": "segmentation_id", "in": "path", "required": true, "description": "The ID of the segmentation job", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_data", "in": "query", "description": "Include the describe data in the response. If false, only job information is returned. Defaults to false.", "required": false, "schema": { "type": "boolean" } }, { "name": "response_format", "in": "query", "description": "Output format for the describe data", "required": false, "schema": { "type": "string", "enum": ["json", "markdown"] } }, { "name": "limit", "in": "query", "description": "Number of items to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the list", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "include_metadata", "in": "query", "description": "Include the file's user-defined metadata and source metadata. In markdown these render as a `## Metadata` section; in JSON they populate `file.metadata` and `file.source_metadata`.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of describe outputs for the segmentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DescribeList" } } } }, "404": { "description": "Segmentation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/face-match": { "post": { "tags": ["Face Match"], "summary": "Find matching face in video", "operationId": "createFaceMatch", "description": "Search for a source face in a target video using facial recognition", "requestBody": { "description": "Face match request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceMatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Face match job created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceMatch" } } } }, "400": { "description": "Invalid request parameters or source image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly face match jobs, or the file limits when given a new URL) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Target video file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Face Match"], "summary": "List face match jobs", "operationId": "listFaceMatch", "description": "List all face match jobs", "parameters": [ { "name": "limit", "in": "query", "description": "Number of face match jobs to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the face match jobs list", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "created_before", "in": "query", "description": "Filter face match jobs created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter face match jobs created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] } } ], "responses": { "200": { "description": "Face match jobs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceMatchListResponse" } } } } } } }, "/face-match/{face_match_id}": { "get": { "tags": ["Face Match"], "summary": "Get face match results", "operationId": "getFaceMatch", "description": "Retrieve face match results including detected faces and similarity scores", "parameters": [ { "name": "face_match_id", "in": "path", "required": true, "description": "The ID of the face match to retrieve", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of face matches to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the face matches list", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Face match results retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceMatch" } } } }, "404": { "description": "Face match job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Face Match"], "summary": "Delete face match analysis", "operationId": "deleteFaceMatch", "description": "Delete a specific face match analysis", "parameters": [ { "name": "face_match_id", "in": "path", "required": true, "description": "The ID of the face match to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Face match deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "face_match_id": { "type": "string", "format": "uuid", "description": "ID of the deleted face match" }, "object": { "type": "string", "enum": ["face_match"], "description": "Object type, always 'face_match'" } }, "required": ["face_match_id", "object"] } } } }, "404": { "description": "Face match job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/face-detect": { "post": { "tags": ["Face Detection"], "summary": "Detect faces in video", "operationId": "createFaceDetection", "description": "Analyze video to detect all faces", "requestBody": { "description": "Face detection request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceDetectionRequest" } } }, "required": true }, "responses": { "200": { "description": "Face detection job created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceDetection" } } } }, "400": { "description": "Invalid request parameters or configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly face detection jobs, or the file limits when given a new URL) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Target video file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Face Detection"], "summary": "List face detection jobs", "operationId": "listFaceDetection", "description": "List all face detection jobs", "parameters": [ { "name": "limit", "in": "query", "description": "Number of face detection jobs to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the face detection jobs list", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "created_before", "in": "query", "description": "Filter face detection jobs created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter face detection jobs created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] } } ], "responses": { "200": { "description": "Face detection jobs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceDetectionListResponse" } } } } } } }, "/face-detect/{face_detection_id}": { "get": { "tags": ["Face Detection"], "summary": "Get face detection results", "operationId": "getFaceDetection", "description": "Retrieve face detection results including all detected faces", "parameters": [ { "name": "face_detection_id", "in": "path", "required": true, "description": "The ID of the face detection to retrieve", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of detected faces to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the detected faces list", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Face detection results retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceDetection" } } } }, "404": { "description": "Face detection job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Face Detection"], "summary": "Delete face detection analysis", "operationId": "deleteFaceDetection", "description": "Delete a specific face detection analysis", "parameters": [ { "name": "face_detection_id", "in": "path", "required": true, "description": "The ID of the face detection to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Face detection deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted face detection" } }, "required": ["id"] } } } }, "404": { "description": "Face detection job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/share": { "post": { "tags": ["Share"], "summary": "Create a shareable asset", "operationId": "createShareableAsset", "description": "Create a shareable asset. Public assets (the default) are viewable by anyone with the link; private assets are restricted to members of the owning account and stream via a signed, token-gated playback url. A file (or file segment) can have at most one active share per visibility — one public and one private — each with its own stable URL; creating a second of the same visibility returns 409.", "requestBody": { "description": "Shareable asset creation request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareableAssetRequest" } } }, "required": true }, "responses": { "200": { "description": "Shareable asset created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareableAsset" } } } }, "400": { "description": "Invalid request parameters or configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly shareable assets) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File or file segment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Shareable asset already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Share"], "summary": "List shareable assets", "operationId": "listShareableAssets", "description": "List shareable assets", "parameters": [ { "name": "file_id", "in": "query", "description": "The ID of the file to list shareable assets for", "schema": { "type": "string", "format": "uuid" } }, { "name": "file_segment_id", "in": "query", "description": "The ID of the file segment to list shareable assets for", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of shareable assets to return", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Offset from the start of the shareable assets list", "schema": { "type": "integer", "minimum": 0 } }, { "name": "created_before", "in": "query", "description": "Filter shareable assets created before a specific date (YYYY-MM-DD format), in UTC timezone", "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter shareable assets created after a specific date (YYYY-MM-DD format), in UTC timezone", "schema": { "type": "string", "format": "date" } }, { "name": "visibility", "in": "query", "description": "Filter shareable assets by visibility. A file can have one public and one private share.", "schema": { "type": "string", "enum": ["public", "private"] } } ], "responses": { "200": { "description": "Shareable assets listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareableAssetListResponse" } } } } } } }, "/share/{id}": { "get": { "tags": ["Share"], "summary": "Get a shareable asset", "operationId": "getShareableAsset", "description": "Get a shareable asset. Optionally pass an instant-clip window (clip_start/clip_end) to receive a stream_url that plays only that window.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the shareable asset to retrieve", "schema": { "type": "string", "format": "uuid" } }, { "name": "clip_start", "in": "query", "required": false, "description": "Instant-clip window start in seconds. Must be provided together with clip_end. When set, the returned stream_url plays only the [clip_start, clip_end] window — the share itself is untouched, and reads without the params keep returning the full-asset stream.", "schema": { "type": "number", "minimum": 0 } }, { "name": "clip_end", "in": "query", "required": false, "description": "Instant-clip window end in seconds; must be greater than clip_start. Must be provided together with clip_start.", "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true } } ], "responses": { "200": { "description": "Shareable asset retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareableAsset" } } } }, "404": { "description": "Shareable asset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Share"], "summary": "Delete a shareable asset", "operationId": "deleteShareableAsset", "description": "Delete a shareable asset", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the shareable asset to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Shareable asset deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted shareable asset" }, "object": { "type": "string", "enum": ["share"], "description": "Object type, always 'share'" } }, "required": ["id", "object"] } } } }, "404": { "description": "Shareable asset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": ["Share"], "summary": "Update a shareable asset", "operationId": "updateShareableAsset", "description": "Update a shareable asset", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the shareable asset to update", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Shareable asset update request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShareableAssetRequest" } } } }, "responses": { "200": { "description": "Shareable asset updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareableAsset" } } } }, "404": { "description": "Shareable asset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/media": { "post": { "tags": ["Collections"], "summary": "Add a media file to a collection", "operationId": "addMedia", "description": "Add a video or audio file to a collection. This is the recommended endpoint for adding media files to collections.\n\n**Media Type Handling:**\n\n- **Video files**: Processed with full visual analysis (scene description, text extraction, etc.)\n- **Audio files**: Visual features automatically disabled; only speech and audio analysis available\n\n**Audio File Restrictions:**\n\n- Audio files cannot be added to face-analysis collections\n- Shot-detector segmentation is not available for audio files", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection to add the media file to", "schema": { "type": "string" } } ], "requestBody": { "description": "File association parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCollectionFile" } } }, "required": true }, "responses": { "200": { "description": "Successful file addition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionFile" } } } }, "400": { "description": "Invalid request (e.g., audio files with shot-detector segmentation, audio in face-analysis collections)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (files per collection, or the file limits when adding by URL) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/imports": { "post": { "tags": ["Bulk Imports"], "summary": "Create a bulk import", "operationId": "createMetadataImport", "description": "Create a bulk import: a saved definition that lists a data connector's source files and brings each match into the collection. What a run ingests follows the collection's type (see `import_type` on the response). For a **metadata collection** it imports each file's source metadata as a collection file, with no media download or processing, and runs consume no credits. For **any other collection type** it imports the media itself: each matching file is ingested and processed exactly like a manual add, so it is **billed per file** and counts against the account's file usage limits. A media run that exhausts credits or a usage limit stops with a user-facing error and keeps everything it already imported — rerun in `append` mode to resume. By default the first run starts immediately (`start: false` saves the definition only). The response's `latest_run` is the triggered run; it is null when `start` is false or when another run is already active in the collection (the definition is saved, and can be run once that one finishes), and it is returned with status `failed` when the run could not be started (trigger a new run to retry). Runs page the connector — and, for media imports, add each file — with the account's default active API key, and fail with a clear error when the account has none.", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the metadata collection", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetadataImportRequest" } } } }, "responses": { "200": { "description": "The created import, with `latest_run` reflecting the immediately-triggered first run when applicable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataImport" } } } }, "400": { "description": "Invalid request — the connector does not exist, the connector type does not support imports, a filter key is not supported by the connector type, or `include_thumbnails` or `enrich_metadata` was set on a media import (imported media gets real thumbnails from the processing pipeline, and a media run has no metadata-only record to enrich)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Bulk Imports"], "summary": "List bulk imports", "operationId": "listMetadataImports", "description": "List a collection's metadata imports, newest first, each with its latest run inline.", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the metadata collection", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of imports to return (default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of imports to skip", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Imports for the collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataImportList" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/imports/{import_id}": { "get": { "tags": ["Bulk Imports"], "summary": "Get a bulk import", "operationId": "getMetadataImport", "description": "Get a metadata import definition with one page of its run history (newest first).", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the metadata collection", "schema": { "type": "string", "format": "uuid" } }, { "name": "import_id", "in": "path", "required": true, "description": "The ID of the metadata import", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of runs to return (default 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of runs to skip", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "The import with paged run history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataImportDetail" } } } }, "404": { "description": "Collection or import not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Bulk Imports"], "summary": "Delete a bulk import", "operationId": "deleteMetadataImport", "description": "Delete an import definition and its run history. Any active run is cancelled first. Imported files and collection memberships are never deleted by this operation.", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the metadata collection", "schema": { "type": "string", "format": "uuid" } }, { "name": "import_id", "in": "path", "required": true, "description": "The ID of the metadata import", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The import was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataImportDelete" } } } }, "404": { "description": "Collection or import not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/imports/{import_id}/runs": { "post": { "tags": ["Bulk Imports"], "summary": "Run a bulk import", "operationId": "createMetadataImportRun", "description": "Trigger a new run of a saved import. `mode` and `delete_missing` default to the definition's saved values. Only one run may be active per collection at a time, so triggering while any run in the collection is active returns a 409. Rerunning is also how a media import resumes after it stopped on exhausted credits or a usage limit: an `append` run skips files it already imported and retries the rest.", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the metadata collection", "schema": { "type": "string", "format": "uuid" } }, { "name": "import_id", "in": "path", "required": true, "description": "The ID of the metadata import", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetadataImportRunRequest" } } } }, "responses": { "200": { "description": "The created run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataImportRun" } } } }, "400": { "description": "Invalid request — `include_thumbnails` or `enrich_metadata` was set on a media import (imported media gets real thumbnails from the processing pipeline, and a media run has no metadata-only record to enrich)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly metadata-import files) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection or import not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A run of this import is already active, or another import in this collection has an active run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The run could not be enqueued and was marked failed — trigger a new run to retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/imports/{import_id}/runs/{run_id}/cancel": { "post": { "tags": ["Bulk Imports"], "summary": "Cancel a bulk import run", "operationId": "cancelMetadataImportRun", "description": "Cancel an in-flight run. Files already imported by the run are kept. Cancelling an already-finished run is a no-op that returns the current state.", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the metadata collection", "schema": { "type": "string", "format": "uuid" } }, { "name": "import_id", "in": "path", "required": true, "description": "The ID of the metadata import", "schema": { "type": "string", "format": "uuid" } }, { "name": "run_id", "in": "path", "required": true, "description": "The ID of the import run", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The run in its post-cancel state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataImportRun" } } } }, "404": { "description": "Collection, import, or run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/query": { "post": { "tags": ["Query"], "summary": "Run a structured query", "operationId": "runQuery", "description": "Run a synchronous read-only SQL query over the structured data extracted from one or more collections. Queries execute against three virtual tables — files, entities, and segment_entities — built from each file's most recent completed extraction.\n\nEach query costs 2 credits. Results are returned inline and stored, so completed runs can be re-fetched via GET /query/{id}. Use GET /query/schema to discover the queryable tables and per-collection fields.", "requestBody": { "description": "Query execution parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Query executed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResult" } } } }, "400": { "description": "Invalid request parameters or rejected SQL (multiple statements, a non-SELECT statement, SQL that could not be parsed, or a face-analysis collection in scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "One or more collections not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Query exceeded the execution time limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The selected collections exceed the maximum queryable dataset size", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many concurrent queries, or the per-minute rate limit was exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A natural-language query could not be compiled into valid SQL — refine the question or send sql directly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Query"], "summary": "List query results", "operationId": "listQueries", "description": "List all query runs with pagination and filtering options. List items omit the columns and rows payloads — fetch an individual run via GET /query/{id} for the full result.", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of query results to return", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Number of query results to skip", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "status", "in": "query", "description": "Filter by query status", "required": false, "schema": { "type": "string", "enum": ["completed", "failed", "in_progress", "cancelled"] } }, { "name": "created_before", "in": "query", "description": "Filter query results created before a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "description": "Filter query results created after a specific date (YYYY-MM-DD format), in UTC timezone", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "List of query results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryListResponse" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/query/schema": { "get": { "tags": ["Query"], "summary": "Get the query schema", "operationId": "getQuerySchema", "description": "Introspect the virtual tables and per-collection extracted fields available to SQL queries over the given collections. Use this to discover column names, entity field names, types, and levels, plus each collection's verbatim extract schema and prompt, before writing a query.\n\nFields with level 'file' appear as rows in the entities table; fields with level 'segment' live inside the segment_entities.entities JSON column.", "parameters": [ { "name": "collections", "in": "query", "description": "Comma-separated list of collection IDs (1-20) to introspect", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The queryable schema for the given collections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuerySchema" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "One or more collections not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/query/{id}": { "get": { "tags": ["Query"], "summary": "Get a query result by ID", "operationId": "getQuery", "description": "Retrieve a stored query run by its ID, including its result rows. Results larger than the inline storage cap are replayed truncated (truncated: true).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the query result to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Query result details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResult" } } } }, "404": { "description": "Query result not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/query/{id}/cancel": { "post": { "tags": ["Query"], "summary": "Cancel a background export", "operationId": "cancelQueryExport", "description": "Cancel an in-progress background export. The run is marked cancelled synchronously, the export stream is aborted mid-flight (the partial upload is discarded), and the reserved credits are refunded. A run that has already completed or failed is returned unchanged.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the query export to cancel", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The query result, with status 'cancelled' when the cancel took effect (or the run's real status if it had already finished)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResult" } } } }, "404": { "description": "Query result not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/find-moments": { "post": { "tags": ["Find Moments"], "summary": "Find moments in a video", "operationId": "createFindMoments", "description": "Runs exhaustive moment discovery for one criterion over one video. Every accepted moment is persisted; ranking and truncation are read-time parameters on GET. Reuses a compatible describe or creates one internally - a missing describe is never an error.", "requestBody": { "description": "Find-moments run parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewFindMoments" } } }, "required": true }, "responses": { "200": { "description": "The created run, or an existing matching run at cost 0 (cache hit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindMoments" } } } }, "400": { "description": "Invalid request. Criterion dialect violations carry a stable code and a field-addressable path; unknown execution fields (e.g. mode, max_moments) are rejected naming the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credit balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Usage limit reached (monthly find-moments runs, or the file limits when given a new URL) — `code: usage_limit_reached`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Find Moments"], "summary": "List find-moments runs", "operationId": "listFindMoments", "description": "Lists runs, newest first, with cursor pagination. Pagination is over runs, never over joined moment rows.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "url", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Runs, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindMomentsList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/find-moments/{job_id}": { "get": { "tags": ["Find Moments"], "summary": "Get a find-moments run", "operationId": "getFindMoments", "description": "Returns the run; when completed, includes moments and findings shaped by the read parameters. Selection never destroys accepted results: total_moments is always the full accepted count.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Top-k read: return only the k best moments by the active sort. total_moments is unaffected.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "min_score", "in": "query", "description": "Only moments whose criterion score is at least this value.", "schema": { "type": "number" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["rank_score", "start_time"], "default": "rank_score" } } ], "responses": { "200": { "description": "The run; when completed, includes moments and findings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindMoments" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Find Moments"], "summary": "Delete a find-moments run", "operationId": "deleteFindMoments", "description": "Deletes the run and its moments and findings. An in-flight run is cancelled and refunded; a completed run is not refunded.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFindMomentsResult" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/moments": { "get": { "tags": ["Collections"], "summary": "List moments in a moments collection", "operationId": "listCollectionMoments", "description": "Moments across current collection members, with exact total. Default sort is positional (file_id, then start_time); criterion_score and rank_score sorts require a single-criterion filter. Removing a file from the collection drops its moments from this enumeration; the underlying runs persist.", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "criterion_name", "in": "query", "schema": { "type": "string" } }, { "name": "attachment_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "query", "description": "Restrict to one video.", "schema": { "type": "string", "format": "uuid" } }, { "name": "min_score", "in": "query", "schema": { "type": "number" } }, { "name": "sort", "in": "query", "description": "criterion_score and rank_score require a single-criterion filter.", "schema": { "type": "string", "enum": ["position", "criterion_score", "rank_score"], "default": "position" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Moments across current collection members, with exact total.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionMomentsList" } } } }, "400": { "description": "Not a moments collection, or a score sort without a single-criterion filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/moments/findings": { "get": { "tags": ["Collections"], "summary": "List findings in a moments collection", "operationId": "listCollectionMomentFindings", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "criterion_name", "in": "query", "schema": { "type": "string" } }, { "name": "file_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": ["absence", "observation"] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Findings across current collection members.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionMomentFindingsList" } } } }, "400": { "description": "Not a moments collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/moment-criteria": { "post": { "tags": ["Collections"], "summary": "Attach a criterion to a moments collection", "operationId": "createCollectionMomentCriterion", "description": "Adds a criterion attachment and backfills existing members. The attach response charges nothing (cost header 0); per-file runs charge as they execute, and a matching prior run satisfies a pair at no extra execution.", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewMomentCriterionAttachment" } } } }, "responses": { "201": { "description": "The attachment, backfill pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MomentCriterionAttachment" } } } }, "400": { "description": "Invalid criterion, or not a moments collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Balance cannot cover the backfill precheck", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/{collection_id}/moment-criteria/{attachment_id}": { "delete": { "tags": ["Collections"], "summary": "Detach a criterion from a moments collection", "operationId": "deleteCollectionMomentCriterion", "description": "Removes the attachment; its moments and findings leave collection enumeration. Underlying runs persist as job history.", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachment_id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } }, "required": ["attachment_id", "deleted"] } } } }, "400": { "description": "Not a moments collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Attachment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sites/{site_id}/route-previews": { "get": { "tags": ["Sites"], "summary": "List site route previews", "operationId": "listSiteRoutePreviews", "description": "List the site's per-route unfurl previews, ordered by route.", "parameters": [ { "name": "site_id", "in": "path", "required": true, "description": "The ID of the site", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The route previews registered for the site", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteRoutePreviewList" } } } }, "404": { "description": "Site not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": ["Sites"], "summary": "Replace site route previews", "operationId": "replaceSiteRoutePreviews", "description": "Replace the site's complete set of per-route unfurl previews. Each entry maps a route within the site (e.g. a clip page) to its own preview card and hero share, so links to that page unfurl distinctly in Slack instead of with the site-wide hero. An optional startSeconds/endSeconds window makes the unfurled player serve only that segment of the hero (trimmed at the asset’s HLS segment boundaries — see the field descriptions). The set is replaced wholesale — typically written by the same pipeline that publishes the site — and an empty array clears all route previews. Routes are stored in canonical form: hash-router prefixes ('#/'), query strings, and surrounding slashes are stripped, so '/clip/intro', 'clip/intro/', and '#/clip/intro' all name the same route. Links to routes with no registered preview fall back to the site-level preview fields.", "parameters": [ { "name": "site_id", "in": "path", "required": true, "description": "The ID of the site", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The site's complete set of route previews", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceSiteRoutePreviewsRequest" } } } }, "responses": { "200": { "description": "The stored route previews (routes in canonical form)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteRoutePreviewList" } } } }, "400": { "description": "Invalid route previews (empty or duplicate canonical routes, non-video heroes, private heroes on a public site, or an invalid clip window)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Site not found, or a previewShareId does not reference a share in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sites/{site_id}/route-previews/{preview_id}": { "delete": { "tags": ["Sites"], "summary": "Delete a site route preview", "operationId": "deleteSiteRoutePreview", "description": "Delete one route preview. Links to that route fall back to the site-level preview fields at their next unfurl.", "parameters": [ { "name": "site_id", "in": "path", "required": true, "description": "The ID of the site", "schema": { "type": "string", "format": "uuid" } }, { "name": "preview_id", "in": "path", "required": true, "description": "The ID of the route preview to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The deleted route preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteRoutePreview" } } } }, "404": { "description": "Site or route preview not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "CreateResponseRequest": { "type": "object", "required": ["model", "input"], "properties": { "model": { "type": "string", "minLength": 1, "example": "nimbus-001", "description": "The model to use for generating the response.\n\n- `nimbus-001`: Fast general question answering model. Requires `knowledge_base`. Default temperature: 0.7.\n- `nimbus-002-preview`: Light reasoning model capable of multi-step reasoning, cross-video synthesis, and structured entity data. Requires `knowledge_base`. Supports `entity_collections` in the knowledge base. Default temperature: 1.\n\nMetadata collections (`collection_type: 'metadata'`) and entities collections (`collection_type: 'entities'`) in the knowledge base are only supported by `nimbus-002-preview` — its agent picks the retrieval scope per search call (metadata docs and file-level entity docs at file granularity, segment-level entity docs at segment granularity); `nimbus-001` rejects both (400)." }, "input": { "oneOf": [ { "type": "string", "description": "A simple string input (treated as a user message)" }, { "type": "array", "description": "An array of message objects", "items": { "$ref": "#/components/schemas/ResponseInputMessage" } } ], "description": "The input for the response. Can be a simple string or an array of messages." }, "instructions": { "type": "string", "description": "System instructions to guide the model's behavior (maps to developer/system message)" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Sampling temperature for the model. Defaults to 0.7 for nimbus-001 and 1 for nimbus-002-preview." }, "knowledge_base": { "description": "Knowledge base configuration. Required for `nimbus-001` and `nimbus-002-preview`.", "$ref": "#/components/schemas/ResponseKnowledgeBase" }, "include": { "type": "array", "items": { "type": "string", "enum": ["cloudglue_citations.media_descriptions"] }, "description": "Additional data to include in the response annotations" }, "tools": { "type": "array", "description": "Tool definitions for function calling.", "items": { "$ref": "#/components/schemas/ResponseToolDefinition" } }, "max_output_tokens": { "type": "integer", "minimum": 1, "maximum": 128000, "description": "Maximum number of output tokens." }, "background": { "type": "boolean", "description": "Set to true to process the response in the background. When true, the response is returned immediately with status 'in_progress'." }, "stream": { "type": "boolean", "description": "Stream response via SSE. Mutually exclusive with background." } } }, "ResponseInputMessage": { "type": "object", "required": ["type", "role", "content"], "properties": { "type": { "type": "string", "enum": ["message"], "description": "The type of the message" }, "role": { "type": "string", "enum": ["developer", "user", "assistant"], "description": "The role of the message sender. 'developer' maps to system instructions." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseInputContent" }, "description": "The content of the message" } } }, "ResponseInputContent": { "type": "object", "required": ["type", "text"], "properties": { "type": { "type": "string", "enum": ["input_text"], "description": "The type of content" }, "text": { "type": "string", "description": "The text content" } } }, "ResponseKnowledgeBase": { "description": "Knowledge base configuration. Determines which content the model searches for context.\n\nThree source modes are supported:\n- `collections`: Search within specific collections (default, backward-compatible)\n- `files`: Search specific files by URL or file ID (uses default index)\n- `default`: Search all default-indexed files for the account", "oneOf": [ { "$ref": "#/components/schemas/KnowledgeBaseCollections" }, { "$ref": "#/components/schemas/KnowledgeBaseFiles" }, { "$ref": "#/components/schemas/KnowledgeBaseDefault" } ], "discriminator": { "propertyName": "source", "mapping": { "collections": "#/components/schemas/KnowledgeBaseCollections", "files": "#/components/schemas/KnowledgeBaseFiles", "default": "#/components/schemas/KnowledgeBaseDefault" } } }, "KnowledgeBaseCollections": { "type": "object", "description": "Search within specific collections. This is the default source mode and is backward-compatible — the `source` field can be omitted. Since 0.7.30, `collections` itself is optional when `type` is `entity_backed_knowledge` and `entity_backed_knowledge_config.entity_collections` carries at least one collection — an entity/moments-only knowledge base answers from the structured-data tools (and moment search for moments collections) with no transcript corpus. At least one of `collections` or `entity_backed_knowledge_config.entity_collections` must be present.", "properties": { "source": { "type": "string", "enum": ["collections"], "description": "Source mode. Can be omitted for backward compatibility (defaults to `collections`)." }, "type": { "type": "string", "enum": ["general_question_answering", "entity_backed_knowledge"], "description": "The type of knowledge base interaction pattern.\n\n- `general_question_answering` (default): Search-and-answer over media collections.\n- `entity_backed_knowledge`: Enables structured entity lookups alongside video content. Requires `entity_backed_knowledge_config` and `nimbus-002-preview` model." }, "collections": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Collection IDs to search for relevant context. Collections must be of type 'rich-transcripts', 'media-descriptions', 'metadata', or 'entities'. Metadata and entities collections require the `nimbus-002-preview` model. Optional when `type` is `entity_backed_knowledge` with at least one entity collection — omit it for an entity/moments-only knowledge base." }, "filter": { "description": "Optional filter to narrow down the search within collections.\n\nSupports filtering by `metadata`, `video_info`, and `file` properties. Each filter is an array of criteria with `path`, `operator`, and `valueText` or `valueTextArray`.\n\nSupported operators: `Equal`, `NotEqual`, `LessThan`, `GreaterThan`, `In`, `ContainsAny`, `ContainsAll`.\n\nExamples:\n- Filter by file ID: `{\"file\": [{\"path\": \"id\", \"operator\": \"Equal\", \"valueText\": \"file-uuid\"}]}`\n- Filter by metadata: `{\"metadata\": [{\"path\": \"speaker\", \"operator\": \"Equal\", \"valueText\": \"Amy\"}]}`\n- Filter by duration: `{\"video_info\": [{\"path\": \"duration_seconds\", \"operator\": \"GreaterThan\", \"valueText\": \"60\"}]}`", "allOf": [ { "$ref": "#/components/schemas/SearchFilter" } ] }, "entity_backed_knowledge_config": { "$ref": "#/components/schemas/EntityBackedKnowledgeConfig" } } }, "KnowledgeBaseFiles": { "type": "object", "description": "Search specific files by URL or file ID. Files must have been described or added to a collection to be searchable.", "required": ["source", "files"], "properties": { "source": { "type": "string", "enum": ["files"], "description": "Source mode identifier." }, "files": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "File references to search. Can be file UUIDs, cloudglue URIs (`cloudglue://files/...`), data connector URLs, or HTTP URLs." } } }, "KnowledgeBaseDefault": { "type": "object", "description": "Search all default-indexed files for the account. Includes any file that has been described (with `use_in_default_index: true`) or added to a collection.", "required": ["source"], "properties": { "source": { "type": "string", "enum": ["default"], "description": "Source mode identifier." } } }, "EntityBackedKnowledgeConfig": { "type": "object", "description": "Configuration for entity-backed knowledge. Required when `type` is `entity_backed_knowledge`. Contains entity collections with pre-extracted structured data and optional domain context.", "required": ["entity_collections"], "properties": { "entity_collections": { "type": "array", "minItems": 1, "description": "List of entity collections that provide pre-extracted structured data. Only supported with `nimbus-002-preview` model.\n\nEntity collections contain structured entities extracted from the same videos in the main collection (e.g., action items, speakers, topics). The model can use these for fast, structured lookups instead of searching raw content.", "items": { "$ref": "#/components/schemas/EntityCollectionConfig" } }, "description": { "type": "string", "maxLength": 2000, "description": "General context about the videos in this collection. Helps the model understand the domain.\n\nExamples:\n- \"Sales call recordings with enterprise prospects from Q4 2024\"\n- \"Product demo videos for the Acme Analytics platform\"\n- \"Weekly team standup recordings from the engineering org\"" } } }, "EntityCollectionConfig": { "type": "object", "description": "Configuration for an entity collection used with `nimbus-002-preview`. Contains structured, pre-extracted data from the same videos as the main media collection.", "required": ["collection_id"], "properties": { "name": { "type": "string", "description": "Name for the entity collection (e.g., `action_items`, `speakers_and_roles`). Used by the model to decide which collection to query. Falls back to the collection's stored name if omitted." }, "description": { "type": "string", "description": "Human-readable description of what this entity collection contains. Helps the model decide when to use this collection. Falls back to the collection's stored description if omitted." }, "collection_id": { "type": "string", "format": "uuid", "description": "UUID of the entity collection. Must be an existing collection of type `entities`." } } }, "Response": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the response" }, "object": { "type": "string", "enum": ["response"], "description": "Object type identifier" }, "status": { "type": "string", "enum": ["in_progress", "completed", "failed", "cancelled"], "description": "Current status of the response" }, "created_at": { "type": "integer", "description": "Unix timestamp of when the response was created" }, "model": { "type": "string", "description": "The model used for the response" }, "instructions": { "type": "string", "nullable": true, "description": "The system instructions used" }, "output": { "type": "array", "nullable": true, "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponseOutputMessage" }, { "$ref": "#/components/schemas/ResponseFunctionCall" }, { "$ref": "#/components/schemas/ResponseQueryCall" } ] }, "description": "The generated output items: assistant message(s), any echoed function_call items, and one cloudglue_query_call per read-only SQL query the agent ran over structured data. Clients should tolerate unknown output-item types." }, "usage": { "$ref": "#/components/schemas/ResponseUsage", "nullable": true }, "error": { "$ref": "#/components/schemas/ResponseError", "nullable": true } } }, "ResponseOutputMessage": { "type": "object", "properties": { "type": { "type": "string", "enum": ["message"], "description": "The type of output" }, "role": { "type": "string", "enum": ["assistant"], "description": "The role (always assistant for outputs)" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseOutputContent" }, "description": "The content items in the output" } } }, "ResponseFunctionCall": { "type": "object", "description": "A function/tool call the model emitted (echoed back in output for client-executed tools).", "properties": { "type": { "type": "string", "enum": ["function_call"], "description": "The type of output item" }, "id": { "type": "string", "description": "Identifier for this output item" }, "call_id": { "type": "string", "description": "Correlates the call with its function_call_output" }, "name": { "type": "string", "description": "The name of the called function" }, "arguments": { "type": "string", "description": "JSON-encoded arguments to the function" } } }, "ResponseQueryCall": { "type": "object", "description": "A read-only SQL query the nimbus-002 agent ran over the structured (extracted) data. Result rows are not included in v1.", "properties": { "type": { "type": "string", "enum": ["cloudglue_query_call"], "description": "The type of output item" }, "id": { "type": "string", "description": "Identifier for this query call (query_)" }, "status": { "type": "string", "enum": ["completed", "failed"], "description": "Whether the query executed successfully" }, "sql": { "type": "string", "description": "The SQL SELECT that was executed" }, "row_count": { "type": "integer", "description": "Rows returned to the model after truncation" }, "total_rows": { "type": "integer", "nullable": true, "description": "True total when the engine saw the whole result; null when truncated" }, "truncated": { "type": "boolean", "description": "Whether the result was truncated (row or byte cap) before reaching the model" }, "error": { "type": "string", "nullable": true, "description": "Error message when status is failed; null otherwise" } } }, "ResponseOutputContent": { "type": "object", "properties": { "type": { "type": "string", "enum": ["output_text"], "description": "The type of content" }, "text": { "type": "string", "description": "The generated text" }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseAnnotation" }, "description": "Citations and references in the output" } } }, "ResponseAnnotation": { "type": "object", "required": ["type", "file_id", "start_time"], "properties": { "type": { "type": "string", "enum": ["cloudglue_citation"], "description": "The type of annotation" }, "collection_id": { "type": "string", "format": "uuid", "description": "The collection containing the cited content. Present when using `collections` source; omitted for `files` and `default` sources." }, "file_id": { "type": "string", "format": "uuid", "description": "The file containing the cited content" }, "segment_id": { "type": "string", "format": "uuid", "description": "The specific segment cited. Present when a matching segment is found." }, "start_time": { "type": "number", "description": "Start time of the cited content in seconds" }, "end_time": { "type": "number", "description": "End time of the cited segment in seconds. Present when a matching segment is found." }, "context": { "type": "string", "description": "The text context of the citation" }, "relevant_sources": { "type": "array", "items": { "type": "string" }, "description": "Relevant source descriptions (included when 'cloudglue_citations.media_descriptions' is requested)" }, "visual_scene_description": { "type": "array", "items": { "type": "string" }, "description": "Visual descriptions (included when 'cloudglue_citations.media_descriptions' is requested)" }, "scene_text": { "type": "array", "items": { "type": "string" }, "description": "On-screen text (included when 'cloudglue_citations.media_descriptions' is requested)" }, "speech": { "type": "array", "items": { "type": "string" }, "description": "Speech transcripts (included when 'cloudglue_citations.media_descriptions' is requested)" }, "audio_description": { "type": "array", "items": { "type": "string" }, "description": "Audio descriptions (included when 'cloudglue_citations.media_descriptions' is requested)" } } }, "ResponseToolDefinition": { "type": "object", "description": "Tool definition for function calling.", "required": ["type", "name", "parameters"], "properties": { "type": { "type": "string", "enum": ["function"], "description": "The type of tool (always `function`)" }, "name": { "type": "string", "minLength": 1, "description": "The name of the function" }, "description": { "type": "string", "description": "A description of what the function does" }, "parameters": { "type": "object", "description": "JSON Schema describing the function parameters", "additionalProperties": true }, "strict": { "type": "boolean", "description": "Whether to enable strict schema validation" } } }, "ResponseUsage": { "type": "object", "description": "Token usage statistics for the response", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens generated" }, "total_tokens": { "type": "integer", "description": "Total tokens used" } } }, "ResponseError": { "type": "object", "description": "Error details when the response status is 'failed'", "nullable": true, "properties": { "message": { "type": "string", "description": "Error message" }, "type": { "type": "string", "description": "Error type" }, "code": { "type": "string", "description": "Error code" } } }, "ResponseList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type identifier" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseListItem" }, "description": "List of responses" }, "total": { "type": "integer", "description": "Total number of responses matching the query" }, "limit": { "type": "integer", "description": "Maximum number of responses returned" }, "offset": { "type": "integer", "description": "Number of responses skipped" } } }, "ResponseListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the response" }, "object": { "type": "string", "enum": ["response"], "description": "Object type identifier" }, "status": { "type": "string", "enum": ["in_progress", "completed", "failed", "cancelled"], "description": "Current status of the response" }, "created_at": { "type": "integer", "description": "Unix timestamp of when the response was created" }, "model": { "type": "string", "description": "The model used for the response" }, "instructions": { "type": "string", "nullable": true, "description": "The system instructions used" }, "usage": { "$ref": "#/components/schemas/ResponseUsage", "nullable": true } } }, "DeleteResponseResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted response" }, "object": { "type": "string", "enum": ["response"], "description": "Object type identifier" }, "deleted": { "type": "boolean", "enum": [true], "description": "Indicates successful deletion" } } }, "DescribeOutputPart": { "type": "object", "properties": { "text": { "type": "string", "description": "Text content" }, "start_time": { "type": "number", "description": "Start time in seconds" }, "end_time": { "type": "number", "description": "End time in seconds" } } }, "WordTimestamp": { "type": "object", "description": "A single word with its timing information", "properties": { "word": { "type": "string", "description": "The word text" }, "start_time": { "type": "number", "description": "Start time of the word in seconds" }, "end_time": { "type": "number", "description": "End time of the word in seconds" } }, "required": ["word", "start_time", "end_time"] }, "SpeechOutputPart": { "type": "object", "properties": { "speaker": { "type": "string", "description": "Identified speaker" }, "text": { "type": "string", "description": "Transcribed speech text" }, "start_time": { "type": "number", "description": "Start time of speech in seconds" }, "end_time": { "type": "number", "description": "End time of speech in seconds" }, "words": { "type": "array", "description": "Word-level timestamps. Only present when include_word_timestamps=true. Not available for YouTube sources.", "items": { "$ref": "#/components/schemas/WordTimestamp" } } } }, "DescribeOutput": { "type": "object", "properties": { "visual_scene_description": { "type": "array", "description": "Array of visual descriptions", "items": { "$ref": "#/components/schemas/DescribeOutputPart" } }, "scene_text": { "type": "array", "description": "Array of scene text extractions", "items": { "$ref": "#/components/schemas/DescribeOutputPart" } }, "speech": { "type": "array", "description": "Array of speech transcriptions", "items": { "$ref": "#/components/schemas/SpeechOutputPart" } }, "audio_description": { "type": "array", "description": "Array of audio descriptions", "items": { "$ref": "#/components/schemas/DescribeOutputPart" } } } }, "Extract": { "required": ["job_id", "status"], "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ] }, "url": { "type": "string", "description": "The URL of the processed video" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the job was created" }, "extract_config": { "type": "object", "description": "Configuration for automatic entity extraction from videos", "properties": { "prompt": { "type": "string", "description": "A natural language prompt describing the data to extract. Required if no schema is provided." }, "schema": { "type": "object", "description": "A more rigid structure if you already know the JSON layout you want. Required if no prompt is provided." }, "enable_video_level_entities": { "type": "boolean", "description": "Whether to extract entities at the video level. Mutually exclusive with enable_segment_level_entities - only one can be true." }, "enable_segment_level_entities": { "type": "boolean", "description": "Whether to extract entities at the segment level. Mutually exclusive with enable_video_level_entities - only one can be true." }, "enable_transcript_mode": { "type": "boolean", "description": "When enabled, extract entities from transcript only (similar to YouTube path). Useful for speech-heavy content." }, "enable_metadata_mode": { "type": "boolean", "description": "When enabled, extract entities from the file's metadata document (filename, file details, user metadata, and connector source metadata) instead of the media content. File-level entities only; flat 1 credit per file; works on metadata-only files without ingesting their media. Mutually exclusive with enable_transcript_mode." } } }, "segmentation_id": { "type": "string", "description": "The ID of the segmentation job used for this extraction" }, "data": { "description": "The structured data extracted from the video based on prompt or schema. Only present when status is 'completed'.", "type": "object", "properties": { "entities": { "type": "object", "description": "Entities extracted from the video level" }, "segment_entities": { "type": "array", "description": "Array of video entities extracted from individual time segments", "items": { "type": "object", "properties": { "start_time": { "type": "number", "description": "Start time of the segment in seconds" }, "end_time": { "type": "number", "description": "End time of the segment in seconds" }, "entities": { "type": "object", "description": "Entities extracted from the segment" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the segment thumbnail, when available." } } } }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the file-level thumbnail for the video. Only present when include_thumbnails=true." } } }, "total": { "type": "integer", "description": "Total number of segment entities available. Only present when status is 'completed'." }, "limit": { "type": "integer", "description": "Maximum number of segment entities returned per request. Only present when status is 'completed'." }, "offset": { "type": "integer", "description": "Number of segment entities skipped. Only present when status is 'completed'." }, "error": { "type": "string", "description": "Error message if status is 'failed'" }, "chapters": { "type": "array", "description": "Array of narrative chapters (only present when include_chapters=true and segmentation strategy is 'narrative')", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "start_time": { "type": "number", "minimum": 0 }, "end_time": { "type": "number", "minimum": 0 }, "description": { "type": "string" } }, "required": ["index", "start_time", "end_time", "description"] } }, "shots": { "type": "array", "description": "Array of shot boundaries (only present when include_shots=true and segmentation strategy is 'shot-detector')", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "start_time": { "type": "number", "minimum": 0 }, "end_time": { "type": "number", "minimum": 0 } }, "required": ["index", "start_time", "end_time"] } }, "total_chapters": { "type": "integer", "minimum": 0, "description": "Total number of chapters (only present when include_chapters=true and segmentation strategy is 'narrative')" }, "total_shots": { "type": "integer", "minimum": 0, "description": "Total number of shots (only present when include_shots=true and segmentation strategy is 'shot-detector')" } } }, "ExtractList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Extract" }, "description": "Array of extract job objects" }, "total": { "type": "integer", "description": "Total number of extract jobs matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "NewExtract": { "allOf": [ { "required": ["url"], "type": "object", "properties": { "url": { "description": "Input media URL. Supports URIs of files uploaded to Cloudglue Files endpoint, public YouTube video URLs, public TikTok video URLs, public Loom share URLs, public HTTP URLs (including direct image URLs such as JPEG/PNG/WebP), and files which have been granted access to Cloudglue via data connectors.\n\nNote that YouTube videos are currently limited to speech level understanding only. Public TikTok video URLs will be scraped and stored automatically — subject to charges. For files via our Data connectors, see our documentation on data connectors for setup information.", "type": "string" }, "prompt": { "description": "A natural language prompt describing the data you want to extract. Required if no schema is provided.", "type": "string" }, "schema": { "description": "A more rigid structure if you already know the JSON layout you want. Required if no prompt is provided.", "type": "object" }, "enable_video_level_entities": { "type": "boolean", "description": "Whether to extract entities at the video level. Mutually exclusive with enable_segment_level_entities - only one can be true." }, "enable_segment_level_entities": { "type": "boolean", "description": "Whether to extract entities at the segment level. Mutually exclusive with enable_video_level_entities - only one can be true." }, "enable_transcript_mode": { "type": "boolean", "description": "When enabled, extract entities from transcript only (similar to YouTube path). Useful for speech-heavy content." }, "enable_metadata_mode": { "type": "boolean", "description": "When enabled, extract entities from the file's metadata document (filename, file details, user metadata, and connector source metadata) instead of the media content. File-level entities only; flat 1 credit per file; works on metadata-only files without ingesting their media. Mutually exclusive with enable_transcript_mode." }, "thumbnails_config": { "$ref": "#/components/schemas/ThumbnailsConfig" }, "include_chapters": { "type": "boolean", "description": "Include narrative chapters in the response when segmentation strategy is 'narrative'. Only affects cached completed results; newly created pending jobs do not include chapters.", "default": false }, "include_shots": { "type": "boolean", "description": "Include shot boundaries in the response when segmentation strategy is 'shot-detector'. Only affects cached completed results; newly created pending jobs do not include shots.", "default": false } } }, { "$ref": "#/components/schemas/FileSegmentationConfig" } ] }, "File": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the file" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ], "description": "Processing status of the file" }, "bytes": { "type": "integer", "nullable": true, "description": "Size of the file in bytes, null if not available" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the file was created" }, "filename": { "type": "string", "description": "Original filename" }, "uri": { "type": "string", "description": "Cloudglue URI for the file, to be used in other API calls" }, "metadata": { "type": "object", "nullable": true, "description": "User-provided metadata about the file, null if none provided" }, "media_type": { "type": "string", "enum": ["video", "audio", "image"], "description": "Type of media file (video, audio, or image). Images are processed at the file level only (no segmentation)." }, "media_info": { "type": "object", "properties": { "duration_seconds": { "type": "number", "nullable": true, "description": "Duration in seconds" }, "width": { "type": "integer", "nullable": true, "description": "Width in pixels (null for audio files)" }, "height": { "type": "integer", "nullable": true, "description": "Height in pixels (null for audio files)" }, "sample_rate": { "type": "integer", "nullable": true, "description": "Audio sample rate in Hz" }, "channels": { "type": "integer", "nullable": true, "description": "Number of audio channels" }, "bitrate": { "type": "integer", "nullable": true, "description": "Audio bitrate in bps" }, "format": { "type": "string", "nullable": true, "description": "File format" }, "has_audio": { "type": "boolean", "nullable": true, "description": "Whether the file has audio" } }, "description": "Unified media information for video, audio, and image files" }, "video_info": { "type": "object", "properties": { "duration_seconds": { "type": "number", "nullable": true, "description": "Duration of the video in seconds, null if not available" }, "height": { "type": "integer", "nullable": true, "description": "Height of the video in pixels, null if not available" }, "width": { "type": "integer", "nullable": true, "description": "Width of the video in pixels, null if not available" }, "format": { "type": "string", "nullable": true, "description": "Format of the video file, null if not available" }, "has_audio": { "type": "boolean", "nullable": true, "description": "Whether the video has audio, null if not available" } }, "description": "Information about the video content" }, "thumbnail_url": { "type": "string", "description": "URL of the thumbnail for the file" }, "source": { "type": "string", "enum": [ "video", "youtube", "s3", "dropbox", "http", "upload", "google-drive", "zoom", "gong", "recall", "gcs", "grain", "loom", "iconik" ], "description": "Source of the file" }, "source_metadata": { "allOf": [ { "$ref": "#/components/schemas/SourceMetadata" } ], "nullable": true, "description": "Source provenance captured from the upstream connector at ingest time. Null when nothing was captured (older files, or a connector that does not yet populate it)." } }, "required": ["id", "uri", "status"] }, "FileUpload": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The video, audio, or image file to be uploaded" }, "metadata": { "type": "object", "description": "User-provided metadata about the file" }, "enable_segment_thumbnails": { "type": "boolean", "description": "Whether to generate thumbnails for each segment" } }, "required": ["file"] }, "FileList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/File" }, "description": "Array of file objects" }, "total": { "type": "integer", "description": "Total number of files matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "FileDelete": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted file" }, "object": { "type": "string", "enum": ["file"], "description": "Object type, always 'file'" } }, "required": ["id", "object"] }, "FileUpdate": { "type": "object", "properties": { "metadata": { "type": "object", "description": "Optional user-provided metadata about the file" }, "filename": { "type": "string", "description": "New filename for the file" } } }, "Collection": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the collection" }, "object": { "type": "string", "enum": ["collection"], "description": "Object type, always 'collection'" }, "name": { "type": "string", "description": "Name of the collection" }, "description": { "type": "string", "nullable": true, "description": "Description of the collection's purpose or contents, null if none provided" }, "collection_type": { "type": "string", "enum": [ "media-descriptions", "entities", "rich-transcripts", "face-analysis", "metadata", "moments" ], "description": "Type of collection, determines how videos are processed and what data is extracted" }, "moments_config": { "type": "object", "description": "Moments collections only: the criteria echo with per-attachment state (live counters on single GETs).", "properties": { "criteria": { "type": "array", "items": { "$ref": "#/components/schemas/MomentCriterionAttachment" } } } }, "extract_config": { "type": "object", "description": "Configuration for automatic entity extraction from videos. Required when collection_type is 'entities'.", "properties": { "prompt": { "type": "string", "description": "A natural language prompt describing the data to extract. Required if no schema is provided." }, "schema": { "type": "object", "description": "A more rigid structure if you already know the JSON layout you want. Required if no prompt is provided." }, "enable_video_level_entities": { "type": "boolean", "description": "Whether to extract entities at the video level. Mutually exclusive with enable_segment_level_entities - only one can be true." }, "enable_segment_level_entities": { "type": "boolean", "description": "Whether to extract entities at the segment level. Mutually exclusive with enable_video_level_entities - only one can be true." }, "enable_transcript_mode": { "type": "boolean", "description": "When enabled, extract entities from transcript only. Useful for speech-heavy content." }, "enable_metadata_mode": { "type": "boolean", "description": "When enabled, every file added to this entities collection is extracted from its metadata document (filename, file details, user metadata, and connector source metadata) instead of the media content. File-level entities only; flat 1 credit per file; metadata-only files are never ingested. Mutually exclusive with enable_transcript_mode." } } }, "transcribe_config": { "type": "object", "description": "Configuration for rich transcription from videos. Used when collection_type is 'rich-transcripts'. If not provided, default values will be used.", "properties": { "enable_summary": { "type": "boolean", "description": "Whether to generate video-level and segment-level (moment-level) summaries and titles" }, "enable_speech": { "type": "boolean", "description": "Whether to generate speech transcript" }, "enable_scene_text": { "type": "boolean", "description": "Whether to generate scene text extraction" }, "enable_visual_scene_description": { "type": "boolean", "description": "Whether to generate visual scene description" }, "enable_audio_description": { "type": "boolean", "description": "Whether to generate audio description" } } }, "describe_config": { "type": "object", "description": "Configuration for comprehensive media description from videos. Used when collection_type is 'media-descriptions'. If not provided, default values will be used.", "properties": { "enable_summary": { "type": "boolean", "description": "Whether to generate video-level and segment-level (moment-level) summaries and titles" }, "enable_speech": { "type": "boolean", "description": "Whether to generate speech transcript" }, "enable_scene_text": { "type": "boolean", "description": "Whether to generate scene text extraction" }, "enable_visual_scene_description": { "type": "boolean", "description": "Whether to generate visual scene description" }, "enable_audio_description": { "type": "boolean", "description": "Whether to generate audio description" }, "prompt": { "type": "string", "description": "Optional free-form guidance applied when describing every file in the collection. Use it to name the terms, product names, acronyms, or people that matter for this collection and how they are spelled, or to say what the descriptions should pay attention to — e.g. \"Spell product names as Cloudglue and Aviary; call out any pricing discussed\". It steers emphasis and vocabulary across the visual, scene-text, speech, and summary passes; it cannot make a description report content that is not in the media, and it does not change the response shape. Like the rest of the describe config it is fixed at creation — files already in the collection were described under the original guidance." } } }, "default_segmentation_config": { "$ref": "#/components/schemas/SegmentationConfig", "description": "Default segmentation configuration used for files in this collection" }, "default_thumbnails_config": { "$ref": "#/components/schemas/ThumbnailsConfig", "description": "Default thumbnails configuration used for files in this collection" }, "face_detection_config": { "type": "object", "nullable": true, "description": "Configuration for face detection in videos. Only present when collection_type is 'face-analysis'.", "properties": { "frame_extraction_config": { "type": "object", "properties": { "strategy": { "type": "string", "enum": ["uniform"], "description": "Frame extraction strategy" }, "uniform_config": { "type": "object", "properties": { "frames_per_second": { "type": "number", "minimum": 0.1, "maximum": 30, "description": "Number of frames to extract per second" }, "max_width": { "type": "number", "minimum": 64, "maximum": 4096, "description": "Maximum width of frames in pixels (aspect ratio preserved)" } } } }, "required": ["strategy"] }, "thumbnails_config": { "type": "object", "properties": { "enable_frame_thumbnails": { "type": "boolean", "description": "Whether to generate thumbnails for extracted frames" } } } } }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the collection was created" }, "file_count": { "type": "integer", "description": "Number of files in the collection" } }, "required": [ "id", "object", "name", "created_at", "file_count", "collection_type" ] }, "CollectionUpdate": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the collection" }, "description": { "type": "string", "description": "Description of the collection" } } }, "NewCollection": { "type": "object", "properties": { "collection_type": { "type": "string", "enum": [ "media-descriptions", "entities", "rich-transcripts", "face-analysis", "metadata", "moments" ], "description": "Type of collection, determines how videos are processed and what data is extracted.\n\n**Collection Types:**\n- **media-descriptions**: Generate comprehensive media descriptions with speech, visual, and text analysis (use `describe_config`)\n- **entities**: Extract structured data/entities from videos (requires `extract_config`)\n- **rich-transcripts**: Generate rich transcriptions with speech and visual descriptions (use `transcribe_config`). For backward compatibility only, new collections should use `media-descriptions` instead.\n- **face-analysis**: Detect and index faces in videos for face matching and search (use `face_detection_config`)\n- **metadata**: Index connector source metadata + user metadata into file-level search documents WITHOUT downloading or processing the media. Free to index. Supports google-drive, dropbox, zoom, gong, recall, grain, and iconik URLs. No processing configs are accepted.\n\n⚠️ **Important**: Only provide the config that matches your collection_type. Other configs will be ignored." }, "moments_config": { "$ref": "#/components/schemas/MomentsConfig" }, "name": { "type": "string", "description": "Name of the collection (must be unique within an organization)" }, "description": { "type": "string", "nullable": true, "description": "Description of the collection's purpose or contents, null if none provided" }, "describe_config": { "type": "object", "description": "🎯 **Use ONLY when collection_type = 'media-descriptions'**\n\nConfiguration for comprehensive media description from videos. Optional - if not provided, default values will be used. This config will be ignored for other collection types.", "properties": { "enable_summary": { "type": "boolean", "description": "Whether to generate video-level and segment-level (moment-level) summaries and titles" }, "enable_speech": { "type": "boolean", "description": "Whether to generate speech transcript" }, "enable_scene_text": { "type": "boolean", "description": "Whether to generate scene text extraction" }, "enable_visual_scene_description": { "type": "boolean", "description": "Whether to generate visual scene description" }, "enable_audio_description": { "type": "boolean", "description": "Whether to generate audio description" }, "prompt": { "type": "string", "maxLength": 2000, "description": "Optional free-form guidance applied when describing every file in the collection. Use it to name the terms, product names, acronyms, or people that matter for this collection and how they are spelled, or to say what the descriptions should pay attention to — e.g. \"Spell product names as Cloudglue and Aviary; call out any pricing discussed\". It steers emphasis and vocabulary across the visual, scene-text, speech, and summary passes; it cannot make a description report content that is not in the media, and it does not change the response shape. Like the rest of the describe config it is fixed at creation — files already in the collection were described under the original guidance." } } }, "extract_config": { "type": "object", "description": "🎯 **Use ONLY when collection_type = 'entities'**\n\nConfiguration for automatic entity extraction from videos. Required for entities collections. This config will be ignored for other collection types.", "properties": { "prompt": { "type": "string", "description": "A natural language prompt describing the data to extract. Required if no schema is provided." }, "schema": { "type": "object", "description": "A more rigid structure if you already know the JSON layout you want. Required if no prompt is provided." }, "enable_video_level_entities": { "type": "boolean", "description": "Whether to extract entities at the video level. Mutually exclusive with enable_segment_level_entities - only one can be true." }, "enable_segment_level_entities": { "type": "boolean", "description": "Whether to extract entities at the segment level. Mutually exclusive with enable_video_level_entities - only one can be true." }, "enable_transcript_mode": { "type": "boolean", "description": "When enabled, extract entities from transcript only. Useful for speech-heavy content." }, "enable_metadata_mode": { "type": "boolean", "description": "When enabled, every file added to this entities collection is extracted from its metadata document (filename, file details, user metadata, and connector source metadata) instead of the media content. File-level entities only; flat 1 credit per file; metadata-only files are never ingested. Mutually exclusive with enable_transcript_mode." } } }, "transcribe_config": { "type": "object", "description": "🎯 **Use ONLY when collection_type = 'rich-transcripts'**\n\nConfiguration for rich transcription from videos. Optional - if not provided, default values will be used. This config will be ignored for other collection types.", "properties": { "enable_summary": { "type": "boolean", "description": "Whether to generate video-level and segment-level (moment-level) summaries and titles" }, "enable_speech": { "type": "boolean", "description": "Whether to generate speech transcript" }, "enable_scene_text": { "type": "boolean", "description": "Whether to generate scene text extraction" }, "enable_visual_scene_description": { "type": "boolean", "description": "Whether to generate visual scene description" }, "enable_audio_description": { "type": "boolean", "description": "Whether to generate audio description" } } }, "default_segmentation_config": { "$ref": "#/components/schemas/DefaultSegmentationConfig", "description": "Default segmentation configuration to use for files added to this collection. If not provided, a default uniform segmentation will be used." }, "default_thumbnails_config": { "$ref": "#/components/schemas/ThumbnailsConfig", "description": "Default thumbnails configuration to use for files added to this collection. If not provided, a default thumbnails configuration will be used." }, "face_detection_config": { "type": "object", "description": "🎯 **Use ONLY when collection_type = 'face-analysis'**\n\nConfiguration for face detection in videos. Optional - if not provided, default values will be used. This config will be ignored for other collection types.", "properties": { "frame_extraction_config": { "type": "object", "properties": { "strategy": { "type": "string", "enum": ["uniform"], "description": "Frame extraction strategy" }, "uniform_config": { "type": "object", "properties": { "frames_per_second": { "type": "number", "minimum": 0.1, "maximum": 30, "description": "Number of frames to extract per second" }, "max_width": { "type": "number", "minimum": 64, "maximum": 4096, "description": "Maximum width of frames in pixels (aspect ratio preserved)" } } } }, "required": ["strategy"] }, "thumbnails_config": { "type": "object", "properties": { "enable_frame_thumbnails": { "type": "boolean", "description": "Whether to generate thumbnails for extracted frames" } } } } } }, "required": ["collection_type", "name"] }, "CollectionList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" }, "description": "Array of collection objects" }, "total": { "type": "integer", "description": "Total number of collections matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "CollectionDelete": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted collection" }, "object": { "type": "string", "enum": ["collection"], "description": "Object type, always 'collection'" } }, "required": ["id", "object"] }, "AddCollectionFile": { "allOf": [ { "type": "object", "oneOf": [ { "type": "object", "properties": { "file_id": { "type": "string", "description": "The ID of the file to add to the collection" } }, "required": ["file_id"] }, { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the video to add to the collection. Supports URIs of files uploaded to Cloudglue Files endpoint, public YouTube video URLs, public TikTok video URLs, public Loom share URLs, public HTTP URLs, and files which have been granted access to Cloudglue via data connectors.\n\nNote that YouTube videos are currently limited to speech level understanding only. Public TikTok video URLs will be scraped and stored automatically — subject to charges. For files via our Data connectors, see our documentation on data connectors for setup information." } }, "required": ["url"] } ] }, { "$ref": "#/components/schemas/FileSegmentationConfig" }, { "type": "object", "properties": { "thumbnails_config": { "$ref": "#/components/schemas/ThumbnailsConfig" }, "metadata": { "type": "object", "description": "User metadata stored on the file (merged into the file's metadata and included in the indexed metadata doc). Only supported when adding to metadata collections; other collection types take metadata via the Files endpoints." } } } ] }, "AddYouTubeCollectionFile": { "allOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the YouTube video to add to the collection.\n\nNote that YouTube videos are currently limited to speech and metadata level understanding, for fully fledge multimodal video understanding please upload a file instead to the Files API and use that object instead as input." }, "metadata": { "type": "object", "description": "User-provided metadata about the YouTube video" } }, "required": ["url"] }, { "$ref": "#/components/schemas/FileSegmentationConfig" } ] }, "CollectionFile": { "type": "object", "properties": { "collection_id": { "type": "string", "description": "ID of the collection" }, "file_id": { "type": "string", "description": "ID of the file" }, "object": { "type": "string", "enum": ["collection_file"], "description": "Object type, always 'collection_file'" }, "added_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the file was added to the collection" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ], "description": "Overall processing status of the file in this collection" }, "searchable_status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Indexing status of the file's search documents in this collection. Only present for media-descriptions, rich-transcripts, metadata, and entities collections. For entities collections it tracks entity indexing: file-level collections index one document per file, segment-level collections one per segment." }, "file": { "$ref": "#/components/schemas/File", "description": "The file object" }, "segmentation": { "type": "object", "description": "Segmentation information for this file in the collection. Only present when the file has been segmented.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the segmentation" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ], "description": "Status of the segmentation job" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file that was segmented" }, "segmentation_config": { "$ref": "#/components/schemas/SegmentationConfig", "description": "Configuration used for this segmentation" } }, "required": ["id", "status", "file_id", "segmentation_config"] } }, "required": ["collection_id", "file_id", "object", "added_at", "status"] }, "CollectionFileList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionFile" }, "description": "Array of collection file objects" }, "total": { "type": "integer", "description": "Total number of files matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "CollectionFileDelete": { "type": "object", "properties": { "collection_id": { "type": "string", "description": "ID of the collection" }, "file_id": { "type": "string", "description": "ID of the file" }, "object": { "type": "string", "enum": ["collection_file"], "description": "Object type, always 'collection_file'" } }, "required": ["collection_id", "file_id", "object"] }, "FileEntities": { "type": "object", "properties": { "collection_id": { "type": "string", "description": "ID of the collection" }, "file_id": { "type": "string", "description": "ID of the file" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the file-level thumbnail for the video. Only present when include_thumbnails=true." }, "entities": { "type": "object", "description": "Entities extracted from the file at the video level" }, "segment_entities": { "type": "array", "description": "Array of video entities extracted from individual time segments", "items": { "type": "object", "properties": { "start_time": { "type": "number", "description": "Start time of the segment in seconds" }, "end_time": { "type": "number", "description": "End time of the segment in seconds" }, "entities": { "type": "object", "description": "Entities extracted from the segment" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the segment thumbnail, when available." } } } }, "total": { "type": "integer", "description": "Total number of segment entities available" }, "limit": { "type": "integer", "description": "Maximum number of entities returned per request" }, "offset": { "type": "integer", "description": "Number of entities skipped" }, "chapters": { "type": "array", "description": "Array of narrative chapters (only present when include_chapters=true and segmentation strategy is 'narrative')", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "start_time": { "type": "number", "minimum": 0 }, "end_time": { "type": "number", "minimum": 0 }, "description": { "type": "string" } }, "required": ["index", "start_time", "end_time", "description"] } }, "shots": { "type": "array", "description": "Array of shot boundaries (only present when include_shots=true and segmentation strategy is 'shot-detector')", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "start_time": { "type": "number", "minimum": 0 }, "end_time": { "type": "number", "minimum": 0 } }, "required": ["index", "start_time", "end_time"] } }, "total_chapters": { "type": "integer", "minimum": 0, "description": "Total number of chapters (only present when include_chapters=true and segmentation strategy is 'narrative')" }, "total_shots": { "type": "integer", "minimum": 0, "description": "Total number of shots (only present when include_shots=true and segmentation strategy is 'shot-detector')" } }, "required": [ "collection_id", "file_id", "entities", "segment_entities", "total", "limit", "offset" ] }, "FileFaceDetections": { "type": "object", "properties": { "collection_id": { "type": "string", "description": "ID of the collection" }, "file_id": { "type": "string", "description": "ID of the file" }, "faces": { "type": "array", "description": "Array of detected faces", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the detected face" }, "face_bounding_box": { "type": "object", "properties": { "height": { "type": "number", "minimum": 0, "maximum": 1, "description": "Height of the bounding box (normalized 0-1)" }, "width": { "type": "number", "minimum": 0, "maximum": 1, "description": "Width of the bounding box (normalized 0-1)" }, "top": { "type": "number", "minimum": 0, "maximum": 1, "description": "Top position of the bounding box (normalized 0-1)" }, "left": { "type": "number", "minimum": 0, "maximum": 1, "description": "Left position of the bounding box (normalized 0-1)" } }, "required": ["height", "width", "top", "left"] }, "frame_id": { "type": "string", "format": "uuid", "description": "ID of the frame where the face was detected" }, "timestamp": { "type": "number", "minimum": 0, "description": "Timestamp of the frame in seconds" }, "thumbnail_url": { "type": "string", "description": "URL of the frame thumbnail (if frame extraction enabled thumbnails)" } }, "required": ["id", "face_bounding_box", "frame_id", "timestamp"] } }, "total": { "type": "integer", "description": "Total number of faces detected" }, "limit": { "type": "integer", "description": "Maximum number of faces returned per request" }, "offset": { "type": "integer", "description": "Number of faces skipped" } }, "required": [ "collection_id", "file_id", "faces", "total", "limit", "offset" ] }, "Error": { "required": ["error"], "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "description": "Machine-readable error code, present on some errors. Known values: `usage_limit_reached` marks a 403 for an exhausted account usage limit (separate from credits); retrying will not succeed until the limit is raised or the period resets. More codes may be added, so treat unknown values as absent." } } }, "ChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string", "description": "Name of the video understanding model to use.", "enum": ["nimbus-001"] }, "messages": { "type": "array", "description": "A list of messages comprising the conversation so far", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "collections": { "type": "array", "description": "List of collection IDs to use as context for the chat.\n\nNote that 'nimbus-001' only supports collections with collection_type 'media-descriptions' or 'rich-transcripts'", "items": { "type": "string" }, "minItems": 1, "maxItems": 1 }, "filter": { "type": "object", "description": "Filter criteria to constrain search results used in chat", "properties": { "metadata": { "type": "array", "description": "Filter by file metadata using JSON path expressions", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path on metadata object (e.g. 'my_custom_field', 'category.subcategory')" }, "operator": { "type": "string", "enum": [ "NotEqual", "Equal", "LessThan", "GreaterThan", "In", "ContainsAny", "ContainsAll" ], "description": "Comparison operator to apply" }, "valueText": { "type": "string", "description": "Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, In)" }, "valueTextArray": { "type": "array", "items": { "type": "string" }, "description": "Array of values for array comparisons (used with ContainsAny, ContainsAll)" } }, "required": ["path", "operator"] } }, "video_info": { "type": "array", "description": "Filter by video information. Use scope 'file' for source video properties or 'segment' for segment properties (e.g. segment duration).", "items": { "type": "object", "properties": { "path": { "type": "string", "enum": ["duration_seconds", "has_audio"], "description": "JSON path on video_info object (e.g. 'has_audio', 'duration_seconds')" }, "scope": { "type": "string", "enum": ["file", "segment"], "description": "Scope of the filter. 'file' filters by source video properties, 'segment' filters by segment properties. Only duration_seconds is supported with segment scope." }, "operator": { "type": "string", "enum": [ "NotEqual", "Equal", "LessThan", "GreaterThan", "In", "ContainsAny", "ContainsAll" ], "description": "Comparison operator to apply" }, "valueText": { "type": "string", "description": "Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, In)" }, "valueTextArray": { "type": "array", "items": { "type": "string" }, "description": "Array of values for array comparisons (used with ContainsAny, ContainsAll)" } }, "required": ["path", "operator"] } }, "file": { "type": "array", "description": "Filter by file properties using JSON path expressions", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path on file object (e.g. 'uri', 'id', 'filename', 'created_at', 'bytes')" }, "operator": { "type": "string", "enum": [ "NotEqual", "Equal", "LessThan", "GreaterThan", "In", "ContainsAny", "ContainsAll" ], "description": "Comparison operator to apply" }, "valueText": { "type": "string", "description": "Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, In)" }, "valueTextArray": { "type": "array", "items": { "type": "string" }, "description": "Array of values for array comparisons (used with ContainsAny, ContainsAll)" } }, "required": ["path", "operator"] } } } }, "temperature": { "type": "number", "description": "Sampling temperature to use, between 0 and 2", "minimum": 0, "maximum": 2 } }, "required": ["model", "messages", "collections"] }, "ChatMessage": { "type": "object", "properties": { "role": { "type": "string", "description": "The role of the message author", "enum": ["system", "user", "assistant"] }, "content": { "type": "string", "description": "The content of the message" }, "name": { "type": "string", "description": "The name of the author of this message" } }, "required": ["role", "content"] }, "ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this chat completion" }, "object": { "type": "string", "description": "Object type, always \"chat.completion\"" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the chat completion was created" }, "model": { "type": "string", "description": "The model used for the chat completion" }, "choices": { "type": "array", "description": "The generated responses", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "The index of this choice" }, "message": { "$ref": "#/components/schemas/ChatMessage", "description": "The chat message generated by the model" }, "citations": { "type": "array", "description": "Citations to specific video segments that informed the response", "items": { "allOf": [ { "type": "object", "properties": { "collection_id": { "type": "string", "description": "ID of the collection containing the cited video" }, "file_id": { "type": "string", "description": "ID of the file being cited" }, "segment_id": { "type": "string", "description": "ID of the segment being cited" }, "start_time": { "oneOf": [ { "type": "string", "description": "Start time of the cited segment in seconds" }, { "type": "number", "description": "Start time of the cited segment in seconds" } ], "description": "Start time of the cited segment in seconds" }, "end_time": { "oneOf": [ { "type": "string", "description": "End time of the cited segment in seconds" }, { "type": "number", "description": "End time of the cited segment in seconds" } ], "description": "End time of the cited segment in seconds" }, "text": { "type": "string", "description": "(Deprecated) Relevant text from the segment; use context and relevant_sources instead" }, "context": { "type": "string", "description": "Short explanation of the relevance of the segment to the query provided as context" }, "relevant_sources": { "type": "array", "description": "List of source modalities in segment that are relevant for this citation", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Source modality, one of visual_scene_description, scene_text, speech" } } } } } }, { "$ref": "#/components/schemas/DescribeOutput" } ] } } } } }, "payload": { "$ref": "#/components/schemas/ChatCompletionPayload" }, "usage": { "type": "object", "description": "Usage statistics for the completion request", "properties": { "prompt_tokens": { "type": "integer", "description": "Number of tokens in the prompt" }, "completion_tokens": { "type": "integer", "description": "Number of tokens in the generated completion" }, "total_tokens": { "type": "integer", "description": "Total number of tokens used in the request" } } } } }, "Transcribe": { "required": ["job_id", "status"], "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ] }, "url": { "type": "string", "description": "The URL of the processed video" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the job was created" }, "transcribe_config": { "type": "object", "description": "Configuration for rich transcription from videos", "properties": { "enable_summary": { "type": "boolean", "description": "Whether the user requested to generate video-level and segment-level (moment-level) summaries and titles" }, "enable_speech": { "type": "boolean", "description": "Whether the user requested to generate speech transcript" }, "enable_visual_scene_description": { "type": "boolean", "description": "Whether the user requested to generate visual scene description" }, "enable_scene_text": { "type": "boolean", "description": "Whether the user requested to generate scene text" } } }, "data": { "allOf": [ { "type": "object", "properties": { "content": { "type": "string", "description": "Content string returned based on formatting, e.g. set to markdown text when response_format=markdown is requested" }, "title": { "type": "string", "description": "Generated title of the video; for YouTube videos, this is the title of the video as it appears on YouTube" }, "summary": { "type": "string", "description": "Generated video level summary; for YouTube videos, this is the summary of the video as it appears on YouTube" }, "segment_summary": { "type": "array", "description": "Array of summary information for each segment of the video. Only available when enable_summary is set to true in the transcribe configuration.", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Generated segment-level title" }, "summary": { "type": "string", "description": "Generated segment-level summary" }, "start_time": { "type": "number", "description": "Start time of segment in seconds" }, "end_time": { "type": "number", "description": "End time of segment in seconds" } } } } } }, { "$ref": "#/components/schemas/DescribeOutput" } ] }, "error": { "type": "string", "description": "Error message if status is 'failed'" }, "file": { "allOf": [ { "$ref": "#/components/schemas/File" } ], "description": "The file this document describes. `metadata` and `source_metadata` are only included when `include_metadata` is true." } } }, "NewTranscribe": { "allOf": [ { "type": "object", "required": ["url"], "properties": { "url": { "description": "Input video URL. Supports URIs of files uploaded to Cloudglue Files endpoint, public YouTube video URLs, public TikTok video URLs, public Loom share URLs, public HTTP URLs, and files which have been granted access to Cloudglue via data connectors.\n\nNote that YouTube videos are currently limited to speech level understanding only. Public TikTok video URLs will be scraped and stored automatically — subject to charges. For files via our Data connectors, see our documentation on data connectors for setup information.", "type": "string" }, "enable_summary": { "description": "Whether to generate video-level and segment-level (moment-level) summaries and titles", "type": "boolean" }, "enable_speech": { "description": "Whether to generate speech transcript", "type": "boolean" }, "enable_visual_scene_description": { "description": "Whether to generate visual scene description", "type": "boolean" }, "enable_scene_text": { "description": "Whether to generate scene text extraction", "type": "boolean" }, "enable_audio_description": { "description": "Whether to generate audio description", "type": "boolean" }, "thumbnails_config": { "$ref": "#/components/schemas/ThumbnailsConfig" }, "include_metadata": { "type": "boolean", "default": false, "description": "Include the file's user-defined metadata and source metadata on the returned `file` object." } } }, { "$ref": "#/components/schemas/FileSegmentationConfig" } ] }, "TranscribeList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transcribe" }, "description": "Array of transcription job objects" }, "total": { "type": "integer", "description": "Total number of transcription jobs matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" } }, "required": ["object", "data", "total", "limit"] }, "DescribeConfig": { "type": "object", "description": "Configuration for media description from videos", "properties": { "enable_summary": { "type": "boolean", "description": "Whether to generate video-level and segment-level (moment-level) summaries and titles" }, "enable_speech": { "type": "boolean", "description": "Whether to generate speech transcript" }, "enable_visual_scene_description": { "type": "boolean", "description": "Whether to generate visual scene description" }, "enable_scene_text": { "type": "boolean", "description": "Whether to generate scene text extraction" }, "enable_audio_description": { "type": "boolean", "description": "Whether to generate audio description" }, "prompt": { "type": "string", "maxLength": 2000, "description": "Optional free-form guidance for the description. Use it to name the terms, product names, acronyms, or people that matter for this media and how they are spelled, or to say what the description should pay attention to — e.g. \"Spell product names as Cloudglue and Aviary; call out any pricing discussed\". It steers emphasis and vocabulary across the visual, scene-text, speech, and summary passes; it cannot make the description report content that is not in the media, and it does not change the response shape. To *constrain* transcript speaker labels to a known cast, use `participants` instead — a prompt is context, not a constraint. Changing it produces a new describe job rather than reusing a cached one." } } }, "SegmentDescribeOutputEntry": { "type": "object", "description": "A single describe output entry with timestamp", "properties": { "text": { "type": "string", "description": "The text content" }, "start_time": { "type": "number", "description": "Start time in seconds" }, "end_time": { "type": "number", "description": "End time in seconds" } }, "required": ["text", "start_time", "end_time"] }, "SegmentDescribeSpeechEntry": { "type": "object", "description": "A speech entry with optional speaker information", "properties": { "text": { "type": "string", "description": "The speech text" }, "start_time": { "type": "number", "description": "Start time in seconds" }, "end_time": { "type": "number", "description": "End time in seconds" }, "speaker": { "type": "string", "description": "Speaker identifier" } }, "required": ["text", "start_time", "end_time"] }, "SegmentDescribeJsonData": { "type": "object", "description": "JSON format describe output data", "properties": { "visual_scene_description": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDescribeOutputEntry" }, "description": "Visual scene descriptions with timestamps" }, "speech": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDescribeSpeechEntry" }, "description": "Speech transcript with timestamps and speaker info" }, "scene_text": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDescribeOutputEntry" }, "description": "On-screen text detected with timestamps" }, "audio_description": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDescribeOutputEntry" }, "description": "Audio descriptions with timestamps" }, "title": { "type": "string", "description": "Generated title for the segment" }, "summary": { "type": "string", "description": "Generated summary for the segment" }, "start_time": { "type": "number", "description": "Start time of the segment in seconds" }, "end_time": { "type": "number", "description": "End time of the segment in seconds" }, "segment_id": { "type": "string", "format": "uuid", "description": "The ID of the segment" } } }, "SegmentDescribeMarkdownData": { "type": "object", "description": "Markdown format describe output data", "properties": { "content": { "type": "string", "description": "Markdown formatted content containing the describe output" } }, "required": ["content"] }, "SegmentDescribe": { "type": "object", "description": "Describe output for a specific video segment", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "The ID of the describe job" }, "segment_id": { "type": "string", "format": "uuid", "description": "The ID of the video segment" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ], "description": "Status of the describe job" }, "describe_config": { "$ref": "#/components/schemas/DescribeConfig" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the job was created" }, "completed_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the job completed" }, "start_time": { "type": "number", "description": "Start time of the segment in seconds" }, "end_time": { "type": "number", "description": "End time of the segment in seconds" }, "file_id": { "type": "string", "format": "uuid", "description": "The ID of the file" }, "segmentation_id": { "type": "string", "format": "uuid", "description": "The ID of the segmentation job" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/SegmentDescribeJsonData" }, { "$ref": "#/components/schemas/SegmentDescribeMarkdownData" } ], "description": "The describe output data. When response_format=json, contains visual_scene_description, speech, scene_text, and audio_description arrays. When response_format=markdown, contains a content string." }, "object": { "type": "string", "enum": ["segment_describe"], "description": "Object type" } }, "required": [ "job_id", "segment_id", "status", "describe_config", "created_at", "start_time", "end_time", "file_id", "object" ] }, "SegmentDescribeListResponse": { "type": "object", "description": "List of describe outputs for a video segment", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDescribe" }, "description": "Array of segment describe objects" }, "total": { "type": "integer", "description": "Total number of describe jobs for this segment" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "NewDescribe": { "allOf": [ { "type": "object", "required": ["url"], "properties": { "url": { "description": "Input media URL. Supports URIs of files uploaded to Cloudglue Files endpoint, public YouTube video URLs, public TikTok video URLs, public Loom share URLs, public HTTP URLs (including direct image URLs such as JPEG/PNG/WebP), and files which have been granted access to Cloudglue via data connectors.\n\nNote that YouTube videos are currently limited to speech level understanding only. Public TikTok video URLs will be scraped and stored automatically — subject to charges. For files via our Data connectors, see our documentation on data connectors for setup information.", "type": "string" }, "enable_summary": { "description": "Whether to generate video-level and segment-level (moment-level) summaries and titles", "type": "boolean" }, "enable_speech": { "description": "Whether to generate speech transcript", "type": "boolean" }, "enable_visual_scene_description": { "description": "Whether to generate visual scene description", "type": "boolean" }, "enable_scene_text": { "description": "Whether to generate scene text extraction", "type": "boolean" }, "enable_audio_description": { "description": "Whether to generate audio description", "type": "boolean" }, "thumbnails_config": { "$ref": "#/components/schemas/ThumbnailsConfig" }, "include_chapters": { "type": "boolean", "description": "Include narrative chapters in the response when segmentation strategy is 'narrative'. Only affects cached completed results; newly created pending jobs do not include chapters.", "default": false }, "include_shots": { "type": "boolean", "description": "Include shot boundaries in the response when segmentation strategy is 'shot-detector'. Only affects cached completed results; newly created pending jobs do not include shots.", "default": false }, "use_in_default_index": { "type": "boolean", "description": "When true, the video's search documents will be added to the account's default index, making them searchable via the Response API and Deep Search API with `source: 'default'`." }, "participants": { "type": "array", "maxItems": 50, "description": "Known participants on the recording. When provided, speaker naming is constrained to these people: transcript speaker labels will only use one of these names (or a generic \"Speaker N\"), never an invented name. Intended for uploaded files, which (unlike data-connector files such as Grain) carry no participant metadata; for connector files this is populated automatically and need not be supplied.", "items": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Participant display name, e.g. \"Alice Smith\"." }, "scope": { "type": "string", "description": "Optional free-form context for the participant, e.g. a role, affiliation, or \"internal\"/\"external\". Used only as naming context." } } } }, "prompt": { "type": "string", "maxLength": 2000, "description": "Optional free-form guidance for the description. Use it to name the terms, product names, acronyms, or people that matter for this media and how they are spelled, or to say what the description should pay attention to — e.g. \"Spell product names as Cloudglue and Aviary; call out any pricing discussed\". It steers emphasis and vocabulary across the visual, scene-text, speech, and summary passes; it cannot make the description report content that is not in the media, and it does not change the response shape. To *constrain* transcript speaker labels to a known cast, use `participants` instead — a prompt is context, not a constraint. Changing it produces a new describe job rather than reusing a cached one." }, "include_metadata": { "type": "boolean", "default": false, "description": "Include the file's user-defined metadata and source metadata on the returned `file` object." } } }, { "$ref": "#/components/schemas/FileSegmentationConfig" } ] }, "Describe": { "required": ["job_id", "status"], "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ] }, "url": { "type": "string", "description": "The URL of the processed video" }, "duration_seconds": { "type": "number", "description": "Duration of the video in seconds" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the file-level thumbnail for the video. Only present when include_thumbnails=true." }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the job was created" }, "describe_config": { "type": "object", "description": "Configuration for media description from videos", "properties": { "enable_summary": { "type": "boolean", "description": "Whether the user requested to generate video-level and segment-level (moment-level) summaries and titles" }, "enable_speech": { "type": "boolean", "description": "Whether the user requested to generate speech transcript" }, "enable_visual_scene_description": { "type": "boolean", "description": "Whether the user requested to generate visual scene description" }, "enable_scene_text": { "type": "boolean", "description": "Whether the user requested to generate scene text" }, "enable_audio_description": { "type": "boolean", "description": "Whether the user requested to generate audio description" }, "participants": { "type": "array", "maxItems": 50, "description": "Known participants on the recording. When provided, speaker naming is constrained to these people: transcript speaker labels will only use one of these names (or a generic \"Speaker N\"), never an invented name. Intended for uploaded files, which (unlike data-connector files such as Grain) carry no participant metadata; for connector files this is populated automatically and need not be supplied.", "items": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Participant display name, e.g. \"Alice Smith\"." }, "scope": { "type": "string", "description": "Optional free-form context for the participant, e.g. a role, affiliation, or \"internal\"/\"external\". Used only as naming context." } } } }, "prompt": { "type": "string", "description": "The free-form guidance this description was produced under, echoed back. Absent when none was supplied." } } }, "use_in_default_index": { "type": "boolean", "description": "Whether this describe job's search documents are included in the default index." }, "data": { "allOf": [ { "type": "object", "properties": { "content": { "type": "string", "description": "Content string returned based on formatting, e.g. set to markdown text when response_format=markdown is requested" }, "title": { "type": "string", "description": "Generated title of the video; for YouTube videos, this is the title of the video as it appears on YouTube" }, "summary": { "type": "string", "description": "Generated video level summary; for YouTube videos, this is the summary of the video as it appears on YouTube" }, "segment_summary": { "type": "array", "description": "Array of summary information for each segment of the video. Only available when enable_summary is set to true in the describe configuration.", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Generated segment-level title" }, "summary": { "type": "string", "description": "Generated segment-level summary" }, "start_time": { "type": "number", "description": "Start time of segment in seconds" }, "end_time": { "type": "number", "description": "End time of segment in seconds" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the segment thumbnail, when available." } } } } } }, { "$ref": "#/components/schemas/DescribeOutput" } ] }, "error": { "type": "string", "description": "Error message if status is 'failed'" }, "segmentation_id": { "type": "string", "format": "uuid", "description": "The ID of the segmentation job if the describe was run with a segmentation" }, "chapters": { "type": "array", "description": "Array of narrative chapters (only present when include_chapters=true and segmentation strategy is 'narrative')", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "start_time": { "type": "number", "minimum": 0 }, "end_time": { "type": "number", "minimum": 0 }, "description": { "type": "string" } }, "required": ["index", "start_time", "end_time", "description"] } }, "shots": { "type": "array", "description": "Array of shot boundaries (only present when include_shots=true and segmentation strategy is 'shot-detector')", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "start_time": { "type": "number", "minimum": 0 }, "end_time": { "type": "number", "minimum": 0 } }, "required": ["index", "start_time", "end_time"] } }, "total_chapters": { "type": "integer", "minimum": 0, "description": "Total number of chapters (only present when include_chapters=true and segmentation strategy is 'narrative')" }, "total_shots": { "type": "integer", "minimum": 0, "description": "Total number of shots (only present when include_shots=true and segmentation strategy is 'shot-detector')" }, "file": { "allOf": [ { "$ref": "#/components/schemas/File" } ], "description": "The file this document describes. `metadata` and `source_metadata` are only included when `include_metadata` is true." } } }, "DescribeList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Describe" }, "description": "Array of describe job objects" }, "total": { "type": "integer", "description": "Total number of describe jobs matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "MediaDescription": { "allOf": [ { "type": "object", "required": ["collection_id", "file_id"], "properties": { "collection_id": { "type": "string", "description": "Unique identifier for the collection" }, "file_id": { "type": "string", "description": "Unique identifier for the file" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the file-level thumbnail for the video. Only present when include_thumbnails=true." }, "content": { "type": "string", "description": "Content string returned based on formatting, e.g. set to markdown text when response_format=markdown is requested" }, "title": { "type": "string", "description": "Generated title of the video" }, "summary": { "type": "string", "description": "Generated video level summary" }, "duration_seconds": { "type": "number", "description": "Duration of the video in seconds" }, "segment_summary": { "type": "array", "description": "Array of summary information for each segment of the video", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Generated segment-level title" }, "summary": { "type": "string", "description": "Generated segment-level summary" }, "start_time": { "type": "number", "description": "Start time of segment in seconds" }, "end_time": { "type": "number", "description": "End time of segment in seconds" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the segment thumbnail, when available." } } } }, "chapters": { "type": "array", "description": "Array of narrative chapters (only present when include_chapters=true and segmentation strategy is 'narrative')", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "start_time": { "type": "number", "minimum": 0 }, "end_time": { "type": "number", "minimum": 0 }, "description": { "type": "string" } }, "required": ["index", "start_time", "end_time", "description"] } }, "shots": { "type": "array", "description": "Array of shot boundaries (only present when include_shots=true and segmentation strategy is 'shot-detector')", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "start_time": { "type": "number", "minimum": 0 }, "end_time": { "type": "number", "minimum": 0 } }, "required": ["index", "start_time", "end_time"] } }, "total_chapters": { "type": "integer", "minimum": 0, "description": "Total number of chapters (only present when include_chapters=true and segmentation strategy is 'narrative')" }, "total_shots": { "type": "integer", "minimum": 0, "description": "Total number of shots (only present when include_shots=true and segmentation strategy is 'shot-detector')" }, "file": { "allOf": [ { "$ref": "#/components/schemas/File" } ], "description": "The file this document describes. `metadata` and `source_metadata` are only included when `include_metadata` is true." } } }, { "$ref": "#/components/schemas/DescribeOutput" } ] }, "RichTranscript": { "allOf": [ { "type": "object", "required": ["collection_id", "file_id"], "properties": { "collection_id": { "type": "string", "description": "The ID of the collection" }, "file_id": { "type": "string", "description": "The ID of the file" }, "content": { "type": "string", "description": "Content string returned based on formatting, e.g. set to markdown text when response_format=markdown is requested" }, "title": { "type": "string", "description": "Generated title of the video" }, "summary": { "type": "string", "description": "Generated video level summary" }, "duration_seconds": { "type": "number", "description": "Duration of the video in seconds" }, "segment_summary": { "type": "array", "description": "Array of summary information for each segment of the video. Only available when enable_summary is set to true in the transcribe configuration.", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Generated segment-level title" }, "summary": { "type": "string", "description": "Generated segment-level summary" }, "start_time": { "type": "number", "description": "Start time of segment in seconds" }, "end_time": { "type": "number", "description": "End time of segment in seconds" } } } }, "file": { "allOf": [ { "$ref": "#/components/schemas/File" } ], "description": "The file this document describes. `metadata` and `source_metadata` are only included when `include_metadata` is true." } } }, { "$ref": "#/components/schemas/DescribeOutput" } ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook" }, "object": { "type": "string", "enum": ["webhook"], "description": "Object type, always 'webhook'" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the webhook was created" }, "webhook_secret": { "type": "string", "description": "Secret used to verify the webhook request" }, "endpoint": { "type": "string", "description": "URL of the webhook endpoint" }, "active": { "type": "boolean", "description": "Whether the webhook is active" }, "description": { "type": "string", "description": "Description of the webhook" }, "subscribed_events": { "type": "array", "description": "Events that the webhook is subscribed to", "items": { "$ref": "#/components/schemas/WebhookEvents" } } }, "required": [ "id", "object", "created_at", "subscribed_events", "active", "endpoint", "webhook_secret" ] }, "DataConnector": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the data connector" }, "object": { "type": "string", "enum": ["data_connector"], "description": "Object type, always 'data_connector'" }, "type": { "type": "string", "enum": [ "s3", "dropbox", "google-drive", "zoom", "gong", "recall", "gcs", "grain", "iconik" ], "description": "The type of data connector" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the data connector was created" }, "updated_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the data connector config was last modified" }, "metadata": { "type": "object", "description": "Safe metadata for the connector (varies by type). Never includes tokens or secrets." } }, "required": [ "id", "object", "type", "created_at", "updated_at", "metadata" ] }, "DataConnectorList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataConnector" }, "description": "Array of data connector objects" }, "total": { "type": "integer", "description": "Total number of data connectors" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "DataConnectorFile": { "type": "object", "properties": { "object": { "type": "string", "enum": ["data_connector_file"], "description": "Object type, always 'data_connector_file'" }, "type": { "type": "string", "enum": ["file", "folder"], "description": "Whether this entry is a file or a folder" }, "uri": { "type": "string", "nullable": true, "description": "URI for importing the file into Cloudglue. Null for folders." }, "name": { "type": "string", "description": "Display name of the file or folder" }, "mime_type": { "type": "string", "nullable": true, "description": "MIME type of the file, if available" }, "size_bytes": { "type": "integer", "nullable": true, "description": "File size in bytes, if available" }, "created_at": { "type": "integer", "nullable": true, "description": "Creation timestamp in milliseconds since epoch, if available" }, "thumbnail_url": { "type": "string", "nullable": true, "description": "Ephemeral preview image for the file — a signed provider URL that expires within hours. Display-only: never store it. Currently populated for iconik (the asset's poster keyframe, honoring a custom keyframe when one is set); null or absent for other connectors." }, "metadata": { "type": "object", "properties": { "folder_id": { "type": "string", "description": "Google Drive folder ID. Pass back as the `folder_id` query parameter to drill into this folder." }, "path": { "type": "string", "description": "Dropbox folder path. Pass back as the `path` query parameter to drill into this folder." }, "prefix": { "type": "string", "description": "S3/GCS key prefix. Pass back as the `prefix` query parameter to drill into this virtual folder." } }, "additionalProperties": true, "description": "Provider-specific metadata. Folder entries expose the navigation key to pass back on the next request. File entries from Grain, Zoom, Recall, Google Drive, Dropbox, and Gong carry the provider's SourceMetadata shape (see the SourceMetadata schema) — the same provenance that lands on the file's `source_metadata` after syncing, so you can inspect participants, hosts, durations, AI summaries, etc. while browsing. S3/GCS file entries carry an empty object. Some fields are only captured at sync time (Dropbox media_info, Gong AI content)." } }, "required": [ "object", "type", "uri", "name", "mime_type", "size_bytes", "created_at", "metadata" ] }, "DataConnectorFileList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataConnectorFile" }, "description": "Array of file and folder objects" }, "has_more": { "type": "boolean", "description": "Whether more results are available" }, "next_page_token": { "type": "string", "nullable": true, "description": "Opaque cursor to pass as page_token for the next page. Null when there are no more results." } }, "required": ["object", "data", "has_more", "next_page_token"] }, "WebhookList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "description": "Array of webhook objects" }, "total": { "type": "integer", "description": "Total number of webhooks matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "WebhookEvents": { "type": "string", "enum": [ "describe.job.processing", "describe.job.completed", "describe.job.failed", "extract.job.processing", "extract.job.completed", "extract.job.failed", "file.job.processing", "file.job.completed", "file.job.failed", "file.job.deleted", "collection.file.job.processing", "collection.file.job.completed", "collection.file.job.failed", "collection.file.job.deleted", "segment.job.processing", "segment.job.completed", "segment.job.failed", "find_moments.job.processing", "find_moments.job.completed", "find_moments.job.failed" ], "description": "Webhook events that can be subscribed to" }, "WebhookDeleteResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook" }, "object": { "type": "string", "enum": ["webhook"], "description": "Object type, always 'webhook'" } }, "required": ["id", "object"] }, "WebhookCreateRequest": { "type": "object", "properties": { "description": { "type": "string", "description": "Description of the webhook" }, "endpoint": { "type": "string", "description": "URL of the webhook endpoint" }, "subscribed_events": { "type": "array", "description": "Events that the webhook is subscribed to", "items": { "$ref": "#/components/schemas/WebhookEvents" } } } }, "WebhookUpdateRequest": { "type": "object", "properties": { "description": { "type": "string", "description": "Description of the webhook" }, "endpoint": { "type": "string", "description": "URL of the webhook endpoint" }, "subscribed_events": { "type": "array", "description": "Events that the webhook is subscribed to", "items": { "$ref": "#/components/schemas/WebhookEvents" } }, "active": { "type": "boolean", "description": "Whether the webhook is active" } } }, "CollectionEntitiesList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "ID of the file" }, "data": { "type": "object", "properties": { "entities": { "type": "object", "description": "Entities extracted from the file at the video level" }, "segment_entities": { "type": "array", "description": "Array of video entities extracted from individual time segments", "items": { "type": "object", "properties": { "start_time": { "type": "number", "description": "Start time of the segment in seconds" }, "end_time": { "type": "number", "description": "End time of the segment in seconds" }, "entities": { "type": "object", "description": "Entities extracted from the segment" } } } } }, "required": ["entities"] } }, "required": ["file_id", "data"] }, "description": "Array of file entities" }, "total": { "type": "integer", "description": "Total number of files with entities matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "CollectionRichTranscriptsList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "ID of the file" }, "duration_seconds": { "type": "number", "description": "Duration of the video in seconds" }, "data": { "allOf": [ { "type": "object", "properties": { "content": { "type": "string", "description": "Content string returned based on formatting, e.g. set to markdown text when response_format=markdown is requested" }, "title": { "type": "string", "description": "Generated title of the video" }, "summary": { "type": "string", "description": "Generated video level summary" }, "segment_summary": { "type": "array", "description": "Array of summary information for each segment of the video. Only available when enable_summary is set to true in the transcribe configuration.", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Generated segment-level title" }, "summary": { "type": "string", "description": "Generated segment-level summary" }, "start_time": { "type": "number", "description": "Start time of segment in seconds" }, "end_time": { "type": "number", "description": "End time of segment in seconds" } } } } } }, { "$ref": "#/components/schemas/DescribeOutput" } ] }, "file": { "allOf": [ { "$ref": "#/components/schemas/File" } ], "description": "The file this document describes. `metadata` and `source_metadata` are only included when `include_metadata` is true." } }, "required": ["file_id", "data"] }, "description": "Array of rich transcription data" }, "total": { "type": "integer", "description": "Total number of files with rich transcription data matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "CollectionMediaDescriptionsList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "Unique identifier for the file" }, "added_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the file was added to the collection" }, "object": { "type": "string", "enum": ["collection_file"], "description": "Object type, always 'collection_file'" }, "duration_seconds": { "type": "number", "description": "Duration of the video in seconds" }, "data": { "allOf": [ { "type": "object", "properties": { "content": { "type": "string", "description": "Content string returned based on formatting, e.g. set to markdown text when response_format=markdown is requested" }, "title": { "type": "string", "description": "Generated title of the video" }, "summary": { "type": "string", "description": "Generated video level summary" }, "segment_summary": { "type": "array", "description": "Array of summary information for each segment of the video", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Generated segment-level title" }, "summary": { "type": "string", "description": "Generated segment-level summary" }, "start_time": { "type": "number", "description": "Start time of segment in seconds" }, "end_time": { "type": "number", "description": "End time of segment in seconds" } } } } } }, { "$ref": "#/components/schemas/DescribeOutput" } ] }, "file": { "allOf": [ { "$ref": "#/components/schemas/File" } ], "description": "The file this document describes. `metadata` and `source_metadata` are only included when `include_metadata` is true." } }, "required": ["file_id", "data", "added_at", "object"] }, "description": "Array of media description data" }, "total": { "type": "integer", "description": "Total number of files with media description data matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "SegmentationUniformConfig": { "type": "object", "required": ["window_seconds"], "properties": { "window_seconds": { "type": "number", "minimum": 1, "maximum": 120, "description": "The duration of each segment in seconds. Must be between 1 and 120 seconds." }, "hop_seconds": { "type": "number", "minimum": 1, "maximum": 120, "description": "The offset between the start of new windows. This means there can be overlap between segments. If not provided, defaults to window_seconds. Must be between 1 and 120 seconds." } } }, "SegmentationShotDetectorConfig": { "type": "object", "required": ["detector"], "properties": { "threshold": { "type": "number", "nullable": true, "description": "Detection sensitivity threshold - lower values create more segments:\n\n• **content**: Sensitivity to visual differences (default: 27.0). Lower values detect smaller changes in color/lighting.\n• **adaptive**: Does not support threshold parameter - uses internal adaptive algorithm." }, "min_seconds": { "type": "number", "minimum": 0.6, "maximum": 600, "nullable": true, "description": "The minimum length of a shot in seconds. Defaults to 0.6." }, "max_seconds": { "type": "number", "minimum": 1, "maximum": 600, "nullable": true, "description": "The maximum length of a shot in seconds. Defaults to 300." }, "detector": { "type": "string", "enum": ["adaptive", "content"], "description": "The detector strategy to use:\n\n• **adaptive**: Designed for dynamic footage with camera movement, panning, or action. Examples: sports broadcasts, drone footage, handheld documentaries, action movies, live events.\n• **content**: Optimized for controlled footage with clear visual transitions. Examples: studio interviews, corporate videos, educational content, product demos, scripted content." }, "fill_gaps": { "type": "boolean", "description": "When true, gaps between detected shots are filled: gaps greater than or equal to min_seconds become their own segments (split by max_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true." } } }, "KeyframeConfig": { "type": "object", "required": ["frames_per_segment"], "description": "Configuration for keyframe extraction. When provided, will be used to extract keyframes for the segmentation. This is not supported for YouTube videos.", "properties": { "frames_per_segment": { "type": "number", "minimum": 0, "maximum": 8, "description": "The number of key frames to extract per segment" }, "max_width": { "type": "number", "minimum": 144, "maximum": 4320, "description": "The maximum width of the key frames in pixels" } } }, "SegmentationManualConfig": { "type": "object", "required": ["segments"], "properties": { "segments": { "type": "array", "items": { "type": "object", "properties": { "start_time": { "type": "number", "description": "The start time of the segment in seconds" }, "end_time": { "type": "number", "description": "The end time of the segment in seconds" } } }, "description": "Array of segments" } } }, "SegmentationConfig": { "type": "object", "description": "Configuration for video segmentation. **Choose a strategy and provide ONLY the corresponding config:**\n\n• **uniform**: Provide `uniform_config`, do NOT provide other configs\n• **shot-detector**: Provide `shot_detector_config`, do NOT provide other configs\n• **manual**: Provide `manual_config`, do NOT provide other configs\n• **narrative**: Provide `narrative_config`, do NOT provide other configs\n\nOptionally specify `start_time_seconds` and `end_time_seconds` to limit segmentation to a portion of the video.", "required": ["strategy"], "properties": { "strategy": { "type": "string", "enum": ["uniform", "shot-detector", "manual", "narrative"], "description": "Segmentation strategy - determines which config you must provide" }, "uniform_config": { "$ref": "#/components/schemas/SegmentationUniformConfig", "description": "🎯 **REQUIRED when strategy = 'uniform'** - Configuration for uniform segmentation." }, "shot_detector_config": { "$ref": "#/components/schemas/SegmentationShotDetectorConfig", "description": "🎯 **REQUIRED when strategy = 'shot-detector'** - Configuration for shot detection segmentation." }, "manual_config": { "$ref": "#/components/schemas/SegmentationManualConfig", "description": "🎯 **REQUIRED when strategy = 'manual'** - Configuration for manual segmentation." }, "narrative_config": { "$ref": "#/components/schemas/NarrativeConfig", "description": "🎯 **REQUIRED when strategy = 'narrative'** - Configuration for narrative-based chapter segmentation using AI analysis." }, "keyframe_config": { "$ref": "#/components/schemas/KeyframeConfig", "description": "When provided, will be used to extract keyframes for the segmentation." }, "start_time_seconds": { "type": "number", "minimum": 0, "description": "Optional: The start time of the video in seconds to start segmenting from" }, "end_time_seconds": { "type": "number", "minimum": 0, "description": "Optional: The end time of the video in seconds to stop segmenting at" } } }, "DefaultSegmentationConfig": { "type": "object", "description": "Configuration for video segmentation. **Choose a strategy and provide ONLY the corresponding config:**\n\n• **uniform**: Provide `uniform_config`, do NOT provide other configs\n• **shot-detector**: Provide `shot_detector_config`, do NOT provide other configs\n• **narrative**: Provide `narrative_config`, do NOT provide other configs\n\nOptionally specify `start_time_seconds` and `end_time_seconds` to limit segmentation to a portion of the video.", "required": ["strategy"], "properties": { "strategy": { "type": "string", "enum": ["uniform", "shot-detector", "narrative"], "description": "Segmentation strategy - determines which config you must provide. Manual strategies are not supported for default segmentation configs." }, "uniform_config": { "$ref": "#/components/schemas/SegmentationUniformConfig", "description": "🎯 **REQUIRED when strategy = 'uniform'** - Configuration for uniform segmentation." }, "shot_detector_config": { "$ref": "#/components/schemas/SegmentationShotDetectorConfig", "description": "🎯 **REQUIRED when strategy = 'shot-detector'** - Configuration for shot detection segmentation." }, "narrative_config": { "$ref": "#/components/schemas/NarrativeConfig", "description": "🎯 **REQUIRED when strategy = 'narrative'** - Configuration for narrative-based chapter segmentation using AI analysis." }, "keyframe_config": { "$ref": "#/components/schemas/KeyframeConfig", "description": "When provided, will be used to extract keyframes for the segmentation." }, "start_time_seconds": { "type": "number", "minimum": 0, "description": "Optional: The start time of the video in seconds to start segmenting from" }, "end_time_seconds": { "type": "number", "minimum": 0, "description": "Optional: The end time of the video in seconds to stop segmenting at" } } }, "ThumbnailsConfig": { "type": "object", "required": ["enable_segment_thumbnails"], "properties": { "enable_segment_thumbnails": { "type": "boolean", "description": "Whether to enable segment thumbnails. If not provided will use default to false. Cannot be used together with segmentation_id." } } }, "FileSegmentationConfig": { "type": "object", "properties": { "segmentation_id": { "type": "string", "format": "uuid", "description": "Segmentation job id to use. If not provided will use default to uniform 20s segmentation. Cannot be provided together with segmentation_config." }, "segmentation_config": { "$ref": "#/components/schemas/SegmentationConfig", "description": "Configuration for video segmentation. Cannot be provided together with segmentation_id." } } }, "Segmentation": { "type": "object", "required": [ "segmentation_id", "status", "created_at", "file_id", "segmentation_config", "thumbnails_config" ], "properties": { "segmentation_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the segmentation job" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ], "description": "Status of the segmentation job. If a job has the status 'not_applicable' it means that we were unable to find any appropriate scenes for this video. This can be possible if you use the shot-detector strategy." }, "created_at": { "type": "number", "minimum": 0, "description": "Unix timestamp in milliseconds when the segmentation was created" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file this segmentation belongs to" }, "segmentation_config": { "$ref": "#/components/schemas/SegmentationConfig" }, "thumbnails_config": { "$ref": "#/components/schemas/ThumbnailsConfig" }, "total_segments": { "type": "number", "minimum": 0, "description": "Total number of segments in this segmentation (only present when status is completed)" }, "total_shots": { "type": "number", "minimum": 0, "description": "Total number of shots in this segmentation (only present when status is completed and segmentation_config.strategy is 'shot-detector')" }, "total_chapters": { "type": "number", "minimum": 0, "description": "Total number of chapters in this segmentation (only present when status is completed and segmentation_config.strategy is 'narrative')" }, "data": { "type": "object", "description": "Segment data with pagination (only present when status is completed and segments exist)", "required": ["object", "total", "limit", "offset"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "segments": { "type": "array", "items": { "type": "object", "required": ["id", "start_time", "end_time"], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the segment" }, "start_time": { "type": "number", "description": "Start time of the segment in seconds" }, "end_time": { "type": "number", "description": "End time of the segment in seconds" }, "thumbnail_url": { "type": "string", "description": "URL of the thumbnail for the segment if it exists" } } } }, "shots": { "type": "array", "description": "Array of shots in the original video (only present when status is completed and segmentation_config.strategy is 'shot-detector')", "items": { "$ref": "#/components/schemas/Shot" } }, "chapters": { "type": "array", "description": "Array of narrative chapters in the video (only present when status is completed and segmentation_config.strategy is 'narrative')", "items": { "$ref": "#/components/schemas/Chapter" } }, "total": { "type": "integer", "description": "Total number of segments" }, "limit": { "type": "integer", "description": "Number of segments returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the segments list" } } } } }, "SegmentationListItem": { "type": "object", "required": [ "segmentation_id", "status", "created_at", "file_id", "segmentation_config", "thumbnails_config" ], "properties": { "segmentation_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the segmentation job" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "not_applicable" ], "description": "Status of the segmentation job. If a job has the status 'not_applicable' it means that we were unable to find any appropriate scenes for this video. This can be possible if you use the shot-detector strategy." }, "created_at": { "type": "number", "minimum": 0, "description": "Unix timestamp in milliseconds when the segmentation was created" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file this segmentation belongs to" }, "segmentation_config": { "$ref": "#/components/schemas/SegmentationConfig" }, "thumbnails_config": { "$ref": "#/components/schemas/ThumbnailsConfig" }, "total_segments": { "type": "number", "minimum": 0, "description": "Total number of segments in this segmentation (only present when status is completed)" } }, "description": "Segmentation object as returned in list responses (does not include segments array or data property)" }, "SegmentationList": { "type": "object", "required": ["object", "data", "total", "limit", "offset"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentationListItem" }, "description": "Array of segmentation objects" }, "total": { "type": "integer", "description": "Total number of segmentations matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } } }, "FrameExtractionConfig": { "type": "object", "description": "Configuration for frame extraction. Currently only supports uniform strategy.", "required": ["strategy"], "properties": { "strategy": { "type": "string", "enum": ["uniform"], "description": "Frame extraction strategy - currently only 'uniform' is supported" }, "uniform_config": { "$ref": "#/components/schemas/FrameExtractionUniformConfig", "description": "Configuration for uniform frame extraction" }, "thumbnails_config": { "$ref": "#/components/schemas/FrameExtractionThumbnailsConfig", "description": "Configuration for frame thumbnails. Optional." }, "start_time_seconds": { "type": "number", "minimum": 0, "description": "Optional: The start time of the video in seconds to start extracting frames from" }, "end_time_seconds": { "type": "number", "minimum": 0, "description": "Optional: The end time of the video in seconds to stop extracting frames at" } } }, "FrameExtractionUniformConfig": { "type": "object", "description": "Configuration for uniform frame extraction", "properties": { "frames_per_second": { "type": "number", "minimum": 0.1, "maximum": 30, "description": "Number of frames to extract per second of video" }, "max_width": { "type": "number", "minimum": 64, "maximum": 4096, "description": "Maximum width of extracted frames in pixels. Aspect ratio is preserved." } } }, "FrameExtractionThumbnailsConfig": { "type": "object", "description": "Configuration for frame thumbnails", "properties": { "enable_frame_thumbnails": { "type": "boolean", "description": "Whether to generate CDN-hosted thumbnails for extracted frames" } } }, "FrameExtraction": { "type": "object", "required": [ "frame_extraction_id", "status", "created_at", "file_id", "frame_extraction_config" ], "properties": { "frame_extraction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the frame extraction job" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Status of the frame extraction job" }, "created_at": { "type": "number", "minimum": 0, "description": "Unix timestamp in milliseconds when the frame extraction was created" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file this frame extraction belongs to" }, "frame_extraction_config": { "$ref": "#/components/schemas/FrameExtractionConfig" }, "frame_count": { "type": "number", "minimum": 0, "description": "Total number of frames extracted (only present when status is completed)" }, "data": { "type": "object", "description": "Frame data with pagination (only present when status is completed and frames exist)", "required": ["object", "total", "limit", "offset"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "frames": { "type": "array", "items": { "type": "object", "required": ["id", "timestamp"], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the frame" }, "timestamp": { "type": "number", "description": "Timestamp of the frame in seconds" }, "thumbnail_url": { "type": "string", "description": "URL of the CDN-hosted thumbnail for the frame if thumbnails are enabled" } } }, "description": "Array of extracted frames" }, "total": { "type": "integer", "description": "Total number of frames in this extraction" }, "limit": { "type": "integer", "description": "Number of frames returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the frames list" } } } } }, "FrameExtractionList": { "type": "object", "required": ["object", "data", "total", "limit", "offset"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "type": "object", "required": [ "frame_extraction_id", "status", "created_at", "file_id", "frame_extraction_config" ], "properties": { "frame_extraction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the frame extraction job" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Status of the frame extraction job" }, "created_at": { "type": "number", "minimum": 0, "description": "Unix timestamp in milliseconds when the frame extraction was created" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file this frame extraction belongs to" }, "frame_extraction_config": { "$ref": "#/components/schemas/FrameExtractionConfig" }, "frame_count": { "type": "number", "minimum": 0, "description": "Total number of frames extracted (only present when status is completed)" } } }, "description": "Array of frame extraction objects" }, "total": { "type": "integer", "description": "Total number of frame extractions matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } } }, "SearchRequest": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["file", "segment", "face", "moment"], "description": "Search scope - 'file' searches at file level (requires collections with enable_summary=true), 'segment' searches at segment level, 'face' searches for faces in videos using image matching, 'moment' searches moments produced by find-moments criteria in moments collections" }, "collections": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "List of collection IDs to search within. \n\nFor text search (scope='file' or 'segment'): All collections must be of collection_type 'media-descriptions', 'rich-transcripts', 'metadata', or 'entities'. For file-level search, 'media-descriptions' and 'rich-transcripts' collections must have 'enable_summary: true' in their config. 'metadata' collections only support scope='file'. 'entities' collections are searchable at the scope matching their extraction level: file-level extraction (enable_video_level_entities or enable_metadata_mode) supports scope='file' only, segment-level extraction (enable_segment_level_entities) supports scope='segment' only.\n\nFor face search (scope='face'): All collections must be of collection_type 'face-analysis'.\n\nFor moment search (scope='moment'): All collections must be of collection_type 'moments'." }, "query": { "type": "string", "minLength": 1, "description": "Text search query to find relevant content (required for scope='file', 'segment', or 'moment')" }, "criterion_name": { "type": "string", "description": "Narrow moment search to one criterion by name (scope='moment' only)" }, "source_image": { "type": "object", "description": "Source image for face search (required for scope='face')", "properties": { "url": { "type": "string", "description": "URL of the source image to search for" }, "base64": { "type": "string", "description": "Base64-encoded image bytes" } } }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum number of search results to return (applies to total items across groups when grouping)" }, "filter": { "$ref": "#/components/schemas/SearchFilter" }, "threshold": { "type": "number", "description": "Minimum score threshold to filter results. Can be any real number." }, "group_by_key": { "type": "string", "enum": ["file"], "description": "Group results by file. Cannot be used with scope=\"file\" or scope=\"moment\" — grouped moment search is not supported and returns a 400. When specified, results are grouped by file_id." }, "sort_by": { "type": "string", "enum": ["score", "item_count"], "description": "Sort order for results. Default: \"score\". When group_by_key is specified, can also use \"item_count\" to sort by number of items per group." }, "search_modalities": { "$ref": "#/components/schemas/SearchModalities" }, "label_filters": { "type": "array", "items": { "type": "string" }, "description": "Filter eligible search items by presence of one or more labels in the provided list (otherwise all tags will be considered in search response). Only supported for `tag_semantic` and `tag_lexical` search modalities " } } }, "SearchFilter": { "type": "object", "properties": { "metadata": { "type": "array", "description": "Filter by file metadata using JSON path expressions", "items": { "allOf": [ { "$ref": "#/components/schemas/SearchFilterCriteria" }, { "type": "object", "properties": { "scope": { "type": "string", "enum": ["file", "segment"], "description": "Specifies scope of eligible search items (file/segment) to check metadata filtering conditions" } } } ] } }, "video_info": { "type": "array", "description": "Filter by video information. Use scope 'file' to filter by source video properties, or 'segment' to filter by individual segment properties (e.g. segment duration).", "items": { "allOf": [ { "$ref": "#/components/schemas/SearchFilterCriteria" }, { "type": "object", "properties": { "path": { "type": "string", "enum": ["duration_seconds", "has_audio"] }, "scope": { "type": "string", "enum": ["file", "segment"], "description": "Scope of the filter. 'file' filters by source video properties, 'segment' filters by segment properties. Only duration_seconds is supported with segment scope." } } } ] } }, "file": { "type": "array", "description": "Filter by file properties", "items": { "allOf": [ { "$ref": "#/components/schemas/SearchFilterCriteria" }, { "type": "object", "properties": { "path": { "type": "string", "enum": ["bytes", "filename", "uri", "created_at", "id"] } } } ] } }, "source_metadata": { "type": "array", "description": "Filter by connector-provided source metadata using JSON path expressions (file scope only). Available fields depend on the file's source. Examples: source_metadata.topic (zoom), source_metadata.host_email (zoom), source_metadata.title (gong/grain/iconik), source_metadata.participants.name (grain), source_metadata.parties.email (gong), source_metadata.tags (grain, use ContainsAny), source_metadata.meeting_platform (recall), source_metadata.name (google-drive/dropbox), source_metadata.media_type (iconik), source_metadata.iconik_metadata. (iconik custom metadata-view fields, e.g. source_metadata.iconik_metadata.Keywords with ContainsAny). Paths through arrays of objects match when ANY element matches. ISO datetime fields (zoom start_time, gong started, grain start_datetime, recall started_at, iconik date_created) compare as strings with LessThan/GreaterThan and represent the actual meeting date (or, for iconik, the asset creation date).", "items": { "$ref": "#/components/schemas/SearchFilterCriteria" } } } }, "SearchFilterCriteria": { "type": "object", "required": ["path", "operator"], "properties": { "path": { "type": "string", "description": "JSON path for the field to filter on" }, "operator": { "type": "string", "enum": [ "NotEqual", "Equal", "LessThan", "GreaterThan", "ContainsAny", "ContainsAll", "In", "Like" ], "description": "Comparison operator to apply" }, "valueText": { "type": "string", "description": "Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like)" }, "valueTextArray": { "type": "array", "items": { "type": "string" }, "description": "Array of values for array comparisons (used with ContainsAny, ContainsAll, In)" } } }, "SearchResponseList": { "type": "object", "required": ["object", "data", "total", "limit", "offset"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "scope", "results", "total", "limit" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the search response" }, "object": { "type": "string", "enum": ["search"], "description": "Object type, always 'search'" }, "query": { "type": "string", "description": "The search query that was executed (for text search) or the source image URL/base64 indicator (for face search)" }, "scope": { "type": "string", "enum": ["file", "segment", "face", "moment"], "description": "The search scope that was used" }, "group_by_key": { "type": "string", "enum": ["file"], "description": "The key used for grouping results. Only present when group_by_key was specified in the request and results are grouped." }, "group_count": { "type": "integer", "description": "Number of groups in the results. Only present when group_by_key is specified." }, "search_modalities": { "$ref": "#/components/schemas/SearchModalities" }, "total": { "type": "integer", "description": "Total number of results returned. When group_by_key is specified, this represents the total number of items across all groups (not the number of groups)." }, "limit": { "type": "integer", "description": "The limit that was applied to the search" } } } }, "total": { "type": "integer", "description": "Total number of search responses matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } } }, "SearchResponse": { "type": "object", "required": ["id", "object", "scope", "results", "total", "limit"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the search response" }, "object": { "type": "string", "enum": ["search"], "description": "Object type, always 'search'" }, "query": { "type": "string", "description": "The search query that was executed (for text search) or the source image URL/base64 indicator (for face search)" }, "scope": { "type": "string", "enum": ["file", "segment", "face", "moment"], "description": "The search scope that was used" }, "group_by_key": { "type": "string", "enum": ["file"], "description": "The key used for grouping results. Only present when group_by_key was specified in the request and results are grouped." }, "group_count": { "type": "integer", "description": "Number of groups in the results. Only present when group_by_key is specified." }, "search_modalities": { "$ref": "#/components/schemas/SearchModalities" }, "results": { "type": "array", "description": "Array of search results ranked by relevance score", "items": { "oneOf": [ { "$ref": "#/components/schemas/FileSearchResult" }, { "$ref": "#/components/schemas/SegmentSearchResult" }, { "$ref": "#/components/schemas/FaceSearchResult" }, { "$ref": "#/components/schemas/MomentSearchResult" }, { "$ref": "#/components/schemas/SegmentGroupResult" }, { "$ref": "#/components/schemas/FaceGroupResult" } ] } }, "total": { "type": "integer", "description": "Total number of results returned. When group_by_key is specified, this represents the total number of items across all groups (not the number of groups)." }, "limit": { "type": "integer", "description": "The limit that was applied to the search" } } }, "FileSearchResult": { "type": "object", "required": ["type", "file_id", "collection_id", "score", "id"], "properties": { "type": { "type": "string", "enum": ["file"], "description": "Result type, always 'file'" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file" }, "collection_id": { "type": "string", "format": "uuid", "description": "ID of the collection containing this file" }, "id": { "type": "string", "format": "uuid", "description": "ID of the search document" }, "score": { "type": "number", "description": "Relevance score (higher is more relevant)" }, "filename": { "type": "string", "nullable": true, "description": "Original filename of the video" }, "summary": { "type": "string", "nullable": true, "description": "Generated summary of the video" }, "generated_title": { "type": "string", "nullable": true, "description": "Generated title of the video" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the thumbnail for the file if available." }, "tag": { "$ref": "#/components/schemas/SearchTagResponse" } } }, "SegmentSearchResult": { "type": "object", "required": [ "type", "file_id", "collection_id", "segment_id", "score", "id", "start_time", "end_time" ], "properties": { "type": { "type": "string", "enum": ["segment"], "description": "Result type, always 'segment'" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file" }, "collection_id": { "type": "string", "format": "uuid", "description": "ID of the collection containing this file" }, "segment_id": { "type": "string", "format": "uuid", "description": "ID of the segment" }, "id": { "type": "string", "format": "uuid", "description": "ID of the search document" }, "score": { "type": "number", "description": "Relevance score (higher is more relevant)" }, "start_time": { "type": "number", "description": "Start time of the segment in seconds" }, "end_time": { "type": "number", "description": "End time of the segment in seconds" }, "title": { "type": "string", "nullable": true, "description": "Title associated with the segment" }, "filename": { "type": "string", "nullable": true, "description": "Original filename of the video" }, "visual_description": { "type": "array", "description": "Visual descriptions for the segment", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Description of visual content in the segment" }, "start_time": { "type": "number", "description": "Start time of the visual content in seconds" }, "end_time": { "type": "number", "description": "End time of the visual content in seconds" } } } }, "scene_text": { "type": "array", "description": "Text detected on screen in the segment", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Text detected on screen" }, "start_time": { "type": "number", "description": "Start time of the text in seconds" }, "end_time": { "type": "number", "description": "End time of the text in seconds" } } } }, "speech": { "type": "array", "description": "Speech transcription for the segment", "items": { "type": "object", "properties": { "speaker": { "type": "string", "description": "Identified speaker" }, "text": { "type": "string", "description": "Transcribed speech text" }, "start_time": { "type": "number", "description": "Start time of speech in seconds" }, "end_time": { "type": "number", "description": "End time of speech in seconds" } } } }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the thumbnail for the segment if available" }, "tag": { "$ref": "#/components/schemas/SearchTagResponse" }, "metadata": { "type": "object", "description": "User-provided metadata about the segment, if provided." }, "keyframes": { "type": "array", "description": "Keyframes for the segment", "items": { "type": "object", "properties": { "time_in_seconds": { "type": "number", "description": "Time of the keyframe in seconds" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "URL of the thumbnail for the keyframe" } } } } } }, "FaceSearchResult": { "type": "object", "required": [ "type", "file_id", "collection_id", "face_id", "frame_id", "score", "timestamp" ], "properties": { "type": { "type": "string", "enum": ["face"], "description": "Result type, always 'face'" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file containing the matched face" }, "collection_id": { "type": "string", "format": "uuid", "description": "ID of the collection containing this file" }, "face_id": { "type": "string", "format": "uuid", "description": "ID of the detected face" }, "frame_id": { "type": "string", "format": "uuid", "description": "ID of the frame where the face was detected" }, "score": { "type": "number", "description": "Similarity score (higher is more similar)" }, "timestamp": { "type": "number", "minimum": 0, "description": "Timestamp of the frame in seconds" }, "face_bounding_box": { "type": "object", "properties": { "height": { "type": "number", "minimum": 0, "maximum": 1, "description": "Height of the bounding box (normalized 0-1)" }, "width": { "type": "number", "minimum": 0, "maximum": 1, "description": "Width of the bounding box (normalized 0-1)" }, "top": { "type": "number", "minimum": 0, "maximum": 1, "description": "Top position of the bounding box (normalized 0-1)" }, "left": { "type": "number", "minimum": 0, "maximum": 1, "description": "Left position of the bounding box (normalized 0-1)" } }, "required": ["height", "width", "top", "left"] }, "thumbnail_url": { "type": "string", "description": "URL of the frame thumbnail" } } }, "SegmentGroupResult": { "type": "object", "required": [ "type", "matched_items", "file_id", "item_count", "best_score" ], "properties": { "type": { "type": "string", "enum": ["segment_group"], "description": "Result type, always 'segment_group'" }, "matched_items": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentSearchResult" }, "description": "Array of segment search results that belong to this file" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file that this group represents" }, "item_count": { "type": "integer", "description": "Number of matched items in this group" }, "best_score": { "type": "number", "description": "The highest score among all items in this group" } } }, "MomentSearchResult": { "description": "A moment search hit (scope='moment'): the full moment record plus provenance and a query-relevance search_score.", "allOf": [ { "$ref": "#/components/schemas/Moment" }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["moment"] }, "file_id": { "type": "string", "format": "uuid" }, "collection_id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid", "description": "The find-moments run that produced this moment" }, "criterion_name": { "type": "string" }, "search_score": { "type": "number", "description": "Query relevance for this search only — unrelated to the moment's criterion_score and rank_score" }, "filename": { "type": "string", "nullable": true } }, "required": [ "type", "file_id", "collection_id", "job_id", "criterion_name", "search_score", "filename" ] } ] }, "FaceGroupResult": { "type": "object", "required": [ "type", "matched_items", "file_id", "item_count", "best_score" ], "properties": { "type": { "type": "string", "enum": ["face_group"], "description": "Result type, always 'face_group'" }, "matched_items": { "type": "array", "items": { "$ref": "#/components/schemas/FaceSearchResult" }, "description": "Array of face search results that belong to this file" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file that this group represents" }, "item_count": { "type": "integer", "description": "Number of matched items in this group" }, "best_score": { "type": "number", "description": "The highest score among all items in this group" } } }, "ThumbnailList": { "type": "object", "required": ["object", "total", "limit", "offset", "data"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "total": { "type": "integer", "description": "Total number of segmentations matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Thumbnail" } } } }, "Thumbnail": { "type": "object", "required": ["id", "url", "time"], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the thumbnail" }, "url": { "type": "string", "description": "The URL of the thumbnail" }, "time": { "type": "number", "description": "The time of the thumbnail in seconds relative to the start of the video" }, "segmentation_id": { "type": "string", "format": "uuid", "description": "The ID of the segmentation if part of a segmentation job" }, "type": { "$ref": "#/components/schemas/ThumbnailType" }, "segment_id": { "type": "string", "format": "uuid", "description": "The ID of the segment if part of a segmentation job" } } }, "NewSegments": { "type": "object", "required": ["url", "criteria"], "properties": { "url": { "type": "string", "description": "Input video or audio file URL. Supports URIs of files uploaded to Cloudglue Files endpoint, public HTTP URLs, YouTube URLs (narrative criteria only), public TikTok video URLs, public Loom share URLs, and files which have been granted access to Cloudglue via data connectors.\n\n**⚠️ Important: YouTube URLs and audio files are ONLY supported for narrative-based segmentation.** Shot-based segmentation requires direct video file access and does not support YouTube URLs or audio files. For YouTube URLs and audio files with narrative segmentation, only the 'balanced' and 'transcript' strategies are accepted; the 'comprehensive' strategy will be rejected with an error. Public TikTok video URLs will be scraped and stored automatically — subject to charges. For files via our Data connectors, see our documentation on data connectors for setup information." }, "criteria": { "type": "string", "enum": ["shot", "narrative"], "description": "Segmentation criteria:\n• **shot**: Detect scene changes and shot boundaries using computer vision (not supported for YouTube URLs or audio files)\n• **narrative**: Identify logical narrative segments and chapters using AI analysis (supports YouTube URLs and audio files)" }, "shot_config": { "$ref": "#/components/schemas/ShotConfig", "description": "Configuration for shot-based segmentation. Only provide when criteria is 'shot'." }, "narrative_config": { "$ref": "#/components/schemas/NarrativeConfig", "description": "Configuration for narrative-based segmentation. Only provide when criteria is 'narrative'." } } }, "ShotConfig": { "type": "object", "properties": { "detector": { "type": "string", "enum": ["content", "adaptive"], "description": "Detection algorithm:\n• **adaptive**: Designed for dynamic footage with camera movement and action (default)\n• **content**: Optimized for controlled footage with clear visual transitions" }, "max_duration_seconds": { "type": "number", "minimum": 1, "maximum": 600, "description": "Maximum duration for each segment in seconds (1 second to 10 minutes, default: 5 minutes)" }, "min_duration_seconds": { "type": "number", "minimum": 0.6, "maximum": 600, "description": "Minimum duration for each segment in seconds (0.6 seconds to 10 minutes, default: 0.6 seconds)" }, "fill_gaps": { "type": "boolean", "description": "When true, gaps between detected shots are filled: gaps greater than or equal to min_duration_seconds become their own segments (split by max_duration_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true." } } }, "NarrativeConfig": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Optional custom prompt to guide the narrative segmentation analysis. This will be incorporated into the main segmentation prompt as additional guidance." }, "strategy": { "type": "string", "enum": ["comprehensive", "balanced", "transcript"], "description": "Narrative segmentation strategy:\n\n• **comprehensive**: Uses a VLM to deeply analyze logical segments of video. Only available for video files (not YouTube or audio).\n\n• **balanced** (default): Balanced analysis approach using multiple modalities. Supports YouTube URLs and audio files.\n\n• **transcript**: Cheap and fast speech-transcript-based segmentation. Requires a transcript; returns an error for silent or visual-only content (use `balanced` instead, or `comprehensive` for non-YouTube/non-audio video files).\n\n**Note**: YouTube URLs and audio files only support the **balanced** and **transcript** strategies; **comprehensive** will be rejected with an error." }, "number_of_chapters": { "type": "integer", "minimum": 1, "description": "Optional target number of chapters to generate. If provided, min_chapters and max_chapters will be calculated automatically if not specified. If only target is provided, the AI will attempt to generate exactly this number of chapters." }, "min_chapters": { "type": "integer", "minimum": 1, "description": "Optional minimum number of chapters to generate. If provided along with number_of_chapters and max_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically." }, "max_chapters": { "type": "integer", "minimum": 1, "description": "Optional maximum number of chapters to generate. If provided along with number_of_chapters and min_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically." } } }, "Segments": { "type": "object", "required": [ "file_id", "job_id", "object", "status", "criteria", "created_at" ], "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the segment job" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file this segment belongs to" }, "object": { "type": "string", "enum": ["segments"], "description": "Object type, always 'segments'" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Current status of the segment job" }, "criteria": { "type": "string", "enum": ["shot", "narrative"], "description": "Segment criteria used for this job" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the job was created" }, "shot_config": { "$ref": "#/components/schemas/ShotConfig", "description": "Configuration used for shot-based segmentation (only present when criteria is 'shot')" }, "narrative_config": { "$ref": "#/components/schemas/NarrativeConfig", "description": "Configuration used for narrative-based segmentation (only present when criteria is 'narrative')" }, "total_segments": { "type": "integer", "minimum": 0, "description": "Total number of segments generated (only present when status is 'completed')" }, "total_shots": { "type": "integer", "minimum": 0, "description": "Total number of shots in the original video (only present when criteria is 'shot')" }, "total_chapters": { "type": "integer", "minimum": 0, "description": "Total number of chapters in the video (only present when criteria is 'narrative')" }, "segments": { "type": "array", "description": "Array of generated segments (only present when status is 'completed')", "items": { "$ref": "#/components/schemas/Segment" } }, "shots": { "type": "array", "description": "Array of shots in the original video (only present when criteria is 'shot')", "items": { "$ref": "#/components/schemas/Shot" } }, "chapters": { "type": "array", "description": "Array of narrative chapters in the video (only present when criteria is 'narrative')", "items": { "$ref": "#/components/schemas/Chapter" } } } }, "SegmentsListItem": { "type": "object", "required": [ "file_id", "job_id", "object", "status", "criteria", "created_at" ], "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the segment job" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the file this segment belongs to" }, "object": { "type": "string", "enum": ["segments"], "description": "Object type, always 'segments'" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Current status of the segment job" }, "criteria": { "type": "string", "enum": ["shot", "narrative"], "description": "Segment criteria used for this job" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the job was created" }, "shot_config": { "$ref": "#/components/schemas/ShotConfig", "description": "Configuration used for shot-based segmentation (only present when criteria is 'shot')" }, "narrative_config": { "$ref": "#/components/schemas/NarrativeConfig", "description": "Configuration used for narrative-based segmentation (only present when criteria is 'narrative')" } }, "description": "Segmentation job object as returned in list responses (does not include segments array or total_segments)" }, "Segment": { "type": "object", "required": ["start_time", "end_time"], "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Start time of the segment in seconds" }, "end_time": { "type": "number", "minimum": 0, "description": "End time of the segment in seconds" }, "description": { "type": "string", "description": "Optional description of the segment content (available for narrative segmentation)" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Optional URL of the thumbnail for this segment" }, "shot_index": { "type": "integer", "description": "Index of the shot in the original video segmentation. Only present when criteria is set to 'shot'" } } }, "Shot": { "type": "object", "required": ["index", "start_time", "end_time"], "properties": { "index": { "type": "integer", "description": "Index of the shot in the original video" }, "start_time": { "type": "number", "minimum": 0, "description": "Start time of the shot in seconds" }, "end_time": { "type": "number", "minimum": 0, "description": "End time of the shot in seconds" } } }, "Chapter": { "type": "object", "required": ["index", "start_time", "end_time", "description"], "properties": { "index": { "type": "integer", "description": "Index of the chapter in the video" }, "start_time": { "type": "number", "minimum": 0, "description": "Start time of the chapter in seconds" }, "end_time": { "type": "number", "minimum": 0, "description": "End time of the chapter in seconds" }, "description": { "type": "string", "description": "AI-generated description of the chapter content" } } }, "SegmentsList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentsListItem" }, "description": "Array of segmentation job objects (without segments array or total_segments)" }, "total": { "type": "integer", "description": "Total number of segmentation jobs matching the query" }, "limit": { "type": "integer", "description": "Number of items returned in this response" }, "offset": { "type": "integer", "description": "Offset from the start of the list" } }, "required": ["object", "data", "total", "limit", "offset"] }, "FaceMatchRequest": { "type": "object", "required": ["source_image", "target_video_url"], "properties": { "source_image": { "$ref": "#/components/schemas/SourceImage", "description": "Source image containing the face to search for" }, "target_video_url": { "type": "string", "description": "URL of the target video to search in" }, "max_faces": { "type": "integer", "minimum": 1, "maximum": 4000, "description": "Maximum number of faces to return" }, "face_detection_id": { "type": "string", "format": "uuid", "description": "Optional: Use previously analyzed face detections in video" }, "frame_extraction_id": { "type": "string", "format": "uuid", "description": "Optional: Use previously extracted frames" }, "frame_extraction_config": { "$ref": "#/components/schemas/FrameExtractionConfig", "description": "Optional: Frame extraction configuration" } } }, "FaceMatch": { "type": "object", "required": ["face_match_id", "status", "created_at"], "properties": { "face_match_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the face match job" }, "face_detection_id": { "type": "string", "format": "uuid", "description": "ID of the face detection analysis used" }, "frame_extraction_id": { "type": "string", "format": "uuid", "description": "ID of the frame extraction used" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the target file" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Status of the face match job" }, "created_at": { "type": "number", "description": "Unix timestamp in milliseconds when the job was created" }, "source_face_bounding_box": { "allOf": [ { "$ref": "#/components/schemas/FaceBoundingBox" } ], "nullable": true, "description": "Bounding box of the source face in the source image (null when job is pending/processing)" }, "data": { "type": "object", "description": "Face match results (only present when status is completed)", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "total": { "type": "integer", "description": "Total number of face matches found" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of face matches returned per page" }, "offset": { "type": "integer", "minimum": 0, "description": "Offset from the start of the face matches list" }, "faces_matches": { "type": "array", "items": { "$ref": "#/components/schemas/FaceMatchResult" }, "description": "Array of face matches found" } } } } }, "FaceDetectionRequest": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "description": "URL of the target video to analyze" }, "frame_extraction_id": { "type": "string", "format": "uuid", "description": "Optional: Use previously extracted frames" }, "frame_extraction_config": { "$ref": "#/components/schemas/FrameExtractionConfig", "description": "Optional: Frame extraction configuration" } } }, "FaceDetection": { "type": "object", "required": ["face_detection_id", "status", "created_at"], "properties": { "face_detection_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the face detection job" }, "frame_extraction_id": { "type": "string", "format": "uuid", "description": "ID of the frame extraction used" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the target file" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Status of the face detection job" }, "created_at": { "type": "number", "description": "Unix timestamp in milliseconds when the job was created" }, "data": { "type": "object", "description": "Face detection results (only present when status is completed)", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "total": { "type": "integer", "description": "Total number of faces detected" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of faces returned per page" }, "offset": { "type": "integer", "minimum": 0, "description": "Offset from the start of the faces list" }, "faces": { "type": "array", "items": { "$ref": "#/components/schemas/DetectedFace" }, "description": "Array of detected faces" } } } } }, "SourceImage": { "type": "object", "description": "Source image configuration - either url or base64_image must be provided", "properties": { "url": { "type": "string", "description": "Public URL of the source image" }, "base64_image": { "type": "string", "description": "Base64 encoded JPEG image data" } } }, "FaceBoundingBox": { "type": "object", "required": ["height", "width", "top", "left"], "properties": { "height": { "type": "number", "minimum": 0, "maximum": 1, "description": "Height of the bounding box (normalized 0-1)" }, "width": { "type": "number", "minimum": 0, "maximum": 1, "description": "Width of the bounding box (normalized 0-1)" }, "top": { "type": "number", "minimum": 0, "maximum": 1, "description": "Top position of the bounding box (normalized 0-1)" }, "left": { "type": "number", "minimum": 0, "maximum": 1, "description": "Left position of the bounding box (normalized 0-1)" } } }, "FaceMatchResult": { "type": "object", "required": [ "id", "face_bounding_box", "similarity", "frame_id", "timestamp" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the face match result" }, "face_bounding_box": { "$ref": "#/components/schemas/FaceBoundingBox", "description": "Bounding box of the matched face in the frame" }, "similarity": { "type": "number", "minimum": 0, "maximum": 100, "description": "Similarity score between source face and detected face (0-100)" }, "frame_id": { "type": "string", "format": "uuid", "description": "ID of the frame where the match was found" }, "timestamp": { "type": "number", "description": "Timestamp of the frame in seconds" }, "thumbnail_url": { "type": "string", "description": "URL of the frame thumbnail (if frame extraction enabled thumbnails)" } } }, "DetectedFace": { "type": "object", "required": ["id", "face_bounding_box", "frame_id", "timestamp"], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the detected face" }, "face_bounding_box": { "$ref": "#/components/schemas/FaceBoundingBox", "description": "Bounding box of the detected face in the frame" }, "frame_id": { "type": "string", "format": "uuid", "description": "ID of the frame where the face was detected" }, "timestamp": { "type": "number", "description": "Timestamp of the frame in seconds" }, "thumbnail_url": { "type": "string", "description": "URL of the frame thumbnail (if frame extraction enabled thumbnails)" } } }, "SearchModalities": { "type": "array", "items": { "type": "string", "enum": [ "general_content", "speech_lexical", "ocr_lexical", "tag_semantic", "tag_lexical", "doc_lexical" ] }, "maxItems": 5, "description": "Specifies the type(s) of search to execute. When multiple modalities are specified, a hybrid search is executed that combines results from each modality.\n\nAvailable modalities:\n- `general_content`: baseline for matching the content of the search item (file/segment) based on visual or spoken content similarity to provided short natural language query string\n- `speech_lexical`: performs keyword based search (e.g. query of `president` matching `president` or `presidential` strings) and exact match (e.g. specifically find mentions of `\"Barack Obama\"` or `\"Donald Trump\"`) against speech content present in search item\n- `ocr_lexical`: performs keyword based search and exact match against screen text content present in search item\n- `tag_semantic`: performs basic word semantic similarity search against tag values associated with search items (e.g. `query=animal` expected to match tags with value containing `dog` or `cat`)\n- `tag_lexical`: performs keyword based search and exact match against tag values associated with search items\n- `doc_lexical`: performs keyword based search and exact match against file-level documents (generated summaries, metadata-collection docs, and entity-collection docs). Only applicable when search `scope=file`.\n\nOnly applicable when search `scope=file` or `scope=segment`.\n" }, "ThumbnailType": { "type": "string", "description": "The type of the thumbnail: 'segment' for segment thumbnails, 'keyframe' for keyframes, 'file' for file thumbnails, 'frame' for frame thumbnails. Comma separated string of one or more types." }, "FileSegment": { "type": "object", "required": [ "id", "file_id", "start_time", "end_time", "thumbnail_url" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the segment" }, "file_id": { "type": "string", "format": "uuid", "description": "The ID of the file" }, "start_time": { "type": "number", "description": "The start time of the segment in seconds" }, "end_time": { "type": "number", "description": "The end time of the segment in seconds" }, "thumbnail_url": { "type": "string", "description": "The URL of the thumbnail for the segment (if available)" }, "metadata": { "type": "object", "description": "The user defined metadata for the segment" }, "segmentation_id": { "type": "string", "format": "uuid", "description": "The ID of the segmentation job it belongs to" } } }, "PaginationResponse": { "type": "object", "required": ["object", "total", "limit", "offset"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "total": { "type": "integer", "description": "The total number of items" }, "limit": { "type": "integer", "description": "The number of items per page" }, "offset": { "type": "integer", "description": "The offset of the items" } } }, "ListVideoTagsResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationResponse" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoTag" }, "description": "The list of tags" } } } ] }, "VideoTag": { "type": "object", "required": ["id", "label", "value", "type", "file_id"], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the tag" }, "label": { "type": "string", "description": "The label of the tag" }, "value": { "type": "string", "description": "The value of the tag" }, "type": { "type": "string", "enum": ["file", "segment"], "description": "The type of the tag" }, "file_id": { "type": "string", "format": "uuid", "description": "The ID of the file" }, "segment_id": { "type": "string", "format": "uuid", "description": "The ID of the segment" } } }, "CreateVideoTagRequest": { "type": "object", "required": ["label", "value", "file_id"], "properties": { "label": { "type": "string", "description": "The label of the tag" }, "value": { "type": "string", "description": "The value of the tag" }, "file_id": { "type": "string", "format": "uuid", "description": "The ID of the file" }, "segment_id": { "type": "string", "format": "uuid", "description": "The ID of the segment" } } }, "UpdateVideoTagRequest": { "type": "object", "properties": { "label": { "type": "string", "description": "The label of the tag" }, "value": { "type": "string", "description": "The value of the tag" } } }, "SearchTagResponse": { "type": "object", "description": "The associated tag for the search result if it exists. Only provided for search requests with tag_semantic or tag_lexical search modalities.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the tag" }, "value": { "type": "string", "description": "The value of the tag" }, "label": { "type": "string", "description": "The label of the tag" } } }, "FaceMatchListResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationResponse" }, { "properties": { "data": { "type": "array", "items": { "type": "object", "required": ["job_id", "status", "created_at"], "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the face match job" }, "face_detection_id": { "type": "string", "format": "uuid", "description": "ID of the face detection analysis used" }, "frame_extraction_id": { "type": "string", "format": "uuid", "description": "ID of the frame extraction used" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the target file" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Status of the face match job" }, "created_at": { "type": "number", "description": "Unix timestamp in milliseconds when the job was created" }, "source_face_bounding_box": { "allOf": [ { "$ref": "#/components/schemas/FaceBoundingBox" } ], "nullable": true, "description": "Bounding box of the source face in the source image (null when job is pending/processing)" }, "match_count": { "type": "integer", "description": "Number of matches found" } } } } } } ] }, "FaceDetectionListResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationResponse" }, { "properties": { "data": { "type": "array", "items": { "type": "object", "required": ["job_id", "status", "created_at"], "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the face detection job" }, "frame_extraction_id": { "type": "string", "format": "uuid", "description": "ID of the frame extraction used" }, "file_id": { "type": "string", "format": "uuid", "description": "ID of the target file" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "Status of the face detection job" }, "created_at": { "type": "number", "description": "Unix timestamp in milliseconds when the job was created" }, "total_faces": { "type": "integer", "description": "Total number of faces detected" } } } } } } ] }, "ChatCompletionList": { "type": "object", "required": ["object", "data", "total", "limit", "offset"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "created_at", "object", "model", "usage", "choices", "payload" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the chat completion" }, "created_at": { "type": "number", "description": "The timestamp of the chat completion" }, "object": { "type": "string", "enum": ["chat.completion"], "description": "Object type, always 'chat.completion'" }, "model": { "type": "string", "description": "The model used for the chat completion" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "description": "The number of tokens in the prompt" }, "completion_tokens": { "type": "integer", "description": "The number of tokens in the completion" }, "total_tokens": { "type": "integer", "description": "The total number of tokens in the request" } }, "description": "The usage of the chat completion" }, "choices": { "type": "array", "items": { "type": "object", "required": ["index", "message"], "properties": { "index": { "type": "integer", "description": "The index of the choice" }, "message": { "$ref": "#/components/schemas/ChatMessage" } } }, "description": "The choices of the chat completion" }, "payload": { "$ref": "#/components/schemas/ChatCompletionPayload" } } }, "description": "The list of chat completions" }, "total": { "type": "integer", "description": "The total number of items" }, "limit": { "type": "integer", "description": "The number of items per page" }, "offset": { "type": "integer", "description": "The offset of the items" } } }, "ChatCompletionPayload": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "temperature": { "type": "number", "description": "The temperature of the chat completion" }, "filter": { "$ref": "#/components/schemas/SearchFilter" }, "collections": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "FileSegmentListResponse": { "type": "object", "required": ["object", "data", "total", "limit", "offset"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FileSegment" } }, "total": { "type": "integer", "description": "The total number of items" }, "limit": { "type": "integer", "description": "The number of items per page" }, "offset": { "type": "integer", "description": "The offset of the items" } } }, "ShareableAssetListResponse": { "type": "object", "required": ["object", "data", "total", "limit", "offset"], "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type, always 'list'" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShareableAsset" } }, "total": { "type": "integer", "description": "The total number of items" }, "limit": { "type": "integer", "description": "The number of items per page" }, "offset": { "type": "integer", "description": "The offset of the items" } } }, "ShareableAsset": { "type": "object", "required": ["id", "file_id", "url", "link_preview", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the shareable asset" }, "file_id": { "type": "string", "format": "uuid", "description": "The ID of the file the shareable asset belongs to" }, "file_segment_id": { "type": "string", "format": "uuid", "description": "The ID of the file segment the shareable asset belongs to (optional)" }, "title": { "type": "string", "description": "The title of the shareable asset" }, "description": { "type": "string", "description": "The description of the shareable asset" }, "metadata": { "type": "object", "description": "The metadata of the shareable asset" }, "visibility": { "type": "string", "enum": ["public", "private"], "description": "The visibility of the shareable asset. 'public' assets are viewable by anyone with the link; 'private' assets are restricted to members of the owning account and stream via a signed, token-gated playback url." }, "link_preview": { "type": "string", "enum": ["none", "full", "player"], "description": "Controls rich link-preview (Open Graph) metadata for unfurl bots on private shares. 'none' (default) emits no preview metadata; 'full' emits title, description, and thumbnail; 'player' additionally lets the share play inline when its link is unfurled by the Cloudglue Slack app — anyone who can see the Slack message can play it. Public shares always emit full metadata (and unfurl playable where the Slack app is installed) regardless of this value." }, "preview_url": { "type": "string", "description": "The thumbnail url of the shareable asset" }, "media_download_url": { "type": "string", "description": "The signed media download url of the shareable asset. For private assets this url is short-lived (a few minutes) and should be used promptly." }, "media_download_expires_at": { "type": "number", "nullable": true, "description": "The timestamp of when the media download url will expire" }, "share_url": { "type": "string", "description": "This is the url that can be used to share the shareable asset. For private assets the page requires sign-in and membership of the owning account." }, "stream_url": { "type": "string", "description": "The HLS stream url of the shareable asset. Available when the stream has finished processing. For private assets this is a signed, token-gated url that should be treated as short-lived. When the asset was fetched with a clip window (clip_start/clip_end on GET /share/{id}), the stream plays only that window." }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"], "description": "The status of the shareable asset" }, "asset_type": { "type": "string", "enum": ["file", "file_segment"], "description": "The type of asset the shareable asset belongs to" }, "created_at": { "type": "number", "description": "The timestamp of when the shareable asset was created" }, "object": { "type": "string", "enum": ["share"], "description": "Object type, always 'share'" } } }, "CreateShareableAssetRequest": { "type": "object", "required": ["file_id"], "properties": { "file_id": { "type": "string", "format": "uuid", "description": "The ID of the file the shareable asset will be created for" }, "file_segment_id": { "type": "string", "format": "uuid", "description": "The ID of the file segment the shareable asset will be created for. When provided, the shareable asset will be created for the file segment." }, "title": { "type": "string", "description": "The title of the shareable asset" }, "description": { "type": "string", "description": "The description of the shareable asset" }, "metadata": { "type": "object", "description": "The metadata of the shareable asset" }, "visibility": { "type": "string", "enum": ["public", "private"], "default": "public", "description": "Visibility of the shareable asset. Defaults to 'public'. 'private' restricts the share page to members of the owning account and serves a signed, token-gated stream. Cannot be changed after creation." }, "link_preview": { "type": "string", "enum": ["none", "full", "player"], "default": "none", "description": "Rich link-preview metadata for unfurl bots. Only affects private shares: 'none' (default) keeps today's no-preview behavior; 'full' emits title, description, and thumbnail Open Graph tags; 'player' additionally lets the share play inline when unfurled by the Cloudglue Slack app — anyone who can see the Slack message can play it. Public shares always emit full metadata." } } }, "UpdateShareableAssetRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the shareable asset" }, "description": { "type": "string", "description": "The description of the shareable asset" }, "metadata": { "type": "object", "description": "The metadata of the shareable asset" }, "link_preview": { "type": "string", "enum": ["none", "full", "player"], "description": "Rich link-preview metadata for unfurl bots. Only affects private shares: 'none' keeps today's no-preview behavior; 'full' emits title, description, and thumbnail Open Graph tags; 'player' additionally lets the share play inline when unfurled by the Cloudglue Slack app — anyone who can see the Slack message can play it. Downgrading from 'player' revokes playback in already-posted unfurls. Public shares always emit full metadata." } } }, "ModalitiesSchema": { "type": "array", "items": { "type": "string", "enum": [ "speech", "visual_scene_description", "scene_text", "audio_description", "summary", "segment_summary", "title" ] }, "description": "The modalities to output in the response. Can be used to return smaller data sets. Comma separated list of strings. Defaults to all modalities available / previously extracted. Accepted values are speech,visual_scene_description,scene_text, audio_description, summary, segment_summary, title" }, "CreateDeepSearchRequest": { "type": "object", "required": ["query", "knowledge_base"], "properties": { "knowledge_base": { "description": "Knowledge base configuration. Determines which content to search.\n\nThree source modes are supported:\n- `collections`: Search within specific collections\n- `files`: Search specific files by URL or file ID (uses default index)\n- `default`: Search all default-indexed files for the account", "oneOf": [ { "$ref": "#/components/schemas/DeepSearchKBCollections" }, { "$ref": "#/components/schemas/DeepSearchKBFiles" }, { "$ref": "#/components/schemas/DeepSearchKBDefault" } ] }, "query": { "type": "string", "minLength": 1, "description": "The search query." }, "scope": { "type": "string", "enum": ["segment", "file"], "description": "The scope of results to return. 'segment' returns individual segments, 'file' returns file-level results — explicit values behave exactly as before, and every collection in the knowledge base must be searchable at the requested scope (metadata and file-level entities collections require 'file'; segment-level entities collections require 'segment'). Omit for auto: the search planner picks a scope per search plan, each collection is searched at the scopes its documents support, and results from both scopes are fused — so a knowledge base can mix collection types (e.g. rich-transcripts + metadata + entities) without a scope." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 20, "description": "Maximum number of results to return. Actual count may be lower when exclude_weak_results is enabled." }, "exclude_weak_results": { "type": "boolean", "default": false, "description": "When true, removes results tagged as weak matches by the synthesis LLM." }, "include": { "type": "array", "items": { "type": "string", "enum": ["search_queries"] }, "description": "Additional fields to include in the response. 'search_queries' includes the intermediate search query plan." }, "stream": { "type": "boolean", "default": false, "description": "Stream the response via SSE. Mutually exclusive with background." }, "background": { "type": "boolean", "default": false, "description": "Process in the background. Returns immediately with status 'in_progress'. Mutually exclusive with stream." } } }, "DeepSearchKBCollections": { "type": "object", "description": "Search within specific collections.", "required": ["source", "collections"], "properties": { "source": { "type": "string", "enum": ["collections"], "description": "Source mode identifier." }, "collections": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Collection IDs to search. Collections must be of type rich-transcripts, media-descriptions, metadata, or entities. With an explicit scope, every collection must be searchable at it: metadata collections only have file-level docs and require scope='file'; entities collections follow their extraction level — file-level extraction (enable_video_level_entities or enable_metadata_mode) requires scope='file', segment-level extraction (enable_segment_level_entities) requires scope='segment'. When scope is omitted (auto), collection types can be mixed freely: each collection is searched at the scopes its documents support." }, "filter": { "description": "Optional filter to narrow down the search within collections.", "allOf": [ { "$ref": "#/components/schemas/SearchFilter" } ] } } }, "DeepSearchKBFiles": { "type": "object", "description": "Search specific files by URL or file ID. Files must have been described or added to a collection to be searchable.", "required": ["source", "files"], "properties": { "source": { "type": "string", "enum": ["files"], "description": "Source mode identifier." }, "files": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "File references to search. Can be file UUIDs, cloudglue URIs (`cloudglue://files/...`), data connector URLs, or HTTP URLs." } } }, "DeepSearchKBDefault": { "type": "object", "description": "Search all default-indexed files for the account. Includes any file that has been described (with `use_in_default_index: true`) or added to a collection.", "required": ["source"], "properties": { "source": { "type": "string", "enum": ["default"], "description": "Source mode identifier." } } }, "DeepSearchResult": { "type": "object", "properties": { "type": { "type": "string", "enum": ["segment", "file"], "description": "The type of result" }, "id": { "type": "string", "format": "uuid", "description": "Result ID" }, "file_id": { "type": "string", "format": "uuid", "description": "The file ID this result belongs to" }, "collection_id": { "type": "string", "format": "uuid", "description": "The collection ID this result belongs to. Present when using `collections` source; omitted for `files` and `default` sources." }, "score": { "type": "number", "description": "Relevance score" }, "context": { "type": "string", "description": "LLM-generated context explaining why this result is relevant" }, "segment_id": { "type": "string", "format": "uuid", "description": "Segment ID (present when type is 'segment')" }, "start_time": { "type": "number", "description": "Start time in seconds (present when type is 'segment')" }, "end_time": { "type": "number", "description": "End time in seconds (present when type is 'segment')" }, "title": { "type": "string", "nullable": true, "description": "Segment title" }, "filename": { "type": "string", "nullable": true, "description": "Original filename" }, "thumbnail_url": { "type": "string", "nullable": true, "description": "URL to a thumbnail image" }, "metadata": { "type": "object", "nullable": true, "description": "Additional metadata" }, "summary": { "type": "string", "nullable": true, "description": "File summary (present when type is 'file')" }, "generated_title": { "type": "string", "nullable": true, "description": "Generated title (present when type is 'file')" } } }, "DeepSearchUsage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "description": "Number of output tokens used" }, "total_tokens": { "type": "integer", "description": "Total number of tokens used" }, "search_calls": { "type": "integer", "description": "Number of search calls made" } } }, "DeepSearchSearchQueryPlan": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query" }, "search_modalities": { "type": "array", "items": { "type": "string" }, "description": "Modalities used for this search" }, "scope": { "type": "string", "description": "Search scope" }, "filter": { "type": "object", "nullable": true, "description": "Optional filter applied" }, "result_count": { "type": "integer", "description": "Number of results returned for this query" } } }, "DeepSearch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Deep search ID" }, "object": { "type": "string", "enum": ["deep_search"], "description": "Object type identifier" }, "status": { "type": "string", "enum": ["in_progress", "completed", "failed", "cancelled"], "description": "Current status of the deep search" }, "created_at": { "type": "number", "description": "Unix timestamp of when the deep search was created" }, "query": { "type": "string", "description": "The original search query" }, "scope": { "type": "string", "enum": ["segment", "file"], "nullable": true, "description": "The scope the caller requested. Null when the request omitted scope (auto: the planner chose scopes per search plan, so results may mix segment and file types)." }, "text": { "type": "string", "nullable": true, "description": "LLM-generated synthesis text summarizing the results" }, "results": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/DeepSearchResult" }, "description": "Array of search results" }, "total": { "type": "integer", "description": "Total number of results" }, "limit": { "type": "integer", "description": "Maximum number of results requested" }, "search_queries": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/DeepSearchSearchQueryPlan" }, "description": "Intermediate search query plans (included when requested via include=['search_queries'])" }, "usage": { "nullable": true, "$ref": "#/components/schemas/DeepSearchUsage", "description": "Token and search call usage" }, "error": { "type": "object", "nullable": true, "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": "string" } }, "description": "Error details if the deep search failed" } } }, "DeepSearchListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Deep search ID" }, "object": { "type": "string", "enum": ["deep_search"], "description": "Object type identifier" }, "status": { "type": "string", "enum": ["in_progress", "completed", "failed", "cancelled"], "description": "Current status" }, "created_at": { "type": "number", "description": "Unix timestamp of creation" }, "query": { "type": "string", "description": "The original search query" }, "scope": { "type": "string", "enum": ["segment", "file"], "nullable": true, "description": "The scope the caller requested; null when the request omitted scope (auto)" }, "total": { "type": "integer", "description": "Total number of results" }, "usage": { "nullable": true, "$ref": "#/components/schemas/DeepSearchUsage", "description": "Token and search call usage" } } }, "DeepSearchList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type identifier" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeepSearchListItem" }, "description": "Array of deep search items" }, "total": { "type": "integer", "description": "Total number of deep searches" }, "limit": { "type": "integer", "description": "Maximum number of items returned" }, "offset": { "type": "integer", "description": "Number of items skipped" } } }, "DeleteDeepSearchResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted deep search" }, "object": { "type": "string", "enum": ["deep_search"], "description": "Object type identifier" }, "deleted": { "type": "boolean", "enum": [true], "description": "Indicates successful deletion" } } }, "GrainSourceMetadata": { "type": "object", "description": "Source provenance captured from Grain at ingest time. The richer AI/contextual fields are only present when Grain returns them.", "properties": { "source_type": { "type": "string", "enum": ["grain"], "description": "Discriminator identifying the upstream connector." }, "grain_recording_id": { "type": "string", "description": "Grain's recording id." }, "title": { "type": "string", "description": "Recording title.", "nullable": true }, "start_datetime": { "type": "string", "format": "date-time", "description": "UTC time Grain started the recording.", "nullable": true }, "end_datetime": { "type": "string", "format": "date-time", "description": "UTC time the recording ended.", "nullable": true }, "duration_ms": { "type": "integer", "description": "Recording duration in milliseconds.", "nullable": true }, "media_type": { "type": "string", "enum": ["audio", "transcript", "video"], "description": "Grain media type of the recording.", "nullable": true }, "upstream_source": { "type": "string", "enum": [ "aircall", "local_capture", "meet", "teams", "upload", "webex", "zoom", "other" ], "description": "Platform Grain captured the recording from.", "nullable": true }, "grain_url": { "type": "string", "description": "URL to the recording in Grain.", "nullable": true }, "thumbnail_url": { "type": "string", "nullable": true, "description": "Thumbnail URL, null if none." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags applied to the recording.", "nullable": true }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "description": "Teams the recording belongs to.", "nullable": true }, "meeting_type": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scope": { "type": "string" } }, "description": "Recording's meeting type, null if none." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "scope": { "type": "string", "enum": ["internal", "external", "unknown"] }, "confirmed_attendee": { "type": "boolean" }, "hs_contact_id": { "type": "string", "nullable": true, "description": "HubSpot contact id, if linked." } } }, "nullable": true, "description": "Meeting participants (include-gated by Grain). Null when requested but empty." }, "highlights": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "Clips / highlights (include-gated). Null when requested but empty." }, "ai_summary": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown AI summary." } }, "nullable": true, "description": "AI summary (include-gated). Null when requested but empty." }, "ai_action_items": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending", "completed"] }, "timestamp_ms": { "type": "integer", "description": "Time in the recording the item was mentioned." }, "text": { "type": "string" }, "assignee": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "user_id": { "type": "string", "nullable": true } } } } }, "nullable": true, "description": "AI action items (include-gated). Null when requested but empty." }, "ai_template_sections": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "AI template sections, shape varies by template (include-gated). Null when requested but empty." }, "calendar_event": { "type": "object", "nullable": true, "properties": { "ical_uid": { "type": "string" } }, "description": "Related calendar event (include-gated)." }, "hubspot": { "type": "object", "properties": { "hubspot_company_ids": { "type": "array", "items": { "type": "string" } }, "hubspot_deal_ids": { "type": "array", "items": { "type": "string" } } }, "nullable": true, "description": "Related HubSpot company/deal ids (include-gated). Null when requested but empty." } }, "required": ["source_type", "grain_recording_id"] }, "ZoomSourceMetadata": { "type": "object", "description": "Source provenance captured from Zoom at ingest time. Signed download/play URLs, share URLs, and passcodes are never included.", "properties": { "source_type": { "type": "string", "enum": ["zoom"], "description": "Discriminator identifying the upstream connector." }, "zoom_meeting_uuid": { "type": "string", "description": "Zoom meeting instance UUID." }, "zoom_meeting_id": { "type": "integer", "description": "Zoom numeric meeting id.", "nullable": true }, "topic": { "type": "string", "description": "Meeting topic (empty string when Zoom omits it).", "nullable": true }, "start_time": { "type": "string", "format": "date-time", "description": "UTC time the meeting started.", "nullable": true }, "host_id": { "type": "string", "nullable": true, "description": "Zoom host user id." }, "host_email": { "type": "string", "nullable": true, "description": "Host email. Nullable whenever Zoom omits it — both list and per-meeting endpoints may return null depending on account scopes." }, "account_id": { "type": "string", "nullable": true, "description": "Zoom account id." }, "timezone": { "type": "string", "nullable": true, "description": "Meeting timezone." }, "duration_minutes": { "type": "number", "nullable": true, "description": "Meeting duration in minutes (as reported by Zoom)." }, "total_size": { "type": "number", "nullable": true, "description": "Total size of all recording files in bytes." }, "recording_count": { "type": "number", "nullable": true, "description": "Number of recording files for the meeting." }, "meeting_type": { "type": "number", "nullable": true, "description": "Zoom's numeric meeting type." }, "recording_files": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "recording_type": { "type": "string", "nullable": true, "description": "e.g. shared_screen_with_speaker_view, audio_only." }, "file_type": { "type": "string", "nullable": true }, "file_extension": { "type": "string", "nullable": true }, "file_size": { "type": "number", "nullable": true, "description": "File size in bytes." }, "recording_start": { "type": "string", "nullable": true }, "recording_end": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } } }, "description": "Structural facts about each recording file. Download/play URLs are excluded." } }, "required": ["source_type", "zoom_meeting_uuid"] }, "RecallSourceMetadata": { "type": "object", "description": "Source provenance captured from Recall at ingest time. Artifact availability is exposed as booleans — signed artifact download URLs are never included.", "properties": { "source_type": { "type": "string", "enum": ["recall"], "description": "Discriminator identifying the upstream connector." }, "recall_recording_id": { "type": "string", "description": "Recall recording id." }, "created_at": { "type": "string", "nullable": true, "description": "UTC time the recording object was created." }, "started_at": { "type": "string", "nullable": true, "description": "UTC time recording started." }, "completed_at": { "type": "string", "nullable": true, "description": "UTC time recording completed." }, "expires_at": { "type": "string", "nullable": true, "description": "UTC time the recording expires upstream at Recall." }, "status_code": { "type": "string", "nullable": true, "description": "Recall status: done, processing, failed, or paused. Only done recordings can be synced." }, "meeting_title": { "type": "string", "nullable": true, "description": "Meeting title, when Recall's meeting metadata carries one." }, "meeting_platform": { "type": "string", "nullable": true, "description": "Meeting platform (e.g. zoom, google_meet), when available." }, "has_transcript": { "type": "boolean", "description": "Whether a transcript artifact exists.", "nullable": true }, "has_audio": { "type": "boolean", "description": "Whether a separate audio artifact exists.", "nullable": true }, "has_participant_events": { "type": "boolean", "nullable": true, "description": "Whether a participant-events artifact exists." }, "bot_id": { "type": "string", "nullable": true, "description": "Id of the bot that captured the recording." }, "recall_metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Arbitrary caller-supplied metadata attached to the bot/recording in Recall." } }, "required": ["source_type", "recall_recording_id"] }, "GoogleDriveSourceMetadata": { "type": "object", "description": "Source provenance captured from Google Drive at ingest time. Short-lived signed URLs (e.g. thumbnailLink) are never included.", "properties": { "source_type": { "type": "string", "enum": ["google-drive"], "description": "Discriminator identifying the upstream connector." }, "gdrive_file_id": { "type": "string", "description": "Drive file id." }, "name": { "type": "string", "description": "File name.", "nullable": true }, "mime_type": { "type": "string", "nullable": true }, "size_bytes": { "type": "number", "nullable": true }, "created_time": { "type": "string", "nullable": true, "description": "UTC time the file was created in Drive." }, "modified_time": { "type": "string", "nullable": true, "description": "UTC time the file was last modified." }, "web_view_link": { "type": "string", "nullable": true, "description": "Link to view the file in Drive (requires Drive access)." }, "owners": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "display_name": { "type": "string", "nullable": true }, "email_address": { "type": "string", "nullable": true } } }, "description": "File owners." }, "last_modifying_user": { "type": "object", "nullable": true, "properties": { "display_name": { "type": "string", "nullable": true }, "email_address": { "type": "string", "nullable": true } }, "description": "User who last modified the file." }, "parents": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Parent folder ids." }, "shared": { "type": "boolean", "nullable": true, "description": "Whether the file is shared." }, "file_extension": { "type": "string", "nullable": true }, "md5_checksum": { "type": "string", "nullable": true }, "video_media_metadata": { "type": "object", "nullable": true, "properties": { "duration_millis": { "type": "number", "nullable": true, "description": "Video duration in milliseconds." }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true } }, "description": "Drive's video metadata, when Drive has processed the file." } }, "required": ["source_type", "gdrive_file_id"] }, "DropboxSourceMetadata": { "type": "object", "description": "Source provenance captured from Dropbox at ingest time.", "properties": { "source_type": { "type": "string", "enum": ["dropbox"], "description": "Discriminator identifying the upstream connector." }, "dropbox_id": { "type": "string", "description": "Dropbox file id (id:… form)." }, "name": { "type": "string", "description": "File name.", "nullable": true }, "path_lower": { "type": "string", "description": "Lowercased path of the file.", "nullable": true }, "path_display": { "type": "string", "nullable": true, "description": "Display-cased path." }, "size_bytes": { "type": "number", "nullable": true }, "client_modified": { "type": "string", "nullable": true, "description": "Modification time reported by the client that uploaded the file." }, "server_modified": { "type": "string", "nullable": true, "description": "Time the file was last modified on Dropbox." }, "rev": { "type": "string", "nullable": true, "description": "Dropbox revision id." }, "content_hash": { "type": "string", "nullable": true, "description": "Dropbox content hash." }, "is_downloadable": { "type": "boolean", "nullable": true }, "media_info": { "type": "object", "nullable": true, "properties": { "duration_ms": { "type": "number", "nullable": true, "description": "Media duration in milliseconds." }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true } }, "description": "Media dimensions/duration. Only populated at sync/lookup time — Dropbox's list endpoint stopped returning media info in 2019, so items in the list endpoint carry null here." } }, "required": ["source_type", "dropbox_id"] }, "GongSourceMetadata": { "type": "object", "description": "Source provenance captured from Gong at ingest time. Signed media URLs are never included. AI content fields (topics, trackers, brief, key_points) require Gong Call Spotlight entitlement and are only captured at sync/lookup time.", "properties": { "source_type": { "type": "string", "enum": ["gong"], "description": "Discriminator identifying the upstream connector." }, "gong_call_id": { "type": "string", "description": "Gong call id." }, "title": { "type": "string", "description": "Call title (empty string when Gong omits it).", "nullable": true }, "started": { "type": "string", "nullable": true, "description": "UTC time the call started." }, "scheduled": { "type": "string", "nullable": true, "description": "UTC time the call was scheduled for." }, "duration": { "type": "number", "nullable": true, "description": "Call duration in seconds." }, "gong_url": { "type": "string", "nullable": true, "description": "URL to the call in Gong." }, "meeting_url": { "type": "string", "nullable": true, "description": "URL of the underlying meeting." }, "is_private": { "type": "boolean", "nullable": true, "description": "Whether the call is private in Gong. Private calls cannot be listed or synced." }, "purpose": { "type": "string", "nullable": true }, "primary_user_id": { "type": "string", "nullable": true, "description": "Gong user id of the call owner." }, "direction": { "type": "string", "nullable": true, "description": "Inbound, Outbound, Conference, or Unknown." }, "system": { "type": "string", "nullable": true, "description": "Telephony/meeting system the call was held on." }, "scope": { "type": "string", "nullable": true, "description": "Internal, External, or Unknown." }, "language": { "type": "string", "nullable": true, "description": "ISO-639-2B language code Gong detected." }, "workspace_id": { "type": "string", "nullable": true, "description": "Gong workspace id." }, "call_media_type": { "type": "string", "nullable": true, "description": "Gong's media indicator: Video or Audio." }, "parties": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "affiliation": { "type": "string", "nullable": true, "description": "Internal, External, or Unknown." }, "speaker_id": { "type": "string", "nullable": true }, "user_id": { "type": "string", "nullable": true } } }, "description": "Call participants." }, "topics": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "duration": { "type": "number", "nullable": true, "description": "Seconds spent on the topic." } } }, "description": "AI topics (Call Spotlight)." }, "trackers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "count": { "type": "number", "nullable": true } } }, "description": "Tracker keyword hit counts (Call Spotlight)." }, "brief": { "type": "string", "nullable": true, "description": "AI call brief (Call Spotlight)." }, "key_points": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "AI key points (Call Spotlight)." } }, "required": ["source_type", "gong_call_id"] }, "SourceMetadata": { "oneOf": [ { "$ref": "#/components/schemas/GrainSourceMetadata" }, { "$ref": "#/components/schemas/ZoomSourceMetadata" }, { "$ref": "#/components/schemas/RecallSourceMetadata" }, { "$ref": "#/components/schemas/GoogleDriveSourceMetadata" }, { "$ref": "#/components/schemas/DropboxSourceMetadata" }, { "$ref": "#/components/schemas/GongSourceMetadata" }, { "$ref": "#/components/schemas/IconikSourceMetadata" } ], "discriminator": { "propertyName": "source_type", "mapping": { "grain": "#/components/schemas/GrainSourceMetadata", "zoom": "#/components/schemas/ZoomSourceMetadata", "recall": "#/components/schemas/RecallSourceMetadata", "google-drive": "#/components/schemas/GoogleDriveSourceMetadata", "dropbox": "#/components/schemas/DropboxSourceMetadata", "gong": "#/components/schemas/GongSourceMetadata", "iconik": "#/components/schemas/IconikSourceMetadata" } }, "description": "Per-source provenance captured from the upstream connector, discriminated by source_type. Populated for Grain, Zoom, Recall, Google Drive, Dropbox, Gong, and iconik; files synced before a connector was upgraded carry null. S3/GCS files carry null (plain object stores have no richer metadata)." }, "SourceMetadataResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": ["source_metadata"] }, "source_metadata": { "$ref": "#/components/schemas/SourceMetadata" } }, "required": ["object", "source_metadata"] }, "IconikSourceMetadata": { "type": "object", "description": "Source provenance captured from iconik at ingest time. Signed download URLs are never included.", "properties": { "source_type": { "type": "string", "enum": ["iconik"], "description": "Discriminator identifying the upstream connector." }, "iconik_asset_id": { "type": "string", "description": "iconik asset id." }, "title": { "type": "string", "nullable": true, "description": "Asset title." }, "media_type": { "type": "string", "nullable": true, "description": "iconik media type of the asset (e.g. video, audio)." }, "date_created": { "type": "string", "nullable": true, "description": "UTC time the asset was created in iconik." }, "date_modified": { "type": "string", "nullable": true, "description": "UTC time the asset was last modified in iconik." }, "duration_ms": { "type": "number", "nullable": true, "description": "Asset duration in milliseconds, when iconik reports one." }, "ingested_rendition": { "type": "string", "enum": ["proxy", "original"], "nullable": true, "description": "Which rendition Cloudglue downloaded: the web proxy (preferred) or the ORIGINAL file." }, "iconik_url": { "type": "string", "nullable": true, "description": "Deep link to the asset page in iconik." }, "external_id": { "type": "string", "nullable": true, "description": "External reference id set on the asset in iconik." }, "created_by_user": { "type": "string", "nullable": true, "description": "iconik user id that created the asset." }, "iconik_metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Custom metadata-view field values from iconik (customer-defined schemas, e.g. a screening view's UGC Title / Keywords / Categories), captured verbatim keyed by field name. Indexed into metadata-collection search documents and filterable via source_metadata.iconik_metadata. paths." } }, "required": ["source_type", "iconik_asset_id"] }, "RunQueryRequest": { "type": "object", "required": ["collections"], "properties": { "collections": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 20, "description": "Collection IDs to query over. All collections must belong to your account; face-analysis collections are not supported." }, "sql": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "A single read-only SQL SELECT statement over the virtual tables (files, entities, segment_entities). Exactly one of sql or query must be provided." }, "query": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "A natural-language question to run instead of sql. Cloudglue compiles it to SQL against the same virtual schema, runs it, and returns the compiled statement in the response's sql field. Exactly one of sql or query must be provided. Costs 4 credits (refunded if compilation fails); returns 422 if it cannot be compiled." }, "format": { "type": "string", "enum": ["json", "csv", "jsonl"], "default": "json", "description": "Result format. 'json' returns rows inline (synchronous). 'csv' and 'jsonl' are for background exports only and require background: true." }, "max_rows": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1000, "description": "Maximum number of result rows to return inline. Results with more rows are truncated (truncated: true). Does not apply to background exports, which stream the full result." }, "background": { "type": "boolean", "default": false, "description": "When true, run the query as a background export: the full result streams to a gzipped csv/jsonl file and the response returns immediately with status 'in_progress' and an id to poll. Requires format 'csv' or 'jsonl'. Reserves 4 credits, reconciled to +1 per 100MB of compressed output. Cannot be combined with dry_run." }, "dry_run": { "type": "boolean", "default": false, "description": "When true, validate (and, for a natural-language query, compile) the statement and return the effective SQL plus its output column schema without executing it over any data. No rows are produced and it is billed at a reduced rate. Cannot be combined with background." } } }, "QueryUsage": { "type": "object", "properties": { "files_scanned": { "type": "integer", "description": "Number of files loaded into the files virtual table" }, "entity_rows": { "type": "integer", "description": "Number of rows loaded into the entities virtual table" }, "segment_entity_rows": { "type": "integer", "description": "Number of rows loaded into the segment_entities virtual table" }, "engine_ms": { "type": "number", "description": "SQL execution time in milliseconds" }, "total_ms": { "type": "number", "description": "Total processing time in milliseconds, including dataset preparation" } } }, "QueryResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Query result ID" }, "object": { "type": "string", "enum": ["query_result"], "description": "Object type identifier" }, "status": { "type": "string", "enum": ["completed", "failed", "in_progress", "cancelled"], "description": "Current status of the query. Synchronous queries return 'completed' or 'failed'." }, "created_at": { "type": "number", "description": "Unix timestamp of when the query was created" }, "collections": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Collection IDs the query ran over" }, "sql": { "type": "string", "nullable": true, "description": "The effective SQL that was executed (echoes the request's sql)" }, "columns": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "SQL type of the column" } } }, "description": "Result columns in select order" }, "rows": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "Result rows as objects keyed by column name" }, "row_count": { "type": "integer", "description": "Number of rows returned" }, "truncated": { "type": "boolean", "description": "Whether the result was truncated by max_rows or the stored-result size cap" }, "dry_run": { "type": "boolean", "description": "True when the query was only validated/compiled (dry_run request): columns holds the output schema and rows is null." }, "usage": { "nullable": true, "$ref": "#/components/schemas/QueryUsage", "description": "Dataset and timing usage for the run" }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "description": "Error details if the query failed" }, "format": { "type": "string", "nullable": true, "enum": ["json", "csv", "jsonl"], "description": "The result format ('csv'/'jsonl' for background exports)" }, "download_url": { "type": "string", "nullable": true, "description": "Signed URL to download a completed background export. Valid for 24 hours and not refreshed on read (re-run the export if it expires); null for synchronous runs and until a background export completes" }, "download_expires_at": { "type": "number", "nullable": true, "description": "Unix timestamp (ms) when download_url expires" }, "output_bytes": { "type": "integer", "nullable": true, "description": "Compressed size of a completed background export, in bytes" } } }, "QueryListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Query result ID" }, "object": { "type": "string", "enum": ["query_result"], "description": "Object type identifier" }, "status": { "type": "string", "enum": ["completed", "failed", "in_progress", "cancelled"], "description": "Current status" }, "created_at": { "type": "number", "description": "Unix timestamp of creation" }, "collections": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Collection IDs the query ran over" }, "sql": { "type": "string", "nullable": true, "description": "The effective SQL that was executed" }, "row_count": { "type": "integer", "description": "Number of rows returned" }, "truncated": { "type": "boolean", "description": "Whether the result was truncated" }, "usage": { "nullable": true, "$ref": "#/components/schemas/QueryUsage", "description": "Dataset and timing usage for the run" }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "description": "Error details if the query failed" } } }, "QueryListResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"], "description": "Object type identifier" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/QueryListItem" }, "description": "Array of query result items (without columns or rows)" }, "total": { "type": "integer", "description": "Total number of query results" }, "limit": { "type": "integer", "description": "Maximum number of items returned" }, "offset": { "type": "integer", "description": "Number of items skipped" } } }, "QuerySchemaTable": { "type": "object", "properties": { "name": { "type": "string", "description": "Virtual table name (files, entities, or segment_entities)" }, "description": { "type": "string", "description": "What the table contains and how to join it" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Column name" }, "type": { "type": "string", "description": "SQL column type" }, "description": { "type": "string", "description": "What the column contains" } } }, "description": "Columns of the virtual table" } } }, "QuerySchemaCollection": { "type": "object", "properties": { "collection_id": { "type": "string", "format": "uuid", "description": "Collection ID" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Entity field name from the collection's extract schema" }, "type": { "type": "string", "description": "Field value type from the extract schema (e.g. string, list)" }, "level": { "type": "string", "enum": ["file", "segment"], "description": "Where the field lives: 'file' fields appear as rows in the entities table; 'segment' fields live inside the segment_entities.entities JSON column" } } }, "description": "Flat summary of the collection's extracted fields" }, "extract_schema": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The collection's extract schema verbatim, showing nested value shapes. Null for collections without one (e.g. metadata collections, which are queried via the files table's metadata and source_metadata JSON columns)." }, "prompt": { "type": "string", "nullable": true, "description": "The collection's extraction prompt verbatim, if one was configured" } } }, "QuerySchema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["query_schema"], "description": "Object type identifier" }, "tables": { "type": "array", "items": { "$ref": "#/components/schemas/QuerySchemaTable" }, "description": "The virtual tables available to SQL queries" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/QuerySchemaCollection" }, "description": "Per-collection extracted field summaries and extract configs" } } }, "MetadataImportFilterSet": { "type": "object", "description": "One listing pass over the connector's source — the same query params as GET /data-connectors/{id}/files. Which keys a connector honors is validated at import creation (an unsupported key is rejected with a 400, never silently dropped): google-drive supports from/to/title_search/folder_id; dropbox from/to/title_search/path/recursive; zoom and gong from/to/title_search; grain from/to/title_search/team/meeting_type; recall from/to; iconik from/to/title_search. Zoom and Gong listings default to a 6-month lookback when no `from` is given; creation pins that date into the stored filters (six months before the set's `to` when one is given, else before creation time) so every run lists the same stable window — pass an explicit `from` to control the window yourself. iconik listings automatically window by date past iconik's 10,000-result search cap, so a single unfiltered set can cover any source size; only the degenerate case of 10,000+ assets sharing one creation timestamp still requires splitting into multiple date-window sets.", "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date", "description": "Only include source files from on/after this date (YYYY-MM-DD, UTC)" }, "to": { "type": "string", "format": "date", "description": "Only include source files from on/before this date (YYYY-MM-DD, UTC)" }, "folder_id": { "type": "string", "description": "Restrict listing to a folder's direct children (Google Drive only). Omit to list the entire corpus." }, "path": { "type": "string", "description": "Restrict listing to a folder path (Dropbox only). Dropbox listing is non-recursive: an import ingests only the direct children of this path (or of the root when omitted — typically all folders, i.e. nothing). Use one filter set per folder to cover a tree." }, "title_search": { "type": "string", "description": "Only include files whose title matches this search" }, "team": { "type": "string", "description": "Restrict to a team (Grain only)" }, "meeting_type": { "type": "string", "description": "Restrict to a meeting type (Grain only)" }, "recursive": { "type": "string", "enum": ["true", "false"], "description": "Dropbox only: 'true' imports the whole subtree under `path` (or the whole account when no `path` is given) instead of direct children." } } }, "MetadataImportRunProgress": { "type": "object", "description": "Best-effort progress counters for display. Run completion is decided from the actual per-file indexing state, never from these counters, so they can drift slightly under retries without affecting correctness.", "properties": { "pages_listed": { "type": "integer", "description": "Connector list pages fetched" }, "files_listed": { "type": "integer", "description": "Source files seen across all filter sets" }, "files_created": { "type": "integer", "description": "New Cloudglue files created" }, "files_updated": { "type": "integer", "description": "Existing files re-imported (refresh mode)" }, "files_skipped": { "type": "integer", "description": "Already-imported files left untouched (append mode)" }, "files_failed": { "type": "integer", "description": "Files whose metadata indexing failed" }, "files_queued": { "type": "integer", "description": "Files handed to indexing — the denominator for progress (indexed + failed settle against it)" }, "files_indexed": { "type": "integer", "description": "Files whose metadata finished indexing (metadata imports)" }, "files_imported": { "type": "integer", "description": "Files whose media was ingested and added to the collection (media imports)" }, "files_removed": { "type": "integer", "description": "Files removed by the delete-missing sweep" }, "files_enriched": { "type": "integer", "description": "Files whose source_metadata an enrichment batch backfilled (enrich_metadata runs only)." } } }, "MetadataImportRun": { "type": "object", "description": "One execution of a metadata import.", "properties": { "object": { "type": "string", "enum": ["metadata_import_run"] }, "id": { "type": "string", "format": "uuid" }, "import_id": { "type": "string", "format": "uuid" }, "import_type": { "type": "string", "enum": ["metadata", "media"], "description": "What this run ingests, inherited from the import definition: metadata indexes source metadata only (free); media ingests and processes the actual files (billed per file)." }, "mode": { "type": "string", "enum": ["append", "refresh"], "description": "append imports new files and retries previously-failed ones; refresh re-imports everything the filters match. For media imports, refresh re-syncs the source metadata of files it already imported — media bytes are never re-downloaded." }, "delete_missing": { "type": "boolean", "description": "Whether this run sweeps files this import previously brought in that the source no longer returns (refresh runs only)" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] }, "progress": { "$ref": "#/components/schemas/MetadataImportRunProgress" }, "error": { "type": "string", "nullable": true, "description": "User-facing failure reason when status is failed" }, "started_at": { "type": "number", "nullable": true, "description": "Unix timestamp in milliseconds" }, "completed_at": { "type": "number", "nullable": true, "description": "Unix timestamp in milliseconds" }, "created_at": { "type": "number", "description": "Unix timestamp in milliseconds" }, "max_files": { "type": "integer", "nullable": true, "description": "The cap this run executed with; null means unbounded" }, "include_thumbnails": { "type": "boolean", "description": "Whether this run copied poster thumbnails" }, "enrich_metadata": { "type": "boolean", "description": "Whether this run backfills omitted source-metadata fields (see the import-level property)." } } }, "MetadataImport": { "type": "object", "description": "A saved bulk import: which connector to list, how to filter it, and how runs behave. What a run ingests depends on the collection — see import_type. Definitions are immutable — delete and recreate to change one.", "properties": { "object": { "type": "string", "enum": ["metadata_import"] }, "id": { "type": "string", "format": "uuid" }, "collection_id": { "type": "string", "format": "uuid" }, "connector_id": { "type": "string", "format": "uuid" }, "import_type": { "type": "string", "enum": ["metadata", "media"], "description": "Inferred from the collection's type at creation and fixed for the import's lifetime. metadata (metadata collections): source metadata is indexed, no media is downloaded, runs are free. media (every other collection type): each matching file is ingested and processed exactly like a manual add, billed per file." }, "name": { "type": "string" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataImportFilterSet" }, "description": "Listing passes; an empty array means one unfiltered pass. Overlapping passes are deduplicated on import." }, "default_mode": { "type": "string", "enum": ["append", "refresh"], "description": "Mode used when a run does not specify one" }, "delete_missing": { "type": "boolean", "description": "Default delete-missing behavior for refresh runs" }, "rate_limit": { "type": "integer", "nullable": true, "description": "Upstream list requests per second; null means the per-connector safe default. Clamped to a per-connector ceiling at run time." }, "created_at": { "type": "number", "description": "Unix timestamp in milliseconds" }, "latest_run": { "allOf": [ { "$ref": "#/components/schemas/MetadataImportRun" } ], "nullable": true, "description": "Most recent run, or null when the import has never run" }, "max_files": { "type": "integer", "nullable": true, "description": "Per-run ceiling on files processed from the listing; null means unbounded" }, "include_thumbnails": { "type": "boolean", "description": "Whether runs copy connector poster images as default thumbnails for imported files (Grain and iconik today)" }, "enrich_metadata": { "type": "boolean", "description": "Backfill source-metadata fields the connector's list endpoint omits, after each index batch settles: Gong parties + Call Spotlight content (batched - enriched docs are re-embedded so the content is searchable) and Dropbox media_info duration/dimensions (per-file). No-op for other connectors. Off by default: it spends upstream API budget and, for Gong, embedding work. Metadata imports only — setting it on a media import is a 400, since a media run ingests each file in full and has no metadata-only record to enrich." } } }, "MetadataImportDetail": { "type": "object", "description": "An import with one page of its run history (newest first). total_runs/limit/offset make truncation visible.", "properties": { "object": { "type": "string", "enum": ["metadata_import"] }, "id": { "type": "string", "format": "uuid" }, "collection_id": { "type": "string", "format": "uuid" }, "connector_id": { "type": "string", "format": "uuid" }, "import_type": { "type": "string", "enum": ["metadata", "media"], "description": "Inferred from the collection's type at creation and fixed for the import's lifetime. metadata (metadata collections): source metadata is indexed, no media is downloaded, runs are free. media (every other collection type): each matching file is ingested and processed exactly like a manual add, billed per file." }, "name": { "type": "string" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataImportFilterSet" } }, "default_mode": { "type": "string", "enum": ["append", "refresh"] }, "delete_missing": { "type": "boolean" }, "rate_limit": { "type": "integer", "nullable": true, "description": "Upstream list requests per second; null means the per-connector safe default. Clamped to a per-connector ceiling at run time." }, "created_at": { "type": "number", "description": "Unix timestamp in milliseconds" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataImportRun" }, "description": "One page of run history, newest first" }, "total_runs": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "max_files": { "type": "integer", "nullable": true, "description": "Per-run ceiling on files processed from the listing; null means unbounded" }, "include_thumbnails": { "type": "boolean", "description": "Whether runs copy connector poster images as default thumbnails for imported files (Grain and iconik today)" }, "enrich_metadata": { "type": "boolean", "description": "Backfill source-metadata fields the connector's list endpoint omits, after each index batch settles: Gong parties + Call Spotlight content (batched - enriched docs are re-embedded so the content is searchable) and Dropbox media_info duration/dimensions (per-file). No-op for other connectors. Off by default: it spends upstream API budget and, for Gong, embedding work. Metadata imports only — setting it on a media import is a 400, since a media run ingests each file in full and has no metadata-only record to enrich." } } }, "MetadataImportList": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataImport" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "MetadataImportDelete": { "type": "object", "properties": { "object": { "type": "string", "enum": ["metadata_import"] }, "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "enum": [true] } } }, "CreateMetadataImportRequest": { "type": "object", "required": ["name", "connector_id"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name for the import" }, "connector_id": { "type": "string", "format": "uuid", "description": "Data connector to list files from. Supported types: google-drive, dropbox, zoom, gong, recall, grain, iconik." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataImportFilterSet" }, "maxItems": 20, "default": [], "description": "Listing passes; empty (the default) means one unfiltered pass" }, "default_mode": { "type": "string", "enum": ["append", "refresh"], "default": "append", "description": "Mode used when a run does not specify one. append imports new files and retries previously-failed ones; refresh re-imports everything the filters match." }, "delete_missing": { "type": "boolean", "default": false, "description": "On refresh runs, remove files this import previously brought in that the source no longer returns. Only files imported by this import are ever removed — manually-added files and other imports are untouched." }, "rate_limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Upstream list requests per second. Defaults to a per-connector safe rate (e.g. gong 2, zoom 6, google-drive/dropbox 8) and is clamped to a per-connector ceiling (gong 3, iconik 12, zoom/grain/recall 10, google-drive/dropbox 20) sized to keep the whole account inside each provider's published rate budget." }, "start": { "type": "boolean", "default": true, "description": "Trigger the first run immediately. false saves the definition only." }, "max_files": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Stop each run after processing this many files from the listing. A capped run stops listing at the limit and never runs the delete-missing sweep — a truncated listing is incomplete by definition, so nothing is removed based on it. Media imports additionally cap every run at 10,000 files, whatever this is set to." }, "include_thumbnails": { "type": "boolean", "default": false, "description": "Copy connector poster images as default thumbnails for imported files, for sources that provide one (Grain, iconik, Google Drive, and Dropbox today). Off by default. Posters are copied in the background, so they do not slow the import itself and may appear shortly after a file is indexed. Metadata imports only — setting it on a media import is a 400, since imported media gets real thumbnails from the processing pipeline." }, "enrich_metadata": { "type": "boolean", "description": "Backfill source-metadata fields the connector's list endpoint omits, after each index batch settles: Gong parties + Call Spotlight content (batched - enriched docs are re-embedded so the content is searchable) and Dropbox media_info duration/dimensions (per-file). No-op for other connectors. Off by default: it spends upstream API budget and, for Gong, embedding work. Metadata imports only — setting it on a media import is a 400, since a media run ingests each file in full and has no metadata-only record to enrich.", "default": false } } }, "CreateMetadataImportRunRequest": { "type": "object", "description": "All fields default to the values saved on the import definition.", "properties": { "mode": { "type": "string", "enum": ["append", "refresh"] }, "delete_missing": { "type": "boolean" }, "max_files": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Override the definition's max_files for this run" }, "include_thumbnails": { "type": "boolean", "description": "Override the definition's include_thumbnails for this run. Metadata imports only — setting it on a media import is a 400." }, "enrich_metadata": { "type": "boolean", "description": "Override the definition default for this run." } } }, "MomentCriterion": { "type": "object", "description": "An inline criterion: rubric instructions plus typed output declarations. Snapshotted and hashed onto the run.", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "instructions": { "type": "string", "minLength": 1, "description": "The complete rubric, including any seed lists and worked examples." }, "moment_schema": { "$ref": "#/components/schemas/MomentSchemaDefinition" }, "finding_schema": { "$ref": "#/components/schemas/MomentSchemaDefinition" }, "anchors": { "type": "object", "description": "Named intra-moment timestamps. A non-required anchor that does not exist is omitted from the moment - never null.", "additionalProperties": { "type": "object", "properties": { "required": { "type": "boolean" }, "description": { "type": "string" } } } }, "scoring": { "type": "object", "description": "The rubric's single canonical score: what rank-ordered reads sort by and what min_score filters on. Exactly one scoring key per criterion.", "properties": { "key": { "type": "string" }, "min": { "type": "number" }, "max": { "type": "number" }, "higher_is_better": { "type": "boolean" }, "description": { "type": "string" } }, "required": ["key", "min", "max"] } }, "required": ["name", "instructions"] }, "MomentSchemaDefinition": { "type": "object", "description": "A validated JSON Schema subset (the moment schema dialect): a root object of string/number/integer/boolean/array-of-those fields, optional enums, one nesting level, per-field descriptions. Rejected shapes get a field-addressable 400 with a stable code." }, "NewFindMoments": { "type": "object", "properties": { "url": { "type": "string", "description": "cloudglue://files/ or an ingestible URL (same resolution rules as describe/extract)." }, "describe_job_id": { "type": "string", "format": "uuid", "description": "Optional pin to a specific describe. It must exist for the file and its config must cover signals_required." }, "criterion": { "$ref": "#/components/schemas/MomentCriterion" }, "signals_required": { "type": "array", "minItems": 1, "default": ["speech"], "items": { "type": "string", "enum": [ "speech", "visual_scene_description", "scene_text", "audio_description" ] } }, "boundary_policy": { "type": "string", "enum": ["sentence", "tight", "loose"], "default": "sentence" }, "speaker_filter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } }, "match": { "type": "string", "enum": ["any", "all"] } } }, "min_duration_seconds": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 5 }, "max_duration_seconds": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 300 }, "cache_policy": { "type": "string", "enum": ["reuse", "refresh"], "default": "reuse" } }, "required": ["url", "criterion"], "additionalProperties": false }, "FindMoments": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds when the run was created" }, "url": { "type": "string" }, "find_moments_config": { "type": "object", "description": "Echo of the request as the run resolved it, plus criterion_hash, the resolved describe_job_id, and the engine version. Defaults the request omitted are filled in here.", "properties": { "criterion": { "$ref": "#/components/schemas/MomentCriterion" }, "criterion_hash": { "type": "string", "description": "Stable hash of the snapshotted criterion; identical criteria share a hash." }, "describe_job_id": { "type": "string", "format": "uuid", "description": "The describe the run actually used, whether reused, pinned, or created internally." }, "signals_required": { "type": "array", "items": { "type": "string" } }, "boundary_policy": { "type": "string", "enum": ["sentence", "tight", "loose"] }, "speaker_filter": { "type": "object", "description": "Speaker restriction, present when the request set one." }, "min_duration_seconds": { "type": "number" }, "max_duration_seconds": { "type": "number" }, "cache_policy": { "type": "string", "enum": ["reuse", "refresh"] }, "engine_version": { "type": "integer", "description": "Version of the moment-discovery engine that produced the run." } } }, "moments": { "type": "array", "items": { "$ref": "#/components/schemas/Moment" } }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/MomentFinding" } }, "total_moments": { "type": "integer", "description": "Full accepted count, independent of the limit read parameter." }, "error": { "type": "string", "description": "Curated failure message, present on failed runs." } }, "required": ["job_id", "status", "created_at", "url"] }, "FindMomentsList": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/FindMoments" } }, "total": { "type": "integer" }, "next_cursor": { "type": "string", "description": "Present when more runs exist; pass as the cursor parameter." } }, "required": ["runs", "total"] }, "Moment": { "type": "object", "properties": { "moment_id": { "type": "string", "format": "uuid" }, "start_time": { "type": "number", "description": "Seconds from source start." }, "end_time": { "type": "number" }, "anchors": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Declared anchors only; an anchor that was not found is absent, never null." }, "title": { "type": "string" }, "reason": { "type": "string" }, "speakers": { "type": "array", "items": { "type": "string" } }, "criterion_score": { "$ref": "#/components/schemas/CriterionScore" }, "rank_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized ordering within the run; what the default sort uses." }, "properties": { "type": "object", "description": "Validates against the criterion's moment_schema." }, "evidence": { "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "moment_id", "start_time", "end_time", "title", "reason", "rank_score" ] }, "CriterionScore": { "type": "object", "description": "The rubric's judgment on its own declared scale.", "properties": { "key": { "type": "string" }, "value": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": ["key", "value", "min", "max"] }, "MomentFinding": { "type": "object", "description": "A non-temporal finding, produced whenever the criterion declares a finding_schema.", "properties": { "finding_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": ["absence", "observation"] }, "properties": { "type": "object", "description": "Validates against the criterion's finding_schema." } }, "required": ["finding_id", "kind", "properties"] }, "DeleteFindMomentsResult": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" }, "refunded": { "type": "boolean", "description": "True when the run was in flight and its charge was refunded." } }, "required": ["job_id", "deleted", "refunded"] }, "MomentsConfig": { "type": "object", "description": "Moments collections: the criteria to run over every current and future member. Each entry becomes a criterion attachment; the attachment rows are the operational source of truth after creation.", "properties": { "criteria": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/NewMomentCriterionAttachment" } } }, "required": ["criteria"] }, "NewMomentCriterionAttachment": { "type": "object", "properties": { "criterion": { "$ref": "#/components/schemas/MomentCriterion" }, "signals_required": { "type": "array", "minItems": 1, "default": ["speech"], "items": { "type": "string", "enum": [ "speech", "visual_scene_description", "scene_text", "audio_description" ] } }, "boundary_policy": { "type": "string", "enum": ["sentence", "tight", "loose"], "default": "sentence" }, "speaker_filter": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } }, "match": { "type": "string", "enum": ["any", "all"] } } }, "min_duration_seconds": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 5 }, "max_duration_seconds": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 300 } }, "required": ["criterion"], "additionalProperties": false }, "MomentCriterionAttachment": { "type": "object", "properties": { "attachment_id": { "type": "string", "format": "uuid" }, "criterion_name": { "type": "string" }, "criterion_hash": { "type": "string" }, "criterion": { "$ref": "#/components/schemas/MomentCriterion" }, "options": { "type": "object", "description": "The per-attachment run knobs, as supplied on NewMomentCriterionAttachment.", "properties": { "signals_required": { "type": "array", "items": { "type": "string" } }, "boundary_policy": { "type": "string", "enum": ["sentence", "tight", "loose"] }, "speaker_filter": { "type": "object" }, "min_duration_seconds": { "type": "number" }, "max_duration_seconds": { "type": "number" } } }, "backfill_status": { "type": "string", "enum": [ "pending", "processing", "completed", "completed_with_failures" ] }, "files_total": { "type": "integer" }, "files_completed": { "type": "integer" }, "files_failed": { "type": "integer" }, "created_at": { "type": "integer", "description": "Unix timestamp in milliseconds" } }, "required": [ "attachment_id", "criterion_name", "criterion_hash", "backfill_status" ] }, "CollectionMomentsList": { "type": "object", "properties": { "moments": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Moment" }, { "type": "object", "properties": { "file_id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "criterion_name": { "type": "string" } }, "required": ["file_id", "job_id", "criterion_name"] } ] } }, "total": { "type": "integer", "description": "Exact total across current members." }, "next_cursor": { "type": "string" } }, "required": ["moments", "total"] }, "CollectionMomentFindingsList": { "type": "object", "properties": { "findings": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/MomentFinding" }, { "type": "object", "properties": { "file_id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "criterion_name": { "type": "string" } }, "required": ["file_id", "job_id", "criterion_name"] } ] } }, "total": { "type": "integer" }, "next_cursor": { "type": "string" } }, "required": ["findings", "total"] }, "SiteRoutePreviewInput": { "type": "object", "required": ["route", "previewShareId"], "properties": { "route": { "type": "string", "maxLength": 512, "description": "The site route this preview applies to. Stored and matched in canonical form: hash-router prefixes ('#/'), query strings, and surrounding slashes are stripped, so '/clip/intro', 'clip/intro/', and '#/clip/intro' all name the same route. Must not be empty after canonicalization — the site root unfurls with the site-level preview fields.", "example": "clip/intro-to-x" }, "previewTitle": { "type": "string", "description": "Preview card title. Falls back to the hero share's own title (then its filename) when unset." }, "previewDescription": { "type": "string", "maxLength": 1000, "description": "Preview card description. Falls back to the hero share's own description when unset. Slack truncates at 200 characters." }, "previewImageUrl": { "type": "string", "format": "uri", "description": "Preview card image. Must be a publicly fetchable URL (e.g. a share's preview_url) — site asset URLs sit behind the private-site gate and won't render. Falls back to the hero share's thumbnail when unset." }, "previewShareId": { "type": "string", "format": "uuid", "description": "The route's hero share: what a link to this page plays when unfurled by the Cloudglue Slack app. Must be a video share owned by the same account; on a public site it must be a public share." }, "startSeconds": { "type": "number", "minimum": 0, "description": "Clip window start, in seconds (fractional allowed). Requires endSeconds; the unfurled player then plays only the [startSeconds, endSeconds] window of the hero share. Precision note: the stream is trimmed with Mux instant clipping, which cuts at the asset's HLS segment boundaries (start rounds down, end rounds up) — not frame-accurate, so the served clip can include a few extra seconds on either side depending on the asset's segment length." }, "endSeconds": { "type": "number", "description": "Clip window end, in seconds (fractional allowed). Requires startSeconds and must be greater than it. Served at HLS segment granularity — see startSeconds." } } }, "SiteRoutePreview": { "type": "object", "required": ["id", "route", "previewShareId", "createdAt", "updatedAt"], "properties": { "id": { "type": "string", "format": "uuid" }, "route": { "type": "string", "maxLength": 512, "description": "The site route this preview applies to. Stored and matched in canonical form: hash-router prefixes ('#/'), query strings, and surrounding slashes are stripped, so '/clip/intro', 'clip/intro/', and '#/clip/intro' all name the same route. Must not be empty after canonicalization — the site root unfurls with the site-level preview fields.", "example": "clip/intro-to-x" }, "previewTitle": { "type": "string", "description": "Preview card title. Falls back to the hero share's own title (then its filename) when unset.", "nullable": true }, "previewDescription": { "type": "string", "maxLength": 1000, "description": "Preview card description. Falls back to the hero share's own description when unset. Slack truncates at 200 characters.", "nullable": true }, "previewImageUrl": { "type": "string", "format": "uri", "description": "Preview card image. Must be a publicly fetchable URL (e.g. a share's preview_url) — site asset URLs sit behind the private-site gate and won't render. Falls back to the hero share's thumbnail when unset.", "nullable": true }, "previewShareId": { "type": "string", "format": "uuid", "description": "The route's hero share: what a link to this page plays when unfurled by the Cloudglue Slack app. Must be a video share owned by the same account; on a public site it must be a public share." }, "startSeconds": { "type": "number", "minimum": 0, "description": "Clip window start, in seconds (fractional allowed). Requires endSeconds; the unfurled player then plays only the [startSeconds, endSeconds] window of the hero share. Precision note: the stream is trimmed with Mux instant clipping, which cuts at the asset's HLS segment boundaries (start rounds down, end rounds up) — not frame-accurate, so the served clip can include a few extra seconds on either side depending on the asset's segment length.", "nullable": true }, "endSeconds": { "type": "number", "description": "Clip window end, in seconds (fractional allowed). Requires startSeconds and must be greater than it. Served at HLS segment granularity — see startSeconds.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SiteRoutePreviewList": { "type": "object", "required": ["previews"], "properties": { "previews": { "type": "array", "items": { "$ref": "#/components/schemas/SiteRoutePreview" } } } }, "ReplaceSiteRoutePreviewsRequest": { "type": "object", "required": ["previews"], "properties": { "previews": { "type": "array", "maxItems": 20000, "description": "The site's complete set of route previews. Replaces whatever was stored before — routes omitted here lose their preview (and fall back to the site-level hero). An empty array clears all route previews.", "items": { "$ref": "#/components/schemas/SiteRoutePreviewInput" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }