--- title: "Sync a data connector URI into a file" method: POST path: "/data-connectors/{id}/sync" tags: ["Data Connectors"] --- # Sync a data connector URI into a file `POST /data-connectors/{id}/sync` ## Request - Base URL: `https://api.cloudglue.dev/v1` - URL: `https://api.cloudglue.dev/v1/data-connectors/{id}/sync` - Auth: HTTP bearer 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. ## Path parameters - `id` string, uuid, required ## Request body - object - `url` string, required: 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/`. ## Response `200` The synced file - File - `id` string, required: Unique identifier for the file - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'not_applicable', required: Processing status of the file - `bytes` integer, nullable: Size of the file in bytes, null if not available - `created_at` integer: Unix timestamp in milliseconds when the file was created - `filename` string: Original filename - `uri` string, required: Cloudglue URI for the file, to be used in other API calls - `metadata` object, nullable: User-provided metadata about the file, null if none provided - `media_type` 'video' | 'audio' | 'image': Type of media file (video, audio, or image). Images are processed at the file level only (no segmentation). - `media_info` object: Unified media information for video, audio, and image files - `duration_seconds` number, nullable: Duration in seconds - `width` integer, nullable: Width in pixels (null for audio files) - `height` integer, nullable: Height in pixels (null for audio files) - `sample_rate` integer, nullable: Audio sample rate in Hz - `channels` integer, nullable: Number of audio channels - `bitrate` integer, nullable: Audio bitrate in bps - `format` string, nullable: File format - `has_audio` boolean, nullable: Whether the file has audio - `video_info` object: Information about the video content - `duration_seconds` number, nullable: Duration of the video in seconds, null if not available - `height` integer, nullable: Height of the video in pixels, null if not available - `width` integer, nullable: Width of the video in pixels, null if not available - `format` string, nullable: Format of the video file, null if not available - `has_audio` boolean, nullable: Whether the video has audio, null if not available - `thumbnail_url` string: URL of the thumbnail for the file - `source` 'video' | 'youtube' | 's3' | 'dropbox' | 'http' | 'upload' | 'google-drive' | 'zoom' | 'gong' | 'recall' | 'gcs' | 'grain' | 'loom' | 'iconik': Source of the file - `source_metadata` union: 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). - GrainSourceMetadata: Source provenance captured from Grain at ingest time. The richer AI/contextual fields are only present when Grain returns them. - `source_type` 'grain', required: Discriminator identifying the upstream connector. - `grain_recording_id` string, required: Grain's recording id. - `title` string, nullable: Recording title. - `start_datetime` string, date-time, nullable: UTC time Grain started the recording. - `end_datetime` string, date-time, nullable: UTC time the recording ended. - `duration_ms` integer, nullable: Recording duration in milliseconds. - `media_type` 'audio' | 'transcript' | 'video', nullable: Grain media type of the recording. - `upstream_source` 'aircall' | 'local_capture' | 'meet' | 'teams' | 'upload' | 'webex' | 'zoom' | 'other', nullable: Platform Grain captured the recording from. - `grain_url` string, nullable: URL to the recording in Grain. - `thumbnail_url` string, nullable: Thumbnail URL, null if none. - `tags` string[], nullable: Tags applied to the recording. - `teams` object[], nullable: Teams the recording belongs to. - `id` string - `name` string - `meeting_type` object, nullable: Recording's meeting type, null if none. - `id` string - `name` string - `scope` string - `participants` object[], nullable: Meeting participants (include-gated by Grain). Null when requested but empty. - `id` string - `name` string - `email` string, nullable - `scope` 'internal' | 'external' | 'unknown' - `confirmed_attendee` boolean - `hs_contact_id` string, nullable: HubSpot contact id, if linked. - `highlights` object[], nullable: Clips / highlights (include-gated). Null when requested but empty. - `ai_summary` object, nullable: AI summary (include-gated). Null when requested but empty. - `text` string: Markdown AI summary. - `ai_action_items` object[], nullable: AI action items (include-gated). Null when requested but empty. - `status` 'pending' | 'completed' - `timestamp_ms` integer: Time in the recording the item was mentioned. - `text` string - `assignee` object, nullable - `id` string - `name` string - `user_id` string, nullable - `ai_template_sections` object[], nullable: AI template sections, shape varies by template (include-gated). Null when requested but empty. - `calendar_event` object, nullable: Related calendar event (include-gated). - `ical_uid` string - `hubspot` object, nullable: Related HubSpot company/deal ids (include-gated). Null when requested but empty. - `hubspot_company_ids` string[] - `hubspot_deal_ids` string[] - ZoomSourceMetadata: Source provenance captured from Zoom at ingest time. Signed download/play URLs, share URLs, and passcodes are never included. - `source_type` 'zoom', required: Discriminator identifying the upstream connector. - `zoom_meeting_uuid` string, required: Zoom meeting instance UUID. - `zoom_meeting_id` integer, nullable: Zoom numeric meeting id. - `topic` string, nullable: Meeting topic (empty string when Zoom omits it). - `start_time` string, date-time, nullable: UTC time the meeting started. - `host_id` string, nullable: Zoom host user id. - `host_email` string, nullable: Host email. Nullable whenever Zoom omits it — both list and per-meeting endpoints may return null depending on account scopes. - `account_id` string, nullable: Zoom account id. - `timezone` string, nullable: Meeting timezone. - `duration_minutes` number, nullable: Meeting duration in minutes (as reported by Zoom). - `total_size` number, nullable: Total size of all recording files in bytes. - `recording_count` number, nullable: Number of recording files for the meeting. - `meeting_type` number, nullable: Zoom's numeric meeting type. - `recording_files` object[], nullable: Structural facts about each recording file. Download/play URLs are excluded. - `id` string, nullable - `recording_type` string, nullable: e.g. shared_screen_with_speaker_view, audio_only. - `file_type` string, nullable - `file_extension` string, nullable - `file_size` number, nullable: File size in bytes. - `recording_start` string, nullable - `recording_end` string, nullable - `status` string, nullable - RecallSourceMetadata: Source provenance captured from Recall at ingest time. Artifact availability is exposed as booleans — signed artifact download URLs are never included. - `source_type` 'recall', required: Discriminator identifying the upstream connector. - `recall_recording_id` string, required: Recall recording id. - `created_at` string, nullable: UTC time the recording object was created. - `started_at` string, nullable: UTC time recording started. - `completed_at` string, nullable: UTC time recording completed. - `expires_at` string, nullable: UTC time the recording expires upstream at Recall. - `status_code` string, nullable: Recall status: done, processing, failed, or paused. Only done recordings can be synced. - `meeting_title` string, nullable: Meeting title, when Recall's meeting metadata carries one. - `meeting_platform` string, nullable: Meeting platform (e.g. zoom, google_meet), when available. - `has_transcript` boolean, nullable: Whether a transcript artifact exists. - `has_audio` boolean, nullable: Whether a separate audio artifact exists. - `has_participant_events` boolean, nullable: Whether a participant-events artifact exists. - `bot_id` string, nullable: Id of the bot that captured the recording. - `recall_metadata` object, nullable: Arbitrary caller-supplied metadata attached to the bot/recording in Recall. - GoogleDriveSourceMetadata: Source provenance captured from Google Drive at ingest time. Short-lived signed URLs (e.g. thumbnailLink) are never included. - `source_type` 'google-drive', required: Discriminator identifying the upstream connector. - `gdrive_file_id` string, required: Drive file id. - `name` string, nullable: File name. - `mime_type` string, nullable - `size_bytes` number, nullable - `created_time` string, nullable: UTC time the file was created in Drive. - `modified_time` string, nullable: UTC time the file was last modified. - `web_view_link` string, nullable: Link to view the file in Drive (requires Drive access). - `owners` object[], nullable: File owners. - `display_name` string, nullable - `email_address` string, nullable - `last_modifying_user` object, nullable: User who last modified the file. - `display_name` string, nullable - `email_address` string, nullable - `parents` string[], nullable: Parent folder ids. - `shared` boolean, nullable: Whether the file is shared. - `file_extension` string, nullable - `md5_checksum` string, nullable - `video_media_metadata` object, nullable: Drive's video metadata, when Drive has processed the file. - `duration_millis` number, nullable: Video duration in milliseconds. - `width` number, nullable - `height` number, nullable - DropboxSourceMetadata: Source provenance captured from Dropbox at ingest time. - `source_type` 'dropbox', required: Discriminator identifying the upstream connector. - `dropbox_id` string, required: Dropbox file id (id:… form). - `name` string, nullable: File name. - `path_lower` string, nullable: Lowercased path of the file. - `path_display` string, nullable: Display-cased path. - `size_bytes` number, nullable - `client_modified` string, nullable: Modification time reported by the client that uploaded the file. - `server_modified` string, nullable: Time the file was last modified on Dropbox. - `rev` string, nullable: Dropbox revision id. - `content_hash` string, nullable: Dropbox content hash. - `is_downloadable` boolean, nullable - `media_info` object, nullable: 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. - `duration_ms` number, nullable: Media duration in milliseconds. - `width` number, nullable - `height` number, nullable - GongSourceMetadata: 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. - `source_type` 'gong', required: Discriminator identifying the upstream connector. - `gong_call_id` string, required: Gong call id. - `title` string, nullable: Call title (empty string when Gong omits it). - `started` string, nullable: UTC time the call started. - `scheduled` string, nullable: UTC time the call was scheduled for. - `duration` number, nullable: Call duration in seconds. - `gong_url` string, nullable: URL to the call in Gong. - `meeting_url` string, nullable: URL of the underlying meeting. - `is_private` boolean, nullable: Whether the call is private in Gong. Private calls cannot be listed or synced. - `purpose` string, nullable - `primary_user_id` string, nullable: Gong user id of the call owner. - `direction` string, nullable: Inbound, Outbound, Conference, or Unknown. - `system` string, nullable: Telephony/meeting system the call was held on. - `scope` string, nullable: Internal, External, or Unknown. - `language` string, nullable: ISO-639-2B language code Gong detected. - `workspace_id` string, nullable: Gong workspace id. - `call_media_type` string, nullable: Gong's media indicator: Video or Audio. - `parties` object[], nullable: Call participants. - `id` string, nullable - `name` string, nullable - `email` string, nullable - `affiliation` string, nullable: Internal, External, or Unknown. - `speaker_id` string, nullable - `user_id` string, nullable - `topics` object[], nullable: AI topics (Call Spotlight). - `name` string, nullable - `duration` number, nullable: Seconds spent on the topic. - `trackers` object[], nullable: Tracker keyword hit counts (Call Spotlight). - `name` string, nullable - `count` number, nullable - `brief` string, nullable: AI call brief (Call Spotlight). - `key_points` string[], nullable: AI key points (Call Spotlight). - IconikSourceMetadata: Source provenance captured from iconik at ingest time. Signed download URLs are never included. - `source_type` 'iconik', required: Discriminator identifying the upstream connector. - `iconik_asset_id` string, required: iconik asset id. - `title` string, nullable: Asset title. - `media_type` string, nullable: iconik media type of the asset (e.g. video, audio). - `date_created` string, nullable: UTC time the asset was created in iconik. - `date_modified` string, nullable: UTC time the asset was last modified in iconik. - `duration_ms` number, nullable: Asset duration in milliseconds, when iconik reports one. - `ingested_rendition` 'proxy' | 'original', nullable: Which rendition Cloudglue downloaded: the web proxy (preferred) or the ORIGINAL file. - `iconik_url` string, nullable: Deep link to the asset page in iconik. - `external_id` string, nullable: External reference id set on the asset in iconik. - `created_by_user` string, nullable: iconik user id that created the asset. - `iconik_metadata` object, nullable: 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. ## Other responses - `400`: Bad request (e.g. URL source does not match the connector type, or the link points to a folder) - `403`: 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` - `404`: Data connector not found, or the referenced file/recording was not found at the source - `429`: The external service rate-limited the request (e.g. Dropbox or Zoom); retry shortly - `500`: An unexpected error occurred on the server - `502`: Error communicating with the external service ## Changes - **2026-10-30** `23d3f240819f`: 6 info - added the optional property `code` to the response with the `400` status - added the optional property `code` to the response with the `403` status - added the optional property `code` to the response with the `404` status - added the optional property `code` to the response with the `429` status - …2 more - **2026-07-22** `c02e52ec2e28`: 1 breaking, 1 warning, 1 info - added `#/components/schemas/IconikSourceMetadata` to the `source_metadata/allOf[#/components/schemas/SourceMetadata]/` response property `oneOf` list for the response status `200` - added the new `iconik` enum value to the `source` response property for the response status `200` - added `iconik` discriminator mapping keys to the `source_metadata/allOf[#/components/schemas/SourceMetadata]/` response property for the response status `200` - …earlier changes not shown [Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/data-connectors/:id/sync/post.md) --- [API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)