> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt > Use this file to discover all available pages before exploring further. # Add YouTube Video to Collection > Add a YouTube video to a collection by URL ## OpenAPI ````yaml POST /collections/{collection_id}/youtube 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.8 servers: - url: https://api.cloudglue.dev/v1 security: - bearerAuth: [] paths: /collections/{collection_id}/youtube: post: tags: - Collections summary: Add a YouTube video to a collection description: Add a YouTube video to a collection by URL operationId: addYouTubeVideo 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' deprecated: true components: schemas: AddYouTubeCollectionFile: allOf: - type: object properties: url: type: string description: >- The URL of the YouTube video to add to the collection. Note 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 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 Error: required: - error type: object properties: error: type: string 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. 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: Video width in pixels (null for audio files) height: type: integer nullable: true description: Video 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 both video and audio 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 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 SegmentationConfig: type: object description: >- Configuration for video segmentation. **Choose a strategy and provide ONLY the corresponding config:** • **uniform**: Provide `uniform_config`, do NOT provide other configs • **shot-detector**: Provide `shot_detector_config`, do NOT provide other configs • **manual**: Provide `manual_config`, do NOT provide other configs • **narrative**: Provide `narrative_config`, do NOT provide other configs Optionally 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' SourceMetadata: oneOf: - $ref: '#/components/schemas/GrainSourceMetadata' discriminator: propertyName: source_type mapping: grain: $ref: '#/components/schemas/GrainSourceMetadata' description: >- Per-source provenance captured from the upstream connector. Currently only Grain is populated. 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: • **content**: Sensitivity to visual differences (default: 27.0). Lower values detect smaller changes in color/lighting. • **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: • **adaptive**: Designed for dynamic footage with camera movement, panning, or action. Examples: sports broadcasts, drone footage, handheld documentaries, action movies, live events. • **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. 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 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: • **comprehensive**: Uses a VLM to deeply analyze logical segments of video. Only available for video files (not YouTube or audio). • **balanced** (default): Balanced analysis approach using multiple modalities. Supports YouTube URLs and audio files. • **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). **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. 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 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. start_datetime: type: string format: date-time description: UTC time Grain started the recording. end_datetime: type: string format: date-time description: UTC time the recording ended. duration_ms: type: integer description: Recording duration in milliseconds. media_type: type: string enum: - audio - transcript - video description: Grain media type of the recording. upstream_source: type: string enum: - aircall - local_capture - meet - teams - upload - webex - zoom - other description: Platform Grain captured the recording from. grain_url: type: string description: URL to the recording in Grain. thumbnail_url: type: string nullable: true description: Thumbnail URL, null if none. tags: type: array items: type: string description: Tags applied to the recording. teams: type: array items: type: object properties: id: type: string name: type: string description: Teams the recording belongs to. 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 - title - start_datetime - end_datetime - duration_ms - media_type - upstream_source - grain_url - tags - teams securitySchemes: bearerAuth: type: http scheme: bearer ````