{"info":{"version":"1.0.0","description":"REST API for managing videos, livestreams, products, channels and playlists. Authenticate with an OAuth 2.0 bearer token obtained from POST /oauth/token; each operation lists the token scope it requires. Resource IDs are strings.","title":"Firework API"},"components":{"schemas":{"ImageMetadata":{"type":"object","properties":{"alt_text":{"type":"string","nullable":true}}},"LiveStreamList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"live_streams":{"type":"array","items":{"$ref":"#/components/schemas/LiveStreamListItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"ImageDownload":{"type":"object","required":["download_url"],"properties":{"format":{"type":"string","description":"Format of the file at download_url (the requested format when converting)","nullable":true},"width":{"type":"integer","nullable":true},"file_size":{"type":"integer","description":"Size of the original in bytes; null when a resized or converted rendition is returned","nullable":true},"download_url":{"type":"string","description":"CDN URL of the original, a resized rendition (when max_dimension is given), a format-converted rendition (when format is given), or both","nullable":true},"height":{"type":"integer","nullable":true}}},"MultipartSignature":{"type":"object","properties":{"key":{"type":"string"},"parts":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"signature":{"description":"Pre-signed upload data for this part"}}}},"upload_id":{"type":"string"}}},"AiCurationSettingsUpdateParams":{"type":"object","description":"Any subset of the settings. Array fields replace the stored value wholesale.","properties":{"score_threshold":{"type":"number"},"tiktok_hashtags":{"type":"array","items":{"type":"string"}},"instagram_hashtags":{"type":"array","items":{"type":"string"}},"tiktok_mentioned_usernames":{"type":"array","items":{"type":"string"}},"instagram_mentioned_usernames":{"type":"array","items":{"type":"string"}},"brand_description":{"type":"string"}}},"ChannelUpdateParams":{"type":"object","description":"Only the provided fields are updated.","properties":{"name":{"type":"string"},"locale":{"type":"string"},"country":{"type":"string","description":"2-letter country code"},"avatar_key":{"type":"string","description":"S3 key of the channel avatar"},"bio":{"type":"string","nullable":true},"cover_key":{"type":"string","description":"S3 key of the channel cover image"}}},"Playlist":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"updated_at":{"type":"string","format":"date-time"},"video_ids":{"type":"array","items":{"type":"string","description":"video ID"}}}},"AiCurationConnectUrlParams":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string","enum":["tiktok","facebook"],"description":"Social platform to connect (Instagram connects via facebook)"},"redirect_back_uri":{"type":"string","description":"Where the browser lands after the OAuth flow completes; defaults to the business portal's callback."}}},"VideoProductMatchCreateParams":{"type":"object","properties":{"auto_accept":{"default":false,"type":"boolean","description":"Accept every match automatically when the matching completes, attaching the products to the video."}}},"VideoPromotion":{"type":"object","description":"A promotion attached to the livestream's video, including scheduled and expired promotions.","required":["id","video_id","product_id","type","starts_at","ends_at","payload","status","inserted_at","updated_at"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["scheduled","active","expired"],"description":"Calculated at response time: expired at or after ends_at; otherwise scheduled before starts_at; otherwise active. Missing bounds are open-ended."},"type":{"type":"string","enum":["product","generic","announcement"]},"video_id":{"type":"string"},"payload":{"$ref":"#/components/schemas/VideoPromotionPayload"},"updated_at":{"type":"string","format":"date-time"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"inserted_at":{"type":"string","format":"date-time"},"product_id":{"type":"string","nullable":true}}},"LiveStreamProduct":{"type":"object","required":["product","selected_product_unit_ids","deals"],"properties":{"product":{"$ref":"#/components/schemas/Product"},"selected_product_unit_ids":{"type":"array","items":{"type":"string","description":"selected product unit ID"}},"deals":{"type":"array","items":{"$ref":"#/components/schemas/LiveStreamProductDeal"}}}},"AiCurationSettings":{"type":"object","properties":{"last_synced_at":{"type":"string","format":"date-time","nullable":true},"score_threshold":{"type":"number","description":"Minimum curation score for feed items","nullable":true},"tiktok_hashtags":{"type":"array","items":{"type":"string"}},"instagram_hashtags":{"type":"array","items":{"type":"string"}},"tiktok_mentioned_usernames":{"type":"array","items":{"type":"string"}},"instagram_mentioned_usernames":{"type":"array","items":{"type":"string"}},"brand_description":{"type":"string","nullable":true},"connected_accounts":{"type":"array","items":{"$ref":"#/components/schemas/AiCurationSocialAccount"}}}},"ImageProducts":{"type":"object","description":"An image's product listings, ordered by product_sort_position.","required":["products"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ImageProductListing"}}}},"AiCurationCreator":{"type":"object","properties":{"id":{"type":"integer","description":"Whitelist entry id (a curation-engine id, not a SecretId)"},"expires_at":{"type":"string","format":"date-time","nullable":true},"username":{"type":"string"},"updated_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"platform":{"type":"string","enum":["tiktok","instagram"]},"creator_name":{"type":"string","nullable":true}}},"VideoPoster":{"type":"object","properties":{"id":{"type":"string","description":"poster ID (pass to DELETE .../posters/{poster_id})"},"format":{"type":"string"},"width":{"type":"integer"},"source":{"type":"string","nullable":true},"url":{"type":"string"},"weight":{"type":"number","nullable":true},"height":{"type":"integer"},"aspect_ratio":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"video_poster_type":{"type":"string","enum":["static","animated"]}}},"ImageProductsAddParams":{"type":"object","description":"Products to append to the image (list order sets the new positions).","required":["products"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ImageProductListingParams"},"minItems":1}}},"ImageCreateFromBase64":{"description":"Create an image from inline base64-encoded bytes (≤5MB decoded; use url or s3_key for anything larger).","allOf":[{"$ref":"#/components/schemas/ImageCreateParams"},{"type":"object","required":["file_base64"],"properties":{"filename":{"type":"string","description":"Filename with an image extension; used to infer the format when the payload is not a data: URI"},"file_base64":{"type":"string","format":"byte","description":"Base64-encoded image bytes, ≤5MB decoded"}}}]},"LiveStreamPlaylistVideos":{"type":"object","description":"Videos of a livestream playlist as rendered by NabooWeb.LiveStreamView.","properties":{"links":{"$ref":"#/components/schemas/Links"},"live_streams":{"type":"array","items":{"type":"object","description":"Livestream detailed summary"}},"paging":{"deprecated":true,"description":"Deprecated — use `links` and `pagination` instead. Retained during the migration window and removed in a future release.","allOf":[{"$ref":"#/components/schemas/Paging"}]},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Links":{"type":"object","description":"Pagination links for a collection response. Follow them verbatim and treat them as opaque. `next` is always present (`null` when there is no next page). `prev` is optional and omitted on forward-only feeds.","required":["next"],"properties":{"next":{"type":"string","description":"Path to the next page, or null.","nullable":true},"prev":{"type":"string","description":"Path to the previous page, or null. Optional — present only on endpoints that support backward paging.","nullable":true}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}},"LiveStreamPinProductsParams":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","description":"Products must already be listed on the livestream","items":{"type":"string","description":"product or product unit ID"},"maxItems":3,"minItems":1}}},"AiCurationConnectUrl":{"type":"object","required":["authorization_url"],"properties":{"state":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"authorization_url":{"type":"string","description":"Open this URL in a browser to complete the connection"}}},"LiveStreamStats":{"type":"object","description":"Consolidated livestream reporting stats (meta / live / replay).","properties":{"meta":{"type":"object","description":"Livestream identity and event metadata.","properties":{"video_id":{"type":"string"},"business_id":{"type":"string"},"channel_id":{"type":"string"},"start_date":{"type":"string","format":"date","nullable":true},"live_stream_id":{"type":"string"},"is_human_hosted":{"type":"boolean","nullable":true},"is_restream":{"type":"boolean","nullable":true},"event_length_mins":{"type":"number","nullable":true},"live_stream_name":{"type":"string","nullable":true}}},"live":{"description":"Metrics for the active broadcast, or null when not live.","nullable":true,"allOf":[{"$ref":"#/components/schemas/LiveStreamStatsMetrics"}]},"replay":{"type":"array","items":{"$ref":"#/components/schemas/LiveStreamStatsMetrics"}}}},"BusinessStoreCreateParams":{"type":"object","required":["name","currency"],"properties":{"name":{"type":"string"},"currency":{"type":"string","description":"Three-letter ISO 4217 code, e.g. USD"},"uid":{"type":"string","description":"Unique store identifier; must be unique within the business"},"url":{"type":"string"},"provider":{"type":"string","description":"Only \"local\" is accepted; defaults to \"local\""},"business_id":{"type":"string","description":"business ID to create the store under (optional for app tokens; defaults to the token's business)"}}},"ImageFolderList":{"type":"object","required":["image_folders","links","pagination"],"properties":{"links":{"$ref":"#/components/schemas/Links"},"pagination":{"$ref":"#/components/schemas/Pagination"},"image_folders":{"type":"array","items":{"$ref":"#/components/schemas/ImageFolder"}}}},"AiCurationCreatorList":{"type":"object","required":["creators","links","pagination"],"properties":{"links":{"$ref":"#/components/schemas/Links"},"creators":{"type":"array","items":{"$ref":"#/components/schemas/AiCurationCreator"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"VideoProductMatchAcceptParams":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","description":"Products whose matches to accept. Every match not listed becomes rejected.","items":{"type":"string","description":"Product ID"},"minItems":1}}},"BusinessList":{"type":"object","properties":{"businesses":{"type":"array","items":{"$ref":"#/components/schemas/Business"}}}},"LiveStreamUpdateParams":{"type":"object","description":"scheduled_at, time_zone, stream_source, s3_key, business_store_id, product_ids, base_video_id and auto_start_enabled can only be updated before the warmup window.","properties":{"description":{"type":"string"},"time_zone":{"type":"string"},"business_store_id":{"type":"string","description":"ID of the business store the products belong to"},"scheduled_at":{"type":"string","format":"date-time","description":"UTC ISO 8601 datetime"},"caption":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string","description":"product ID"}},"replay_enabled":{"type":"boolean"},"chat_enabled":{"type":"boolean"},"transcription_enabled":{"type":"boolean"},"chat_in_replay_enabled":{"type":"boolean"},"replay_messaging_enabled":{"type":"boolean"},"replay_interactions_enabled":{"type":"boolean"},"replay_viewers_count_enabled":{"type":"boolean"},"trailer_announcement_enabled":{"type":"boolean"},"trailer_messaging_enabled":{"type":"boolean"},"viewers_count_enabled":{"type":"boolean"},"hearts_count_enabled":{"type":"boolean"},"fomo_product_viewing_enabled":{"type":"boolean"},"access_code":{"type":"string"},"announcement":{"type":"string"},"auto_response":{"type":"string"},"s3_key":{"type":"string","description":"S3 key of a trailer video uploaded via the upload signature endpoints; defaults to the standard trailer"},"stream_source":{"type":"string","enum":["fw","external","prerecorded"]},"base_video_id":{"type":"string","description":"BaseVideo ID required when stream_source is prerecorded"},"viewers_count_mode":{"type":"string"},"chat_moderation_enabled":{"type":"boolean"},"auto_start_enabled":{"type":"boolean","description":"Whether a prerecorded livestream should start automatically at scheduled_at"}}},"VideoCreateFromUrl":{"description":"Create a video by downloading it from a public URL.","allOf":[{"$ref":"#/components/schemas/VideoCreateParams"},{"type":"object","required":["url"],"properties":{"async":{"type":"boolean","description":"When true the video is imported asynchronously: the response is 202 with a VideoImport object whose status can be polled at /api/v1/videos/imports/{id}."},"url":{"type":"string","description":"HTTP(S) URL of an mp4 or mov file (max 5GB). The server must return Content-Length and Content-Type headers."}}}]},"VideoPosterUpdateParams":{"type":"object","required":["weight"],"properties":{"weight":{"maximum":1,"type":"number","minimum":0}}},"AiCurationCreatorCreateParams":{"type":"object","required":["creators"],"properties":{"creators":{"type":"array","items":{"type":"object","required":["username","platform"],"properties":{"expires_at":{"type":"string","format":"date-time"},"username":{"type":"string"},"platform":{"type":"string","enum":["tiktok","instagram"]},"creator_name":{"type":"string"}}},"maxItems":100,"minItems":1}}},"LiveStreamUnpinnedProducts":{"type":"object","properties":{"unpinned_product_ids":{"type":"array","items":{"type":"string"}}}},"ImageFolderDeleteResult":{"type":"object","required":["deleted_folders","deleted_images"],"properties":{"deleted_folders":{"type":"integer","description":"Folders soft-deleted (incl. this one)"},"deleted_images":{"type":"integer","description":"Images soft-deleted in the subtree"}}},"AiCurationSocialAccount":{"type":"object","properties":{"id":{"type":"integer","description":"Connection id (a curation-engine id, not a SecretId)"},"provider":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"account_name":{"type":"string","nullable":true}}},"VideoPublishParams":{"type":"object","description":"Optional body for publishVideo. Omit entirely to publish immediately.","properties":{"published_at":{"type":"string","format":"date-time","description":"ISO 8601 time to publish. A future time schedules the video (capped at 28 days from now; a time beyond that window, or in the past, returns 422). Omit to publish now."}}},"BoundingBox":{"type":"object","description":"A resolution-independent box expressed as fractions of the image dimensions (0..1). x + w and y + h must not exceed 1.","required":["x","y","w","h"],"properties":{"x":{"maximum":1,"type":"number","minimum":0},"y":{"maximum":1,"type":"number","minimum":0},"h":{"maximum":1,"type":"number","minimum":0},"w":{"maximum":1,"type":"number","minimum":0}}},"PlaylistCreateParams":{"type":"object","required":["channel_id","name"],"properties":{"name":{"type":"string","description":"Playlist name (max 100 chars)"},"description":{"type":"string","nullable":true},"channel_id":{"type":"string","description":"channel ID the playlist belongs to"},"video_ids":{"type":"array","description":"Initial videos, in order","items":{"type":"string","description":"video ID"}}}},"PlaylistAddVideoParams":{"type":"object","required":["video_id"],"properties":{"position":{"type":"integer","description":"0-based insert index; appends to the end when omitted"},"video_id":{"type":"string","description":"video ID to add"}}},"ImageCreateFromS3Key":{"description":"Create an image from a file uploaded via createImageUploadSignature.","allOf":[{"$ref":"#/components/schemas/ImageCreateParams"},{"type":"object","required":["s3_key"],"properties":{"s3_key":{"type":"string","description":"S3 key returned by createImageUploadSignature"}}}]},"VideoList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"videos":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"paging":{"deprecated":true,"description":"Deprecated — use `links` and `pagination` instead. Retained during the migration window and removed in a future release.","allOf":[{"$ref":"#/components/schemas/Paging"}]},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"BusinessStore":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"currency":{"type":"string"},"url":{"type":"string","nullable":true},"provider":{"type":"string","description":"e.g. shopify, woocommerce, local"},"store_type":{"type":"string","description":"store, creator-store, or b2b-syndication-store"}}},"VideoDownloadList":{"type":"object","properties":{"videos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"format":{"type":"string","nullable":true},"width":{"type":"integer","nullable":true},"download_url":{"type":"string","description":"CDN URL of the video's transcoded file; null when the video has no available source","nullable":true},"duration":{"type":"number","description":"Duration in seconds","nullable":true},"height":{"type":"integer","nullable":true}}}}}},"LiveStreamStatsMetrics":{"type":"object","description":"Per-day viewer/engagement metrics for a live or replay row.","properties":{"report_date":{"type":"string","format":"date"},"total_watched_seconds":{"type":"number"},"unique_viewers_count":{"type":"integer"},"engaged_viewers":{"type":"integer"},"total_chats":{"type":"integer"},"total_product_clicks":{"type":"integer"},"share_targets":{"type":"object","additionalProperties":{"type":"integer"}},"total_shares":{"type":"integer"},"total_video_views":{"type":"integer"},"viewer_watch_time_breakdown":{"type":"object","properties":{"num_watched_0_to_1_mins":{"type":"integer"},"num_watched_1_to_10_mins":{"type":"integer"},"num_watched_10_to_30_mins":{"type":"integer"},"num_watched_30_to_end_mins":{"type":"integer"},"num_watched_0_mins":{"type":"integer"}}},"total_7d_attributed_gmv":{"type":"object","additionalProperties":{"type":"number"}},"total_7d_attributed_orders":{"type":"object","additionalProperties":{"type":"integer"}}}},"LiveStreamProductList":{"type":"object","required":["products"],"properties":{"products":{"type":"array","description":"Complete configured product snapshot in livestream order","items":{"$ref":"#/components/schemas/LiveStreamProduct"}}}},"MultipartCompleteParams":{"type":"object","required":["key","upload_id","parts"],"properties":{"key":{"type":"string","description":"S3 key returned when the upload was initiated"},"parts":{"type":"array","items":{"type":"object","required":["part","etag"],"properties":{"part":{"type":"integer","minimum":1},"etag":{"type":"string","description":"ETag returned by S3 for the uploaded part"}}},"maxItems":100,"minItems":1},"upload_id":{"type":"string"}}},"Image":{"type":"object","properties":{"access":{"type":"string","description":"Visibility: \"public\", \"private\" or \"unlisted\""},"id":{"type":"string"},"format":{"type":"string"},"description":{"type":"string","nullable":true},"title":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ImageMetadata"},"width":{"type":"integer","nullable":true},"source":{"type":"string","description":"social_media, aigc or api"},"url":{"type":"string","description":"Full-resolution CDN URL of the original file.","nullable":true},"locale":{"type":"string","nullable":true},"hashtags":{"type":"array","items":{"type":"string"}},"products":{"type":"array","items":{"$ref":"#/components/schemas/ImageProductListing"}},"published_at":{"type":"string","format":"date-time","description":"When the image is/was published; null for a draft. A future value is scheduled.","nullable":true},"file_size":{"type":"integer","nullable":true},"updated_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"height":{"type":"integer","nullable":true},"badge":{"type":"string","description":"e.g. \"ad\"","nullable":true},"archived_at":{"type":"string","format":"date-time","nullable":true},"is_published":{"type":"boolean","description":"Whether the image is currently published (published_at set and not in the future); evaluated at request time."},"blur_hash":{"type":"string","nullable":true},"folder_id":{"type":"string","nullable":true}}},"VideoPosterParams":{"type":"object","required":["url"],"properties":{"source":{"type":"string","description":"Where the poster was generated (defaults to \"api\")","nullable":true},"url":{"type":"string","description":"HTTP(S) URL of a poster image; downloaded and attached to the video"},"weight":{"maximum":1,"type":"number","description":"Rotation weight; heavier posters are served first","minimum":0,"nullable":true},"external_id":{"type":"string","description":"The generating system's own poster id; unique per video, usable to address the poster in updates","nullable":true},"video_poster_type":{"type":"string","enum":["static","animated"],"description":"Derived from the file format when omitted","nullable":true}}},"Pagination":{"type":"object","description":"Pagination state for the current response. Which keys appear depends on the strategy: cursor endpoints return `cursor` and may include `total_entries`; page endpoints return `page` and may include `page_size`/`total_pages`/`total_entries`.","properties":{"cursor":{"type":"string","description":"Cursor strategy: opaque cursor for the next page (pass back as `after`/`before`); null when there is no next page.","nullable":true},"page":{"type":"integer","description":"Page strategy: 1-based current page number."},"page_size":{"type":"integer","description":"Page strategy: items per page."},"total_entries":{"type":"integer","description":"Total number of items matching the current filters across all pages. Present only on endpoints that compute an exact total."},"total_pages":{"type":"integer","description":"Page strategy: total number of pages."},"has_more":{"type":"boolean","description":"True when another page is available now. Optional — may be omitted when computing it would be too expensive (clients then fall back to `next`). Required on live/polling feeds."}}},"VideoProductMatchList":{"type":"object","required":["status","matches"],"properties":{"status":{"type":"string","enum":["none","in_progress","completed","failed"],"description":"Status of the most recent matching job for the video"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/VideoProductMatch"}}}},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"locale":{"type":"string","nullable":true},"business_id":{"type":"string"},"username":{"type":"string"},"country":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true}}},"ProductUnitParams":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"url":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"integer"},"sku":{"type":"string"},"external_id":{"type":"string","description":"Stable unit identifier within the product. Required when updating an existing product (merging matches on it); optional on first-time creation, where an omitted value is auto-generated."},"original_price":{"type":"number"},"gtin":{"type":"string"},"mpn":{"type":"string"},"barcode":{"type":"string"}}},"ImageCreateFromUrl":{"description":"Create an image by fetching it from a public URL.","allOf":[{"$ref":"#/components/schemas/ImageCreateParams"},{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"HTTP(S) URL of a jpg/jpeg/png/webp image"}}}]},"ProductUnit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"integer"},"options":{"type":"array","items":{"type":"object"}},"url":{"type":"string","nullable":true},"price":{"type":"number","nullable":true},"quantity":{"type":"integer","nullable":true},"sku":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"original_price":{"type":"number","nullable":true},"gtin":{"type":"string","nullable":true},"mpn":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true}}},"VideoUpdateParams":{"type":"object","properties":{"access":{"type":"string","description":"Visibility, e.g. \"public\" or \"private\""},"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"business_store_id":{"type":"string","description":"ID of the business store the products belong to"},"caption":{"type":"string"},"custom_fields":{"type":"object","additionalProperties":{"type":"string"}},"action_url":{"type":"string","description":"Video CTA destination URL. Required when action_type is present.","nullable":true},"product_ids":{"type":"array","items":{"type":"string","description":"product ID"}},"action_type":{"type":"string","description":"Video CTA action type, e.g. \"shop_now\" or \"custom\"","nullable":true},"external_media":{"$ref":"#/components/schemas/ExternalMediaParams"},"display_social_attributions":{"type":"boolean","description":"When true, external_media (source, url, username) is required"},"archived_at":{"type":"string","format":"date-time","nullable":true},"poster_url":{"type":"string","description":"URL of a poster image (jpg, jpeg, png or webp). Pass an empty string to remove existing posters."},"variant_ids":{"type":"array","items":{"type":"string","description":"product variant ID"}},"video_hidden":{"type":"boolean","description":"Hide the video from product video feeds"},"audio_disabled":{"type":"boolean"},"action_custom_label":{"type":"string","description":"Label for action_type \"custom\"; must be omitted for other action types.","nullable":true}}},"PlaylistVideoViewsList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"video_views":{"type":"array","items":{"$ref":"#/components/schemas/PlaylistVideoViews"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Video":{"type":"object","properties":{"access":{"type":"string","description":"Visibility, e.g. \"public\" or \"private\""},"id":{"type":"string"},"description":{"type":"string","nullable":true},"hashtags":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","description":"When the video is/was published; null for an unpublished draft. A future value is scheduled.","nullable":true},"duration":{"type":"number","description":"Duration in seconds","nullable":true},"caption":{"type":"string","nullable":true},"custom_fields":{"type":"object","additionalProperties":{"type":"string"}},"action_url":{"type":"string","nullable":true},"product_ids":{"type":"array","items":{"type":"string"}},"action_type":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"video_posters":{"type":"array","items":{"$ref":"#/components/schemas/VideoPoster"}},"external_media":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExternalMedia"}]},"display_social_attributions":{"type":"boolean","nullable":true},"content_generation_type":{"type":"string","enum":["aigc"],"description":"Whether the video contains AI-generated content.","nullable":true},"archived_at":{"type":"string","format":"date-time","nullable":true},"audio_disabled":{"type":"boolean"},"action_custom_label":{"type":"string","nullable":true},"is_published":{"type":"boolean","description":"Whether the video is currently live (published_at is set and not in the future). Evaluated at request time, so a scheduled video flips to true automatically when its time passes."},"action_type_translation":{"type":"string","description":"Translated CTA display label; for custom actions, this is the custom label.","nullable":true},"watch_url":{"type":"string","description":"Web URL where a viewer can watch the video."}}},"LiveStreamPinnedProducts":{"type":"object","properties":{"pinned_product_ids":{"type":"array","items":{"type":"string"}}}},"VideoSubtitleFromUrl":{"description":"Add a subtitle by downloading a .vtt/.srt from a public URL.","allOf":[{"$ref":"#/components/schemas/VideoSubtitleParams"},{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"HTTP(S) URL of a .vtt or .srt file (max 5MB)"}}}]},"UploadSignatureParams":{"type":"object","required":["filename","mime_type","channel_id"],"properties":{"filename":{"type":"string"},"channel_id":{"type":"string"},"mime_type":{"type":"string","enum":["video/mp4","video/quicktime"]}}},"LiveStreamMessageList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/LiveStreamMessage"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"AiCurationCreatedCreators":{"type":"object","required":["creators"],"properties":{"creators":{"type":"array","items":{"$ref":"#/components/schemas/AiCurationCreator"}}}},"Paging":{"type":"object","description":"Pagination links. Keys are present only when the corresponding page exists.","properties":{"next":{"type":"string","description":"URL of the next page","nullable":true},"prev":{"type":"string","description":"URL of the previous page","nullable":true}}},"VideoCreateFromS3Key":{"description":"Create a video from a file previously uploaded via /api/v1/upload_signatures or the multipart upload endpoints.","allOf":[{"$ref":"#/components/schemas/VideoCreateParams"},{"type":"object","required":["s3_key"],"properties":{"s3_key":{"type":"string","description":"S3 key returned by the upload signature endpoints"}}}]},"BusinessStoreDetail":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"currency":{"type":"string"},"uid":{"type":"string","description":"Store identifier on the commerce platform","nullable":true},"url":{"type":"string","nullable":true},"provider":{"type":"string","description":"e.g. shopify, woocommerce, local"},"business_id":{"type":"string"},"store_type":{"type":"string","description":"store, creator-store, or b2b-syndication-store"}}},"ImageFolderCreateParams":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Folder name (max 255 chars)"},"parent_folder_id":{"type":"string","description":"Parent folder ID; omit for a root-level folder"}}},"ImageProductListing":{"type":"object","properties":{"bounding_box":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/BoundingBox"}]},"product_id":{"type":"string"},"product_unit_id":{"type":"string","nullable":true},"product_sort_position":{"type":"integer"},"image_sort_position":{"type":"integer","nullable":true},"image_hidden":{"type":"boolean"},"product_hidden":{"type":"boolean"}}},"ExternalMedia":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string","nullable":true},"username":{"type":"string","nullable":true},"navigation_enabled":{"type":"boolean","nullable":true}}},"ImageProductListingUpdateParams":{"type":"object","properties":{"bounding_box":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/BoundingBox"}]},"image_sort_position":{"type":"integer","nullable":true},"image_hidden":{"type":"boolean"},"product_hidden":{"type":"boolean"}}},"AiCurationSocialAccountList":{"type":"object","required":["accounts"],"properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/AiCurationSocialAccount"}}}},"ProductList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"paging":{"deprecated":true,"description":"Deprecated — use `links` and `pagination` instead. Retained during the migration window and removed in a future release.","allOf":[{"$ref":"#/components/schemas/Paging"}]},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Business":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}}},"ProductUpdateParams":{"type":"object","description":"Partial update: only provided fields change. `external_id` re-keys the product (the new value must be unused within the store; an empty string generates a new one). `product_units` and the product-level unit fields follow the same merge semantics as ProductUpsertParams — units are never deleted by this operation, and every sent unit must include an external_id.","properties":{"handle":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"object"}},"description":{"type":"string"},"category":{"type":"string"},"url":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit."},"brand":{"type":"string"},"price":{"type":"number","description":"Product-level unit field for simple products: applies to the product's single unit."},"quantity":{"type":"integer","description":"Product-level unit field for simple products: applies to the product's single unit."},"sku":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true},"external_id":{"type":"string"},"original_price":{"type":"number","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true},"gtin":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true},"mpn":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true},"shipping":{"type":"object"},"product_images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImageParams"}},"product_units":{"type":"array","items":{"$ref":"#/components/schemas/ProductUnitParams"}},"hide_price":{"type":"boolean"},"custom_cta":{"type":"object","properties":{"title":{"type":"string"},"target":{"type":"string"},"url":{"type":"string"},"hide_primary":{"type":"boolean"}}},"subtitle":{"type":"string"},"barcode":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true}}},"AiCurationFeedList":{"type":"object","required":["feed_items","links","pagination"],"properties":{"links":{"$ref":"#/components/schemas/Links"},"pagination":{"$ref":"#/components/schemas/Pagination"},"feed_items":{"type":"array","items":{"$ref":"#/components/schemas/AiCurationFeedItem"}}}},"LiveStreamEnded":{"type":"object","properties":{"status":{"type":"string","enum":["ended"]},"live_stream_id":{"type":"string"}}},"VideoCreateParams":{"type":"object","properties":{"access":{"type":"string","description":"Visibility, e.g. \"public\" or \"private\""},"description":{"type":"string"},"publish":{"type":"boolean","description":"Whether to publish the video. Defaults to true — the video is live immediately. Set to false to create an unpublished draft; published_at must then be omitted."},"hashtags":{"type":"array","items":{"type":"string"}},"business_store_id":{"type":"string","description":"ID of the business store the products belong to"},"channel_id":{"type":"string","description":"ID of the channel the video is created in (optional; defaults to the business's sole channel for app tokens)"},"published_at":{"type":"string","format":"date-time","description":"Optional ISO 8601 time to publish the video. A future time schedules it (capped at 28 days from now; beyond that returns 422). Omit to publish now."},"caption":{"type":"string"},"custom_fields":{"type":"object","additionalProperties":{"type":"string"}},"action_url":{"type":"string","description":"Video CTA destination URL. Required when action_type is present.","nullable":true},"product_ids":{"type":"array","items":{"type":"string","description":"product ID"}},"creator":{"type":"string","deprecated":true},"action_type":{"type":"string","description":"Video CTA action type, e.g. \"shop_now\" or \"custom\"","nullable":true},"external_media":{"$ref":"#/components/schemas/ExternalMediaParams"},"display_social_attributions":{"type":"boolean","description":"When true, external_media (source, url, username) is required"},"content_generation_type":{"type":"string","enum":["aigc"],"description":"Whether the video contains AI-generated content.","nullable":true},"archived_at":{"type":"string","format":"date-time","nullable":true},"poster_url":{"type":"string","description":"URL of a poster image (jpg, jpeg, png or webp). Pass an empty string to remove existing posters."},"variant_ids":{"type":"array","items":{"type":"string","description":"product variant ID"}},"video_hidden":{"type":"boolean","description":"Hide the video from product video feeds"},"creation_details":{"type":"object","description":"Free-form creation metadata"},"audio_disabled":{"type":"boolean"},"action_custom_label":{"type":"string","description":"Label for action_type \"custom\"; must be omitted for other action types.","nullable":true},"creator_gender":{"type":"string","deprecated":true},"creator_age_range":{"type":"string","deprecated":true},"creator_ethnicity":{"type":"string","deprecated":true},"sentiment":{"type":"string","deprecated":true}}},"BaseVideo":{"type":"object","properties":{"id":{"type":"string","description":"BaseVideo ID"},"title":{"type":"string"},"url":{"type":"string","nullable":true},"inserted_at":{"type":"string","format":"date-time"},"duration":{"type":"number","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"transcoding_status":{"type":"string","enum":["pending","transcoded","error"]}}},"ProductCustomCta":{"type":"object","properties":{"title":{"type":"string"},"target":{"type":"string","nullable":true},"url":{"type":"string"},"title_translation":{"type":"object","nullable":true},"hide_primary":{"type":"boolean"}}},"AiCurationImportParams":{"type":"object","required":["feed_item_id"],"properties":{"access":{"default":"public","type":"string","enum":["public","private","unlisted"]},"hashtags":{"type":"array","items":{"type":"string"}},"caption":{"type":"string","description":"Defaults to the feed item's own caption"},"poster_url":{"type":"string","description":"jpg/jpeg/png/webp URL for the poster"},"feed_item_id":{"type":"string","description":"The `id` of a feed item from listAiCurationFeed"},"product_matching":{"type":"object","description":"When `auto` is set, matching runs after the video is approved, bounded by the matching quota; usage is not checked at request time","properties":{"auto":{"default":false,"type":"boolean","description":"Run AI product matching once the imported video is approved"},"auto_accept":{"default":false,"type":"boolean","description":"Accept every match automatically (requires `auto`)"}}}}},"LiveStreamMessage":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"text":{"type":"string"},"username":{"type":"string"},"inserted_at":{"type":"string","format":"date-time"},"elapsed_time":{"type":"number","description":"Seconds from the start of the stream"}}},"VideoImport":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","description":"Import status, e.g. \"running\" or \"completed\""},"video_id":{"type":"string","description":"ID of the created video once the import completes","nullable":true},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"BaseVideoCreateParams":{"type":"object","required":["title","s3_key"],"properties":{"title":{"type":"string","description":"Display name for the Media Asset"},"channel_id":{"type":"string","description":"Channel ID (optional when the authenticated business has exactly one channel)"},"s3_key":{"type":"string","description":"The `key` returned by createUploadSignature or createMultipartUploadSignature after the upload completes"}}},"VideoDownloadBatchParams":{"type":"object","required":["video_ids"],"properties":{"video_ids":{"type":"array","description":"Video IDs to resolve, 1 to 50 per request","items":{"type":"string"},"maxItems":50,"minItems":1}}},"ImageProductListingParams":{"type":"object","description":"A product to list on the image. List order sets product_sort_position.","required":["product_id"],"properties":{"bounding_box":{"$ref":"#/components/schemas/BoundingBox"},"product_id":{"type":"string","description":"product ID"},"product_unit_id":{"type":"string","description":"product unit/variant ID"},"image_hidden":{"type":"boolean"},"product_hidden":{"type":"boolean"}}},"ImageFolder":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"archived_at":{"type":"string","format":"date-time","nullable":true},"parent_folder_id":{"type":"string","nullable":true},"has_subfolders":{"type":"boolean","description":"Whether the folder has any child folders (derived per-request in listings)"},"has_images":{"type":"boolean","description":"Whether the folder holds any images (derived per-request in listings)"}}},"LiveStreamProductDeal":{"type":"object","required":["id","product_unit_id","product_unit_external_id","coupon_code","discount_type","discount_amount","starts_at","ends_at"],"properties":{"id":{"type":"string","description":"livestream deal ID"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"discount_amount":{"type":"string","description":"Decimal discount value serialized as a string","nullable":true},"coupon_code":{"type":"string","nullable":true},"product_unit_id":{"type":"string","description":"Product unit ID, or null when the deal applies to the whole product","nullable":true},"discount_type":{"type":"string","enum":["percentage","fixed_amount"],"nullable":true},"product_unit_external_id":{"type":"string","nullable":true}}},"ProductUpsertParams":{"type":"object","description":"Products are upserted by external_id within the business store: an existing product with the same external_id is updated, otherwise a new one is created. `product_units` are merged by unit external_id: matching units are updated in place (keeping their IDs and video associations), new units are added, and units omitted from the list are left untouched — removing a unit requires the unit DELETE endpoint. When updating an existing product, every sent unit must include an external_id (422 otherwise). For simple products without variants, the product-level unit fields (sku, gtin, mpn, barcode, price, original_price, quantity, url) apply to the product's single unit instead of `product_units`; they are rejected when combined with `product_units` or when the product has multiple units.","required":["business_store_id"],"properties":{"handle":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"object"}},"description":{"type":"string"},"category":{"type":"string"},"url":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit."},"business_store_id":{"type":"string"},"brand":{"type":"string"},"price":{"type":"number","description":"Product-level unit field for simple products: applies to the product's single unit."},"quantity":{"type":"integer","description":"Product-level unit field for simple products: applies to the product's single unit."},"sku":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true},"external_id":{"type":"string"},"original_price":{"type":"number","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true},"gtin":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true},"mpn":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true},"shipping":{"type":"object"},"product_images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImageParams"}},"product_units":{"type":"array","items":{"$ref":"#/components/schemas/ProductUnitParams"}},"hide_price":{"type":"boolean"},"custom_cta":{"type":"object","properties":{"title":{"type":"string"},"target":{"type":"string"},"url":{"type":"string"},"hide_primary":{"type":"boolean"}}},"subtitle":{"type":"string"},"barcode":{"type":"string","description":"Product-level unit field for simple products: applies to the product's single unit.","nullable":true}}},"Product":{"type":"object","properties":{"handle":{"type":"string","nullable":true},"id":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"object"}},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"business_store_id":{"type":"string"},"brand":{"type":"string","nullable":true},"units":{"type":"array","items":{"$ref":"#/components/schemas/ProductUnit"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImage"}},"external_id":{"type":"string","nullable":true},"shipping":{"type":"object","nullable":true},"hide_price":{"type":"boolean"},"custom_cta":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ProductCustomCta"}]},"subtitle":{"type":"string","nullable":true}}},"ChannelList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"paging":{"deprecated":true,"description":"Deprecated — use `links` and `pagination` instead. Retained during the migration window and removed in a future release.","allOf":[{"$ref":"#/components/schemas/Paging"}]},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"BaseVideoList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"pagination":{"$ref":"#/components/schemas/Pagination"},"base_videos":{"type":"array","items":{"$ref":"#/components/schemas/BaseVideo"}}}},"ProductVideoList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"videos":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Video"},{"type":"object","properties":{"hidden":{"type":"boolean"}}}]}},"paging":{"deprecated":true,"description":"Deprecated — use `links` and `pagination` instead. Retained during the migration window and removed in a future release.","allOf":[{"$ref":"#/components/schemas/Paging"}]},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"ImageUpdateParams":{"type":"object","description":"Only the provided fields are updated.","properties":{"access":{"type":"string","enum":["public","private","unlisted"],"description":"Visibility; defaults to \"public\""},"description":{"type":"string","nullable":true},"title":{"type":"string","description":"Image title (max 255 chars); required on create"},"metadata":{"$ref":"#/components/schemas/ImageMetadata"},"source":{"type":"string","enum":["social_media","aigc","api"],"description":"Where the image came from; defaults to \"api\""},"locale":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"products":{"type":"array","description":"Ordered product listings (order sets product_sort_position). On update, replaces the existing listings wholesale.","items":{"$ref":"#/components/schemas/ImageProductListingParams"},"maxItems":100},"published_at":{"type":"string","format":"date-time","description":"ISO 8601 publish time. A future time schedules the image (capped at 28 days). Pass null (or omit) to create an unpublished draft.","nullable":true},"badge":{"type":"string","enum":["ad"],"nullable":true},"folder_id":{"type":"string","description":"Folder to place the image in (null/omit = unfiled)"}}},"UploadSignature":{"type":"object","description":"Pre-signed POST credentials for uploading a file directly to S3. POST to `post_url` as multipart/form-data with the fields below (mapped to the named S3 form field), a `Content-Type` field matching the requested mime_type, and the binary `file` field LAST. Then create the video with s3_key = `key`.","properties":{"date":{"type":"string","description":"Send as form field `X-Amz-Date`"},"policy":{"type":"string","description":"Send as form field `Policy`"},"signature":{"type":"string","description":"Send as form field `X-Amz-Signature`"},"key":{"type":"string","description":"S3 object key; send as form field `key` and reuse as s3_key"},"algorithm":{"type":"string","description":"Send as form field `X-Amz-Algorithm`"},"credential":{"type":"string","description":"Send as form field `X-Amz-Credential`"},"acl":{"type":"string","description":"Send as form field `acl`"},"post_url":{"type":"string","description":"URL to POST the multipart/form-data upload to"}}},"LiveStreamInsights":{"type":"object","properties":{"status":{"type":"string"},"live_stream_id":{"type":"string"}}},"ProductImage":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"integer"},"url":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"unit_external_ids":{"type":"array","items":{"type":"string","nullable":true}}}},"ExternalMediaParams":{"type":"object","description":"Attribution for media imported from a social network. Required (source, url, username) when display_social_attributions is true.","properties":{"source":{"type":"string","description":"Social network the media originates from"},"url":{"type":"string"},"username":{"type":"string"},"navigation_enabled":{"type":"boolean"}}},"ProductUnitUpdateParams":{"type":"object","description":"Partial in-place update of a product unit: only provided fields change and the unit keeps its ID, so video and listing associations are preserved. `external_id` must stay unique within the product and cannot be cleared. `sku`, `gtin`, `mpn` and `barcode` accept null to clear the field. When a change touches `price` or `original_price`, the final `original_price` must be at least the final `price` — raising `price` above the current `original_price` requires sending both (or a null `original_price`).","properties":{"name":{"type":"string"},"url":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"integer"},"sku":{"type":"string","nullable":true},"external_id":{"type":"string"},"original_price":{"type":"number","nullable":true},"gtin":{"type":"string","nullable":true},"mpn":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true}}},"ImageFolderUpdateParams":{"type":"object","description":"Only the provided fields are updated.","properties":{"name":{"type":"string"},"parent_folder_id":{"type":"string","description":"New parent folder ID; null moves the folder to the root","nullable":true}}},"VideoDownload":{"type":"object","required":["download_url"],"properties":{"format":{"type":"string","nullable":true},"width":{"type":"integer","nullable":true},"download_url":{"type":"string","description":"CDN URL of the video's transcoded file"},"duration":{"type":"number","description":"Duration in seconds","nullable":true},"height":{"type":"integer","nullable":true}}},"VideoCreateFromBase64":{"description":"Create a video from inline base64-encoded bytes. For short clips only — the decoded size must be ≤5MB (it rides the JSON body limit). Use url or s3_key for anything larger.","allOf":[{"$ref":"#/components/schemas/VideoCreateParams"},{"type":"object","required":["file_base64"],"properties":{"filename":{"type":"string","description":"Optional filename for the stored object"},"file_base64":{"type":"string","format":"byte","description":"Base64-encoded mp4/mov bytes, ≤5MB decoded"}}}]},"BusinessStoreUpdateParams":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"Three-letter ISO 4217 code, e.g. USD"},"url":{"type":"string"}}},"PlaylistList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"playlists":{"type":"array","items":{"$ref":"#/components/schemas/Playlist"}},"paging":{"deprecated":true,"description":"Deprecated — use `links` and `pagination` instead. Retained during the migration window and removed in a future release.","allOf":[{"$ref":"#/components/schemas/Paging"}]},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"ImageCreateParams":{"type":"object","required":["title"],"properties":{"access":{"type":"string","enum":["public","private","unlisted"],"description":"Visibility; defaults to \"public\""},"description":{"type":"string","nullable":true},"title":{"type":"string","description":"Image title (max 255 chars); required on create"},"metadata":{"$ref":"#/components/schemas/ImageMetadata"},"source":{"type":"string","enum":["social_media","aigc","api"],"description":"Where the image came from; defaults to \"api\""},"locale":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"products":{"type":"array","description":"Ordered product listings (order sets product_sort_position). On update, replaces the existing listings wholesale.","items":{"$ref":"#/components/schemas/ImageProductListingParams"},"maxItems":100},"published_at":{"type":"string","format":"date-time","description":"ISO 8601 publish time. A future time schedules the image (capped at 28 days). Pass null (or omit) to create an unpublished draft.","nullable":true},"badge":{"type":"string","enum":["ad"],"nullable":true},"folder_id":{"type":"string","description":"Folder to place the image in (null/omit = unfiled)"}}},"LiveStream":{"type":"object","properties":{"event_name":{"type":"string","nullable":true},"interactions":{"type":"array","description":"Polls, quizzes and questions; only returned on show","items":{"type":"object"}},"replay_messaging_enabled":{"type":"boolean"},"chat_enabled":{"type":"boolean"},"transcription_enabled":{"type":"boolean"},"auto_response":{"type":"string","nullable":true},"ended_at":{"type":"string","format":"date-time","nullable":true},"hearts_count_enabled":{"type":"boolean"},"stream_url":{"type":"string","description":"Only returned on create/update when stream_source is \"external\""},"scheduled_at":{"type":"string","format":"date-time","nullable":true},"fomo_product_viewing_enabled":{"type":"boolean"},"has_access_code":{"type":"boolean"},"video_id":{"type":"string","description":"backing video ID"},"replay_viewers_count_enabled":{"type":"boolean"},"replay_enabled":{"type":"boolean"},"viewers_count_enabled":{"type":"boolean"},"chat_in_replay_enabled":{"type":"boolean"},"auto_start_enabled":{"type":"boolean"},"started_at":{"type":"string","format":"date-time","nullable":true},"simulcast_provider":{"type":"string","description":"Simulcast backend provider; only returned on show","nullable":true},"replay_interactions_enabled":{"type":"boolean"},"base_video_id":{"type":"string","description":"BaseVideo ID","nullable":true},"id":{"type":"string","description":"livestream ID"},"provider":{"type":"string","description":"Only returned on create"},"viewers_count_mode":{"type":"string","nullable":true},"stream_key":{"type":"string","description":"Only returned on create/update when stream_source is \"external\""},"trailer_messaging_enabled":{"type":"boolean"},"stream_source":{"type":"string","enum":["fw","external","prerecorded"]},"thumbnail_url":{"type":"string","nullable":true},"trailer_announcement_enabled":{"type":"boolean"},"event_description":{"type":"string","nullable":true},"chat_moderation_enabled":{"type":"boolean"},"announcement":{"type":"string","nullable":true},"channel_id":{"type":"string","description":"channel ID"},"status":{"type":"string","enum":["idle","active","paused","replay","completed","expired"]}}},"VideoProductMatch":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","rejected"]},"product":{"$ref":"#/components/schemas/Product"},"updated_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"matching_score":{"type":"integer","description":"Higher is a better match"}}},"AiCurationFeedItem":{"type":"object","properties":{"id":{"type":"string","description":"Opaque feed-item handle — pass it to importAiCuration as `feed_item_id`.","nullable":true},"imported":{"type":"boolean","description":"Whether the item was already imported into the channel"},"summary":{"type":"string","nullable":true},"intent":{"type":"string","nullable":true},"score":{"type":"number","description":"Curation relevance score (higher is better)","nullable":true},"quotes":{"type":"array","items":{"type":"string"}},"video":{"$ref":"#/components/schemas/AiCurationExternalVideo"},"audience":{"type":"string","nullable":true},"tone":{"type":"string","nullable":true},"consent_status":{"type":"string","description":"Creator-consent status: \"approved\", \"pending\", \"need_review\" or \"denied\"","nullable":true},"whitelisted_creator":{"type":"boolean","description":"Whether the creator is on the whitelist"},"curated_at":{"type":"string","format":"date-time","nullable":true}}},"MultipartSignatureParams":{"type":"object","required":["filename","mime_type","channel_id","parts_count"],"properties":{"filename":{"type":"string"},"channel_id":{"type":"string"},"mime_type":{"type":"string","enum":["video/mp4","video/quicktime"]},"parts_count":{"maximum":100,"type":"integer","minimum":1}}},"ImageList":{"type":"object","required":["images","links","pagination"],"properties":{"links":{"$ref":"#/components/schemas/Links"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"ImageUploadSignatureParams":{"type":"object","required":["filename","content_type"],"properties":{"filename":{"type":"string"},"content_type":{"type":"string","enum":["image/jpeg","image/png","image/webp"]}}},"VideoSubtitleFromContent":{"description":"Add a subtitle from inline .vtt/.srt text.","allOf":[{"$ref":"#/components/schemas/VideoSubtitleParams"},{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"The subtitle file contents (.vtt or .srt text, max 5MB)"}}}]},"PlaylistUpdateParams":{"type":"object","description":"Only the provided fields are updated.","properties":{"name":{"type":"string","description":"Playlist name (max 100 chars)"},"description":{"type":"string","nullable":true},"video_ids":{"type":"array","description":"Full ordered list of videos (replaces the existing order)","items":{"type":"string","description":"video ID"}}}},"VideoPosterBatchUpdateParams":{"type":"object","required":["posters"],"properties":{"posters":{"type":"array","description":"Each item addresses a poster by exactly one of id or external_id","items":{"type":"object","required":["weight"],"properties":{"id":{"type":"string","description":"poster ID"},"weight":{"maximum":1,"type":"number","minimum":0},"external_id":{"type":"string"}}},"maxItems":100}}},"VideoPromotionPayload":{"type":"object","description":"Promotion content. Inapplicable and unset fields are null.","required":["offer_type","amount","offer_description","code","display_text","action_type","action_url"],"properties":{"code":{"type":"string","maxLength":255,"nullable":true},"amount":{"type":"number","nullable":true},"action_url":{"type":"string","maxLength":8192,"nullable":true},"action_type":{"type":"string","maxLength":25,"nullable":true},"offer_type":{"type":"string","enum":["percentage_discount","fixed_amount_discount","free_gift","bundle",null],"nullable":true},"offer_description":{"type":"string","maxLength":2048,"nullable":true},"display_text":{"type":"string","maxLength":2048,"nullable":true}}},"LiveStreamListItem":{"type":"object","properties":{"id":{"type":"string","description":"livestream ID"},"status":{"type":"string","enum":["idle","active","paused","replay","completed","expired"]},"started_at":{"type":"string","format":"date-time","nullable":true},"video_id":{"type":"string","description":"backing video ID"},"channel_id":{"type":"string","description":"channel ID"},"event_name":{"type":"string","nullable":true},"scheduled_at":{"type":"string","format":"date-time","nullable":true},"ended_at":{"type":"string","format":"date-time","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"replay_enabled":{"type":"boolean"},"chat_enabled":{"type":"boolean"},"transcription_enabled":{"type":"boolean"},"chat_in_replay_enabled":{"type":"boolean"},"replay_messaging_enabled":{"type":"boolean"},"replay_interactions_enabled":{"type":"boolean"},"replay_viewers_count_enabled":{"type":"boolean"},"trailer_announcement_enabled":{"type":"boolean"},"trailer_messaging_enabled":{"type":"boolean"},"viewers_count_enabled":{"type":"boolean"},"hearts_count_enabled":{"type":"boolean"},"fomo_product_viewing_enabled":{"type":"boolean"},"has_access_code":{"type":"boolean"},"announcement":{"type":"string","nullable":true},"auto_response":{"type":"string","nullable":true},"stream_source":{"type":"string","enum":["fw","external","prerecorded"]},"base_video_id":{"type":"string","description":"BaseVideo ID","nullable":true},"viewers_count_mode":{"type":"string","nullable":true},"chat_moderation_enabled":{"type":"boolean"},"auto_start_enabled":{"type":"boolean"},"event_description":{"type":"string","nullable":true}}},"VideoProductMatchStatus":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["in_progress"]},"auto_accept":{"type":"boolean"}}},"PlaylistReorderParams":{"type":"object","required":["video_ids"],"properties":{"video_ids":{"type":"array","description":"Full ordered list of the playlist's videos","items":{"type":"string","description":"video ID"}}}},"AiCurationExternalVideo":{"type":"object","properties":{"source":{"type":"string","description":"\"tiktok\" or \"instagram\"","nullable":true},"url":{"type":"string","description":"Post URL on the platform","nullable":true},"hashtags":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true},"username":{"type":"string","nullable":true},"duration":{"type":"number","description":"Duration in seconds","nullable":true},"display_name":{"type":"string","nullable":true},"external_id":{"type":"string","description":"Platform post id","nullable":true},"caption":{"type":"string","nullable":true},"likes_count":{"type":"integer","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"views_count":{"type":"integer","nullable":true},"comments_count":{"type":"integer","nullable":true}}},"LiveStreamDetail":{"type":"object","description":"Viewer-side livestream details as rendered by NabooWeb.LiveStreamView (playback URLs, channel info, replays and chat configuration).","required":["video_promotions"],"properties":{"video_promotions":{"type":"array","description":"Promotions attached to this video, ordered by descending ID. Product promotions are included only when their product is present in the cached livestream product listings, which exclude deleted products and deleted product units. Empty when no promotions qualify.","items":{"$ref":"#/components/schemas/VideoPromotion"}}}},"LiveStreamCreateParams":{"type":"object","required":["channel_id","caption","scheduled_at","stream_source"],"properties":{"description":{"type":"string"},"time_zone":{"type":"string"},"business_store_id":{"type":"string","description":"ID of the business store the products belong to"},"channel_id":{"type":"string","description":"ID of the channel the livestream is created in"},"scheduled_at":{"type":"string","format":"date-time","description":"UTC ISO 8601 datetime"},"caption":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string","description":"product ID"}},"replay_enabled":{"type":"boolean"},"chat_enabled":{"type":"boolean"},"transcription_enabled":{"type":"boolean"},"chat_in_replay_enabled":{"type":"boolean"},"replay_messaging_enabled":{"type":"boolean"},"replay_interactions_enabled":{"type":"boolean"},"replay_viewers_count_enabled":{"type":"boolean"},"trailer_announcement_enabled":{"type":"boolean"},"trailer_messaging_enabled":{"type":"boolean"},"viewers_count_enabled":{"type":"boolean"},"hearts_count_enabled":{"type":"boolean"},"fomo_product_viewing_enabled":{"type":"boolean"},"access_code":{"type":"string"},"announcement":{"type":"string"},"auto_response":{"type":"string"},"s3_key":{"type":"string","description":"S3 key of a trailer video uploaded via the upload signature endpoints; defaults to the standard trailer"},"stream_source":{"type":"string","enum":["fw","external","prerecorded"]},"base_video_id":{"type":"string","description":"BaseVideo ID required when stream_source is prerecorded"},"viewers_count_mode":{"type":"string"},"chat_moderation_enabled":{"type":"boolean"},"auto_start_enabled":{"type":"boolean","description":"Whether a prerecorded livestream should start automatically at scheduled_at"}}},"ProductImageParams":{"type":"object","properties":{"url":{"type":"string"},"external_id":{"type":"string"},"unit_identifiers":{"type":"array","description":"external_ids of the product units this image belongs to","items":{"type":"string"}}}},"ImagePublishParams":{"type":"object","description":"Optional body for publishImage. Omit entirely to publish immediately.","properties":{"published_at":{"type":"string","format":"date-time","description":"ISO 8601 time to publish. A future time schedules the image (capped at 28 days from now; beyond that, or in the past, returns 422). Omit to publish now."}}},"VideoSubtitleParams":{"type":"object","required":["language"],"properties":{"language":{"type":"string","description":"BCP-47 language code, e.g. en or en-US"},"is_cc":{"type":"boolean","description":"Whether this is a closed-captions track"}}},"VideoInsights":{"type":"object","properties":{"status":{"type":"string"},"video_id":{"type":"string"}}},"VideoSubtitle":{"type":"object","properties":{"id":{"type":"string"},"language":{"type":"string"},"is_cc":{"type":"boolean"}}},"BusinessStoreList":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/Links"},"paging":{"deprecated":true,"description":"Deprecated — use `links` and `pagination` instead. Retained during the migration window and removed in a future release.","allOf":[{"$ref":"#/components/schemas/Paging"}]},"stores":{"type":"array","items":{"$ref":"#/components/schemas/BusinessStore"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"PlaylistVideoViews":{"type":"object","properties":{"video_id":{"type":"string"},"live_stream_id":{"type":"string","description":"Encoded livestream ID, or null for a non-livestream item","nullable":true},"active_views":{"type":"integer"},"replay_views":{"type":"integer"}}}},"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"business_stores:read":"Read business stores","business_stores:write":"Create, update and delete business stores","businesses:read":"List the businesses the token can act on","channels:read":"List channels","channels:write":"Update channels and add (copy) videos to a channel","images:read":"Read library images, folders and download URLs","images:write":"Create and update library images, folders and product listings; create image upload signatures","insights:read":"Read video and livestream insights","livestreams:read":"Read livestreams, CSV exports and playlist videos","livestreams:write":"Create, update and end livestreams, pin products","playlists:read":"List playlists","playlists:write":"Create, update and delete playlists; add, remove and reorder playlist videos","products:read":"List product videos; also accepted for business store reads","products:write":"Create and update products","videos:read":"Read videos and video imports","videos:write":"Create and update videos, create upload signatures"},"tokenUrl":"/oauth/token"}}}}},"paths":{"/api/v1/playlists":{"get":{"description":"Lists a channel's playlists. `channel_id` is optional for a token whose business has a single channel; otherwise it is required.","parameters":[{"in":"query","name":"channel_id","description":"channel ID (optional; defaults to the business's sole channel)","required":false,"schema":{"type":"string"}},{"in":"query","name":"q","description":"Search filter: case-insensitive substring match on the playlist name. Use this to find a specific playlist instead of paging the channel.","required":false,"schema":{"type":"string"}},{"in":"query","name":"archived","description":"Archived filter: omitted or false returns only non-archived playlists; true returns only archived ones","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List playlists of a channel","responses":{"200":{"description":"Paginated playlists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"listPlaylists","security":[{"oauth2":["playlists:read"]}]},"post":{"summary":"Create a playlist in a channel","responses":{"201":{"description":"Created playlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Playlist"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"createPlaylist","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistCreateParams"}}}},"security":[{"oauth2":["playlists:write"]}]}},"/api/v1/channels/{channel_id}/ai_curation/social_accounts/connect_url":{"post":{"description":"Returns an `authorization_url` the user must open in a browser to log into the social platform and approve the connection — the OAuth flow cannot be completed over this API. Afterwards the account appears in listAiCurationSocialAccounts and the feed can populate.","parameters":[{"in":"path","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}}],"summary":"Start connecting a social account","responses":{"201":{"description":"The authorization URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationConnectUrl"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad gateway (the upstream AI-curation service failed or timed out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["AI Curation"],"operationId":"createAiCurationConnectUrl","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationConnectUrlParams"}}}},"security":[{"oauth2":["channels:write"]}]}},"/api/v1/products/{product_id}/images":{"get":{"description":"Reverse lookup: the business's library images that list this product, ordered by each listing's image_sort_position (unranked last). Listings hidden via image_hidden and archived/deleted images are excluded; unpublished images are excluded unless `include_unpublished=true`. Requires the `images` feature.","parameters":[{"in":"path","name":"product_id","description":"product ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"include_unpublished","description":"Include unpublished/scheduled images","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List library images featuring a product","responses":{"200":{"description":"Paginated images","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"listProductImages","security":[{"oauth2":["images:read"]}]}},"/api/v1/live_streams/{id}/pin_product":{"post":{"parameters":[{"in":"path","name":"id","description":"livestream ID","required":true,"schema":{"type":"string"}}],"summary":"Pin products on an active or paused livestream","responses":{"200":{"description":"Pinned product IDs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamPinnedProducts"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"pinLiveStreamProducts","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamPinProductsParams"}}}},"security":[{"oauth2":["livestreams:write"]}]}},"/api/v1/live_streams/{id}/messages":{"get":{"description":"Cursor-paginated chat messages for an ended livestream's replay. Page forward/backward with the opaque `after`/`before` cursors from the `links`/`pagination` in the response, or seek by `since`/`until` (elapsed-time/value window).","parameters":[{"in":"path","name":"id","description":"livestream ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"since","description":"Start of an elapsed-time/value window","required":false,"schema":{"type":"string"}},{"in":"query","name":"until","description":"End of an elapsed-time/value window","required":false,"schema":{"type":"string"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List a livestream replay's chat messages","responses":{"200":{"description":"Paginated chat messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamMessageList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"listLiveStreamMessages","security":[{"oauth2":["livestreams:read"]}]}},"/api/v1/products/{product_id}/units/{id}":{"get":{"parameters":[{"in":"path","name":"product_id","description":"product ID, or a product/unit identifier within the store: external_id, SKU, GTIN, MPN, or barcode","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","description":"product unit ID, or a unit identifier within the store: external_id, SKU, GTIN, or MPN","required":true,"schema":{"type":"string"}},{"in":"query","name":"business_store_id","description":"business store ID; used to resolve non-ID identifiers — defaults to the business's only store and is required when it has several (may be omitted when addressing by ID; when supplied, it must match the product’s store)","required":false,"schema":{"type":"string"}}],"summary":"Get a product unit","responses":{"200":{"description":"The product unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUnit"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"showProductUnit","security":[{"oauth2":["products:read"]}]},"delete":{"description":"Soft-deletes the unit. This is the only public operation that removes units — product upserts and updates never delete them.","parameters":[{"in":"path","name":"product_id","description":"product ID, or a product/unit identifier within the store: external_id, SKU, GTIN, MPN, or barcode","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","description":"product unit ID, or a unit identifier within the store: external_id, SKU, GTIN, or MPN","required":true,"schema":{"type":"string"}},{"in":"query","name":"business_store_id","description":"business store ID; used to resolve non-ID identifiers — defaults to the business's only store and is required when it has several (may be omitted when addressing by ID; when supplied, it must match the product’s store)","required":false,"schema":{"type":"string"}}],"summary":"Delete a product unit","responses":{"204":{"description":"No content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"deleteProductUnit","security":[{"oauth2":["products:write"]}]},"patch":{"description":"Partially updates the unit in place: omitted fields keep their values and the unit keeps its ID, so video and listing associations are preserved. This is also where a unit's `external_id` can be changed.","parameters":[{"in":"path","name":"product_id","description":"product ID, or a product/unit identifier within the store: external_id, SKU, GTIN, MPN, or barcode","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","description":"product unit ID, or a unit identifier within the store: external_id, SKU, GTIN, or MPN","required":true,"schema":{"type":"string"}},{"in":"query","name":"business_store_id","description":"business store ID; used to resolve non-ID identifiers — defaults to the business's only store and is required when it has several (may be omitted when addressing by ID; when supplied, it must match the product’s store)","required":false,"schema":{"type":"string"}}],"summary":"Update a product unit","responses":{"200":{"description":"Updated product unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUnit"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"updateProductUnit","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUnitUpdateParams"}}}},"security":[{"oauth2":["products:write"]}]}},"/api/v1/images/{id}/products/{product_id}":{"delete":{"description":"Deletes the listing selected by `product_id` (path) and, for a variant listing, `product_unit_id` (query). Remaining positions are left as-is (order is relative). Requires the `images` feature.","parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"product_id","description":"product ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"product_unit_id","description":"product unit/variant ID for a variant listing","required":false,"schema":{"type":"string"}}],"summary":"Remove a product from a library image","responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"removeImageProduct","security":[{"oauth2":["images:write"]}]},"patch":{"description":"Tweaks one product listing on the image: image_hidden, product_hidden, bounding_box, image_sort_position. Select the listing by `product_id` (path) and, for a variant listing, `product_unit_id` (query). Requires the `images` feature.","parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"product_id","description":"product ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"product_unit_id","description":"product unit/variant ID for a variant listing","required":false,"schema":{"type":"string"}}],"summary":"Update a single image-product listing","responses":{"200":{"description":"The updated listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageProductListing"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"updateImageProductListing","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageProductListingUpdateParams"}}}},"security":[{"oauth2":["images:write"]}]}},"/api/v1/videos/{id}/subtitles/{subtitle_id}":{"delete":{"parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"subtitle_id","description":"subtitle ID","required":true,"schema":{"type":"string"}}],"summary":"Remove a subtitle from a video","responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"deleteVideoSubtitle","security":[{"oauth2":["videos:write"]}]}},"/api/v1/images/upload_signatures":{"post":{"description":"Advanced path for large images: upload the bytes **directly to S3**, then call createImage with `s3_key`=<key>. Agents without S3 egress should instead use createImage with `url` (server fetches) or, for small images, `file_base64`. POST to `post_url` as multipart/form-data with the returned fields and the binary `file` field LAST. Requires the `images` feature.","summary":"Create a pre-signed S3 POST upload signature for an image","responses":{"201":{"description":"Pre-signed POST credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSignature"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"createImageUploadSignature","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageUploadSignatureParams"}}}},"security":[{"oauth2":["images:write"]}]}},"/api/v1/images/{id}":{"get":{"parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}}],"summary":"Get a library image","responses":{"200":{"description":"The image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"showImage","security":[{"oauth2":["images:read"]}]},"delete":{"description":"Soft-deletes the image; it no longer appears in listings.","parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}}],"summary":"Delete a library image","responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"deleteImage","security":[{"oauth2":["images:write"]}]},"patch":{"description":"Updates image metadata. Passing `products` replaces the image's product listings wholesale (an empty array clears them); omit it to leave them untouched.","parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}}],"summary":"Update a library image","responses":{"200":{"description":"Updated image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"updateImage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageUpdateParams"}}}},"security":[{"oauth2":["images:write"]}]}},"/api/v1/videos/{id}/unpublish":{"post":{"description":"Reverts the video to an unpublished draft by clearing `published_at`. The video is hidden from feeds and product lookups until it is published again.","parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Unpublish a video","responses":{"200":{"description":"Unpublished video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"unpublishVideo","security":[{"oauth2":["videos:write"]}]}},"/api/v1/playlists/{id}/videos/{video_id}/pin":{"delete":{"parameters":[{"in":"path","name":"id","description":"playlist ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"video_id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Unpin a video in a playlist (AI-feed playlists only)","responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"unpinPlaylistVideo","security":[{"oauth2":["playlists:write"]}]},"post":{"description":"Pins a video to the top of the playlist. Only supported on playlists that have an AI feed enabled; returns 422 otherwise.","parameters":[{"in":"path","name":"id","description":"playlist ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"video_id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Pin a video in a playlist (AI-feed playlists only)","responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"pinPlaylistVideo","security":[{"oauth2":["playlists:write"]}]}},"/api/v1/playlists/{id}":{"delete":{"parameters":[{"in":"path","name":"id","description":"playlist ID","required":true,"schema":{"type":"string"}}],"summary":"Delete a playlist","responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"deletePlaylist","security":[{"oauth2":["playlists:write"]}]},"patch":{"parameters":[{"in":"path","name":"id","description":"playlist ID","required":true,"schema":{"type":"string"}}],"summary":"Update a playlist","responses":{"200":{"description":"Updated playlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Playlist"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"updatePlaylist","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistUpdateParams"}}}},"security":[{"oauth2":["playlists:write"]}]}},"/api/v1/channels/{channel_id}/ai_curation/creators/{id}":{"delete":{"parameters":[{"in":"path","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","description":"Creator whitelist entry id from listAiCurationCreators","required":true,"schema":{"type":"integer"}}],"summary":"Remove a creator from the whitelist","responses":{"204":{"description":"Removed"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad gateway (the upstream AI-curation service failed or timed out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["AI Curation"],"operationId":"removeAiCurationCreator","security":[{"oauth2":["channels:write"]}]}},"/api/v1/live_streams/{id}/comments_csv":{"get":{"description":"Available only after the livestream has ended.","parameters":[{"in":"path","name":"id","description":"livestream ID","required":true,"schema":{"type":"string"}}],"summary":"Download livestream comments as CSV","responses":{"200":{"description":"Comments CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"downloadLiveStreamComments","security":[{"oauth2":["livestreams:read"]}]}},"/api/v1/videos/{id}/unarchive":{"post":{"parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Unarchive a video","responses":{"200":{"description":"Unarchived video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"unarchiveVideo","security":[{"oauth2":["videos:write"]}]}},"/api/v1/videos/{id}/download":{"get":{"description":"Returns a CDN URL of the video's transcoded file (the same file the business portal's download button serves) plus its format and dimensions. Requires the `content_download` feature on the business's subscription.","parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Get a download URL for the video file","responses":{"200":{"description":"The download URL and file facts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoDownload"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"getVideoDownloadUrl","security":[{"oauth2":["videos:read"]}]}},"/api/v1/live_streams/{id}/products":{"get":{"description":"Returns the complete, unpaginated snapshot of products configured for the livestream, including selected variants and configured deals. Supported Public API and CMS configuration paths accept at most 100 and 200 product-listing entries per livestream, respectively.","parameters":[{"in":"path","name":"id","description":"livestream ID","required":true,"schema":{"type":"string"}}],"summary":"List products configured for a livestream","responses":{"200":{"description":"Livestream products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamProductList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"listLiveStreamProducts","security":[{"oauth2":["livestreams:read"]}]}},"/api/v1/images/{id}/products":{"post":{"description":"Adds product listings to the image, appended after the existing ones (their positions are preserved; list order sets the new positions). Use create/updateImage's `products` array to reorder or replace wholesale. Every product must belong to the business, the total must stay ≤ 100, and no (product_id, product_unit_id) may duplicate an existing listing. Returns the image's full listing set after the append. Requires the `images` feature.","parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}}],"summary":"Append products to a library image","responses":{"200":{"description":"The image's product listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageProducts"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"addImageProducts","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageProductsAddParams"}}}},"security":[{"oauth2":["images:write"]}]}},"/api/v1/products/{id}":{"get":{"description":"Fetches a product by ID or by another identifier (external_id, SKU, GTIN, MPN, or barcode). Non-ID identifiers resolve within a store, so they need `business_store_id` unless the token resolves to a single store.","parameters":[{"in":"path","name":"id","description":"product ID, or a product/unit identifier within the store: external_id, SKU, GTIN, MPN, or barcode","required":true,"schema":{"type":"string"}},{"in":"query","name":"business_store_id","description":"business store ID; used to resolve non-ID identifiers — defaults to the business's only store and is required when it has several (may be omitted when addressing by ID; when supplied, it must match the product’s store)","required":false,"schema":{"type":"string"}}],"summary":"Get a product","responses":{"200":{"description":"The product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"showProduct","security":[{"oauth2":["products:read"]}]}},"/api/v1/images/{id}/download":{"get":{"description":"Returns the unsigned CDN URL of the image with format and dimensions. Pass `max_dimension` to receive a CDN rendition downscaled to fit that many pixels on the longest side (works for every format). Pass `format` (jpg, png, webp) to convert the file. `max_dimension` and `format` compose. Renditions are generated on the fly by the CDN's image-resizing service (the first generation may require a browser-like client). Requires the `images` feature.","parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"max_dimension","description":"Fit the longest side to this many pixels (16-16384, downscale only)","required":false,"schema":{"type":"integer"}},{"in":"query","name":"format","description":"Convert to this format (jpg, png, webp)","required":false,"schema":{"type":"string"}}],"summary":"Get a download URL for a library image","responses":{"200":{"description":"The download URL and file facts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageDownload"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"getImageDownloadUrl","security":[{"oauth2":["images:read"]}]}},"/api/v1/videos/{id}/archive":{"post":{"parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Archive a video","responses":{"200":{"description":"Archived video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"archiveVideo","security":[{"oauth2":["videos:write"]}]}},"/api/v1/live_streams/{id}":{"get":{"parameters":[{"in":"path","name":"id","description":"livestream ID","required":true,"schema":{"type":"string"}}],"summary":"Get a livestream","responses":{"200":{"description":"The livestream, including interactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStream"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"showLiveStream","security":[{"oauth2":["livestreams:read"]}]},"patch":{"parameters":[{"in":"path","name":"id","description":"livestream ID","required":true,"schema":{"type":"string"}}],"summary":"Update a livestream","responses":{"200":{"description":"Updated livestream","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStream"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"updateLiveStream","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamUpdateParams"}}}},"security":[{"oauth2":["livestreams:write"]}]}},"/api/v1/channels/{id}":{"patch":{"parameters":[{"in":"path","name":"id","description":"channel ID","required":true,"schema":{"type":"string"}}],"summary":"Update a channel's metadata","responses":{"200":{"description":"Updated channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Channels"],"operationId":"updateChannel","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelUpdateParams"}}}},"security":[{"oauth2":["channels:write"]}]}},"/api/v1/image_folders/{id}/unarchive":{"post":{"parameters":[{"in":"path","name":"id","description":"folder ID","required":true,"schema":{"type":"string"}}],"summary":"Unarchive an image folder","responses":{"200":{"description":"Unarchived folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageFolder"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Image Folders"],"operationId":"unarchiveImageFolder","security":[{"oauth2":["images:write"]}]}},"/api/v1/live_streams/{id}/unpin_product":{"post":{"parameters":[{"in":"path","name":"id","description":"livestream ID","required":true,"schema":{"type":"string"}}],"summary":"Unpin products on an active or paused livestream","responses":{"200":{"description":"Unpinned product IDs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamUnpinnedProducts"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"unpinLiveStreamProducts","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamPinProductsParams"}}}},"security":[{"oauth2":["livestreams:write"]}]}},"/api/v1/videos/{id}/posters":{"post":{"parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Add a poster to a video from a URL","responses":{"201":{"description":"Video with the new poster","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"addVideoPoster","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoPosterParams"}}}},"security":[{"oauth2":["videos:write"]}]},"patch":{"description":"All-or-nothing: every item must resolve and validate or nothing is applied. Each item addresses a poster by exactly one of id or external_id.","parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Update poster weights in one atomic batch","responses":{"200":{"description":"Video with updated posters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"updateVideoPosters","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoPosterBatchUpdateParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/businesses":{"get":{"description":"Returns the businesses available to the authenticated token — its own for an app token, the user's memberships for a user token. Use a returned id as business_id on business-scoped endpoints.","summary":"List the businesses the token can act on","responses":{"200":{"description":"The accessible businesses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessList"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Businesses"],"operationId":"listBusinesses","security":[{"oauth2":["businesses:read"]}]}},"/api/v1/image_folders":{"get":{"description":"Lists the direct children of `parent_folder_id` (omit it for the root level). Use each folder's `has_subfolders` to decide whether to expand it and `has_images` to tell whether it is empty. Pass `include_archived=true` to include archived folders. Requires the `images` feature.","parameters":[{"in":"query","name":"business_id","description":"business ID (optional for app tokens; defaults to the token's business)","required":false,"schema":{"type":"string"}},{"in":"query","name":"parent_folder_id","description":"Parent folder ID (omit for the root level)","required":false,"schema":{"type":"string"}},{"in":"query","name":"include_archived","description":"Include archived folders","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"Page through a level of the folder tree","responses":{"200":{"description":"Paginated folders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageFolderList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Image Folders"],"operationId":"listImageFolders","security":[{"oauth2":["images:read"]}]},"post":{"description":"Creates a folder at the library root, or under `parent_folder_id`. Requires the `images` feature.","summary":"Create an image folder","responses":{"201":{"description":"Created folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageFolder"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Image Folders"],"operationId":"createImageFolder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageFolderCreateParams"}}}},"security":[{"oauth2":["images:write"]}]}},"/api/v1/videos/download_urls":{"post":{"description":"Resolves CDN download URLs for up to 50 videos in a single request — use this instead of calling getVideoDownloadUrl per video. Results are returned in the order the ids were given, each carrying its `id`. A video with no available source is returned with a null `download_url` rather than failing the batch. Requires the `content_download` feature on the business's subscription. Not paginated: the response is bounded by the ids you send.","summary":"Get download URLs for many videos at once","responses":{"200":{"description":"The download URLs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoDownloadList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"getVideoDownloadUrls","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoDownloadBatchParams"}}}},"security":[{"oauth2":["videos:read"]}]}},"/api/v1/images/{id}/unpublish":{"post":{"description":"Reverts the image to an unpublished draft by clearing published_at.","parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}}],"summary":"Unpublish a library image","responses":{"200":{"description":"Unpublished image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"unpublishImage","security":[{"oauth2":["images:write"]}]}},"/api/v1/live_streams":{"get":{"description":"Lists primary, non-showroom livestreams for a channel. Use the returned `id` values as `live_stream_id` inputs to the livestream reporting stats endpoint.","parameters":[{"in":"query","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"statuses","description":"Comma-separated status filter, e.g. \"active,replay\"","required":false,"schema":{"type":"string"}},{"in":"query","name":"archived","description":"Archived filter: omitted or false returns only non-archived livestreams; true returns only archived ones","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List livestreams of a channel","responses":{"200":{"description":"Paginated livestreams","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"listLiveStreams","security":[{"oauth2":["livestreams:read"]}]},"post":{"summary":"Schedule a livestream","responses":{"201":{"description":"Created livestream","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStream"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"createLiveStream","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamCreateParams"}}}},"security":[{"oauth2":["livestreams:write"]}]}},"/api/v1/upload_multipart/complete":{"post":{"description":"Finalizes a multipart upload after every part has been PUT to its signed URL. Supply the `key` and `upload_id` from createMultipartUploadSignature and the `ETag` S3 returned for each uploaded part. On success (204), create the video with `s3_key`=<key>.","summary":"Complete a multipart upload","responses":{"204":{"description":"Upload completed"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request entity too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Uploads"],"operationId":"completeMultipartUpload","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultipartCompleteParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/base_videos":{"get":{"description":"Lists undeleted BaseVideos for a channel. Use a returned `id` as `base_video_id` when creating a prerecorded livestream. `channel_id` is optional when the token resolves to a single channel. A BaseVideo may be selected while it is still transcoding; check `transcoding_status` before the scheduled start time.","parameters":[{"in":"query","name":"channel_id","description":"channel ID (optional; defaults to the business's sole channel)","required":false,"schema":{"type":"string"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List Media Assets available for prerecorded livestreams","responses":{"200":{"description":"Paginated BaseVideos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseVideoList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"listBaseVideos","security":[{"oauth2":["livestreams:read"]}]},"post":{"description":"Creates a BaseVideo after a direct upload through createUploadSignature or createMultipartUploadSignature, matching the CMS upload flow. Pass the `key` returned by that operation as `s3_key`. The object must exist under the authenticated channel's S3 prefix; external S3 URLs are not supported. Transcoding starts asynchronously, so use listBaseVideos to check `transcoding_status` before starting the livestream.","summary":"Create a Media Asset for prerecorded livestreams","responses":{"201":{"description":"BaseVideo created and queued for transcoding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseVideo"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"createBaseVideo","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseVideoCreateParams"}}}},"security":[{"oauth2":["livestreams:write"]}]}},"/api/v1/stats/live_streams/{live_stream_id}":{"get":{"description":"Consolidated stats for a livestream: `meta` (identity), `live` (the active broadcast's metrics, or null), and `replay` (per-day replay metrics). `from`/`to` (ISO dates) bound only the replay array.","parameters":[{"in":"path","name":"live_stream_id","description":"livestream ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","description":"Replay-window start (ISO date, e.g. 2026-01-31)","required":false,"schema":{"type":"string"}},{"in":"query","name":"to","description":"Replay-window end (ISO date)","required":false,"schema":{"type":"string"}}],"summary":"Get consolidated livestream reporting stats","responses":{"200":{"description":"Consolidated livestream stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamStats"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"showLiveStreamReportingStats","security":[{"oauth2":["livestreams:read"]}]}},"/api/v1/live_streams/{live_stream_id}/detail":{"get":{"parameters":[{"in":"path","name":"live_stream_id","description":"livestream ID","required":true,"schema":{"type":"string"}}],"summary":"Get viewer-side livestream details","responses":{"200":{"description":"Livestream details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamDetail"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"showLiveStreamDetail","security":[{"oauth2":["livestreams:read"]}]}},"/api/v1/videos":{"get":{"description":"Lists a channel's videos. `channel_id` is optional for an app token whose business has a single channel; otherwise it is required. The pagination object includes `total_entries`, the exact number of videos matching the current filters.","parameters":[{"in":"query","name":"channel_id","description":"channel ID (optional; defaults to the business's sole channel)","required":false,"schema":{"type":"string"}},{"in":"query","name":"q","description":"Search filter: case-insensitive substring match on the video caption. Use this to find a specific video instead of paging the whole channel.","required":false,"schema":{"type":"string"}},{"in":"query","name":"status","description":"Filter by status","required":false,"schema":{"type":"string"}},{"in":"query","name":"access","description":"Filter by access level (public, private, unlisted)","required":false,"schema":{"type":"string"}},{"in":"query","name":"video_type","description":"Filter by video type (e.g. live_stream)","required":false,"schema":{"type":"string"}},{"in":"query","name":"hashtag","description":"Filter by an exact, case-insensitive hashtag. A leading `#` is significant; use the value returned in a video's `hashtags` array.","required":false,"schema":{"type":"string"}},{"in":"query","name":"archived","description":"Archived filter: omitted or false returns only non-archived videos; true returns only archived ones","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"published","description":"Filter by published state","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"fields","description":"Comma-separated subset of response fields to return, e.g. `id,caption,duration`. `id` is always included. Use it to cut response size on list calls. Valid fields: id, access, audio_disabled, caption, content_generation_type, description, duration, hashtags, archived_at, published_at, is_published, action_type, action_type_translation, action_url, action_custom_label, product_ids, variant_ids, custom_fields, display_social_attributions, external_media, thumbnail_url, watch_url, video_posters.","required":false,"schema":{"type":"string"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List videos in a channel","responses":{"200":{"description":"Paginated videos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"listVideos","security":[{"oauth2":["videos:read"]}]},"post":{"description":"Creates a video in a channel. Provide the source one of four ways (in order of preference): `url` (server downloads it — best for any real size, no client egress needed), `s3_key` (after a direct-to-S3 upload via the upload-signature endpoints), inline `file_base64` (**short clips only, ≤5MB** — the body is buffered and rides the JSON parser; larger inline uploads are rejected), or a multipart `file` (mp4/mov, max 5GB). channel_id is optional when the token resolves to a single channel; otherwise it is required. Video duration must be at least 3 seconds. The maximum follows the business's short-video subscription limit: 1 hour by default, up to the 3-hour platform ceiling.","summary":"Create a video","responses":{"201":{"description":"Created video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"202":{"description":"Asynchronous import accepted (JSON body with url and async: true)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoImport"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"createVideo","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/VideoCreateFromUrl"},{"$ref":"#/components/schemas/VideoCreateFromS3Key"},{"$ref":"#/components/schemas/VideoCreateFromBase64"}]}},"multipart/form-data":{"schema":{"type":"object","required":["metadata","file"],"properties":{"file":{"type":"string","format":"binary","description":"mp4 or mov, max 5GB"},"metadata":{"type":"string","description":"JSON-encoded VideoCreateParams object"}}}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/images/{id}/unarchive":{"post":{"parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}}],"summary":"Unarchive a library image","responses":{"200":{"description":"Unarchived image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"unarchiveImage","security":[{"oauth2":["images:write"]}]}},"/api/v1/live_streams/{id}/interactions/{interaction_id}/responses_csv":{"get":{"description":"Available only after the livestream has ended.","parameters":[{"in":"path","name":"id","description":"livestream ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"interaction_id","description":"interaction ID","required":true,"schema":{"type":"string"}}],"summary":"Download interaction (poll/quiz/question) responses as CSV","responses":{"200":{"description":"Interaction responses CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"downloadInteractionResponses","security":[{"oauth2":["livestreams:read"]}]}},"/api/v1/images/{id}/archive":{"post":{"parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}}],"summary":"Archive a library image","responses":{"200":{"description":"Archived image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"archiveImage","security":[{"oauth2":["images:write"]}]}},"/api/v1/videos/{id}/publish":{"post":{"description":"Publishes the video immediately, or — when `published_at` is a future time — schedules it. Scheduling is capped at 28 days from now; a `published_at` beyond that window (or in the past) returns 422. Omit the body to publish now. A scheduled video becomes visible automatically once the time passes, with no further call.","parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Publish a video, optionally at a scheduled time","responses":{"200":{"description":"Published video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"publishVideo","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoPublishParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/channels":{"get":{"parameters":[{"in":"query","name":"business_id","description":"business ID (optional for app tokens; defaults to the token's business)","required":false,"schema":{"type":"string"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List channels of a business","responses":{"200":{"description":"Paginated channels","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Channels"],"operationId":"listChannels","security":[{"oauth2":["channels:read"]}]}},"/api/v1/image_folders/{id}":{"get":{"parameters":[{"in":"path","name":"id","description":"folder ID","required":true,"schema":{"type":"string"}}],"summary":"Get an image folder","responses":{"200":{"description":"The folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageFolder"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Image Folders"],"operationId":"showImageFolder","security":[{"oauth2":["images:read"]}]},"delete":{"description":"Cascade soft-delete: the folder, every nested subfolder and every image in that subtree are soft-deleted in one transaction. Returns the affected counts (200, not 204).","parameters":[{"in":"path","name":"id","description":"folder ID","required":true,"schema":{"type":"string"}}],"summary":"Delete an image folder (cascades)","responses":{"200":{"description":"Cascade delete counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageFolderDeleteResult"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Image Folders"],"operationId":"deleteImageFolder","security":[{"oauth2":["images:write"]}]},"patch":{"description":"Renames the folder and/or moves it under a new `parent_folder_id` (pass null to move it to the root). Cycles and depth-limit violations return 422.","parameters":[{"in":"path","name":"id","description":"folder ID","required":true,"schema":{"type":"string"}}],"summary":"Rename or move an image folder","responses":{"200":{"description":"Updated folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageFolder"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Image Folders"],"operationId":"updateImageFolder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageFolderUpdateParams"}}}},"security":[{"oauth2":["images:write"]}]}},"/api/v1/products/{product_id}":{"delete":{"description":"Deletes a product (and its units/images) from its store. `business_store_id` is optional when the token resolves to a single store.","parameters":[{"in":"path","name":"product_id","description":"product ID, or a product/unit identifier within the store: external_id, SKU, GTIN, MPN, or barcode","required":true,"schema":{"type":"string"}},{"in":"query","name":"business_store_id","description":"business store ID; used to resolve non-ID identifiers — defaults to the business's only store and is required when it has several (may be omitted when addressing by ID; when supplied, it must match the product’s store)","required":false,"schema":{"type":"string"}}],"summary":"Delete a product","responses":{"204":{"description":"No content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"deleteProduct","security":[{"oauth2":["products:write"]}]},"patch":{"description":"Partially updates the product: omitted fields keep their values, and units are only ever merged, never deleted. This is also the only operation that can change a product's `external_id` (upsertProduct matches by it).","parameters":[{"in":"path","name":"product_id","description":"product ID, or a product/unit identifier within the store: external_id, SKU, GTIN, MPN, or barcode","required":true,"schema":{"type":"string"}},{"in":"query","name":"business_store_id","description":"business store ID; used to resolve non-ID identifiers — defaults to the business's only store and is required when it has several (may be omitted when addressing by ID; when supplied, it must match the product’s store)","required":false,"schema":{"type":"string"}}],"summary":"Update a product","responses":{"200":{"description":"Updated product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"updateProduct","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpdateParams"}}}},"security":[{"oauth2":["products:write"]}]}},"/api/v1/products/{product_id}/videos":{"get":{"parameters":[{"in":"path","name":"product_id","description":"product ID, or a product/unit identifier within the store: external_id, SKU, GTIN, MPN, or barcode","required":true,"schema":{"type":"string"}},{"in":"query","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"business_store_id","description":"business store ID; defaults to the first store","required":false,"schema":{"type":"string"}},{"in":"query","name":"accesses","description":"Comma-separated access filter, e.g. \"public,private\"","required":false,"schema":{"type":"string"}},{"in":"query","name":"archived","description":"Archived filter: omitted or false returns only non-archived videos; true returns only archived ones","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List videos featuring a product","responses":{"200":{"description":"Paginated videos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductVideoList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"listProductVideos","security":[{"oauth2":["products:read"]}]}},"/api/v1/videos/imports/{id}":{"get":{"parameters":[{"in":"path","name":"id","description":"import job ID returned when creating","required":true,"schema":{"type":"string"}}],"summary":"Get the status of an asynchronous video import","responses":{"200":{"description":"Import job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoImport"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"showVideoImport","security":[{"oauth2":["videos:read"]}]}},"/api/v1/videos/{id}/subtitles":{"post":{"description":"Add a subtitle (.vtt or .srt). Supply it as a multipart `file`, as inline `content` (the subtitle text), or as a `url` the server downloads. The server stores it and records the subtitle.","parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Add a subtitle to a video","responses":{"201":{"description":"Created subtitle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoSubtitle"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"addVideoSubtitle","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/VideoSubtitleFromContent"},{"$ref":"#/components/schemas/VideoSubtitleFromUrl"}]}},"multipart/form-data":{"schema":{"type":"object","required":["language","file"],"properties":{"file":{"type":"string","format":"binary","description":"Subtitle file (.vtt or .srt, max 5MB)"},"language":{"type":"string","description":"BCP-47 language code, e.g. en or en-US"},"is_cc":{"type":"boolean","description":"Whether this is a closed-captions track"}}}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/business_stores/{id}":{"get":{"parameters":[{"in":"path","name":"id","description":"business store ID","required":true,"schema":{"type":"string"}}],"summary":"Get a business store","responses":{"200":{"description":"Business store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessStoreDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Business Stores"],"operationId":"showBusinessStore","security":[{"oauth2":["business_stores:read"]},{"oauth2":["products:read"]}]},"delete":{"description":"Soft-deletes the store; it no longer appears in listings. Fails when the store's products are linked to a domain assistant (AVA knowledge base).","parameters":[{"in":"path","name":"id","description":"business store ID","required":true,"schema":{"type":"string"}}],"summary":"Delete a business store","responses":{"204":{"description":"Store deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Business Stores"],"operationId":"deleteBusinessStore","security":[{"oauth2":["business_stores:write"]}]},"patch":{"description":"Updates the store's metadata. `provider`, `uid` and `store_type` are immutable after creation.","parameters":[{"in":"path","name":"id","description":"business store ID","required":true,"schema":{"type":"string"}}],"summary":"Update a business store","responses":{"200":{"description":"Updated store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessStoreDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Business Stores"],"operationId":"updateBusinessStore","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessStoreUpdateParams"}}}},"security":[{"oauth2":["business_stores:write"]}]}},"/api/v1/upload_signatures":{"post":{"description":"Advanced / large-file path: the client must upload **directly to S3**, so it requires outbound network access to the S3 host. Agents without S3 egress (e.g. sandboxed MCP connectors) should instead use createVideo with `url` (server downloads) or, for short clips, `file_base64`. Returns pre-signed POST credentials to upload a video file (25KB to 5GB) directly to S3 — the bytes never pass through this API. Upload by sending an HTTP POST to `post_url` as multipart/form-data with these form fields, the binary `file` field LAST: `key`=<key>, `acl`=<acl>, `Content-Type`=<the mime_type you requested>, `Policy`=<policy>, `X-Amz-Algorithm`=<algorithm>, `X-Amz-Credential`=<credential>, `X-Amz-Date`=<date>, `X-Amz-Signature`=<signature>. A 2xx response means success; then call createVideo with `s3_key`=<key>.","summary":"Create a pre-signed S3 POST upload signature","responses":{"201":{"description":"Pre-signed POST credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSignature"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Uploads"],"operationId":"createUploadSignature","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSignatureParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/live_streams/playlists/{playlist_id}/videos":{"get":{"parameters":[{"in":"path","name":"playlist_id","description":"playlist ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"archived","description":"Archived filter: omitted or false returns only non-archived livestreams; true returns only archived ones","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"page","description":"Page number (default 1)","required":false,"schema":{"type":"integer"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List videos of a livestream playlist","responses":{"200":{"description":"Playlist videos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamPlaylistVideos"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"listLiveStreamPlaylistVideos","security":[{"oauth2":["livestreams:read"]}]}},"/api/v1/playlists/{id}/videos/{video_id}":{"delete":{"parameters":[{"in":"path","name":"id","description":"playlist ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"video_id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Remove a video from a playlist","responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"removePlaylistVideo","security":[{"oauth2":["playlists:write"]}]}},"/api/v1/channels/{channel_id}/ai_curation/imports":{"post":{"description":"Imports a curated social video by the `id` of a feed item from listAiCurationFeed. The import is asynchronous — poll the returned import with showVideoImport. `caption` defaults to the item's own caption. Set `product_matching.auto` (and optionally `auto_accept`) to run AI product matching automatically once the video is ready — matching runs after the video is approved and is bounded by the matching quota; usage is not checked at request time. Re-importing the same item into the same channel is rejected (422).","parameters":[{"in":"path","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}}],"summary":"Import a feed item into the video library","responses":{"202":{"description":"Import started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoImport"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad gateway (the upstream AI-curation service failed or timed out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["AI Curation"],"operationId":"importAiCuration","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationImportParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/upload_multipart/signatures":{"post":{"description":"Advanced / large-file path: parts are uploaded **directly to S3**, so the client needs S3 egress. Agents without it should use createVideo with `url`. For large files: split the file into `parts_count` parts (≤100; each part ≥5MB except the last). Returns `key`, `upload_id` and one pre-signed entry per part. PUT each part's bytes to its signed URL, capture the `ETag` response header from each PUT, then call completeMultipartUpload with `key`, `upload_id` and `parts`=[{part, etag}]. Finally call createVideo with `s3_key`=<key>. The bytes go straight to S3, not through this API.","summary":"Initiate a multipart upload and sign its parts","responses":{"201":{"description":"Multipart upload signatures","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultipartSignature"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Uploads"],"operationId":"createMultipartUploadSignature","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultipartSignatureParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/image_folders/{id}/archive":{"post":{"parameters":[{"in":"path","name":"id","description":"folder ID","required":true,"schema":{"type":"string"}}],"summary":"Archive an image folder (cosmetic; contents untouched)","responses":{"200":{"description":"Archived folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageFolder"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Image Folders"],"operationId":"archiveImageFolder","security":[{"oauth2":["images:write"]}]}},"/api/v1/videos/{id}/product_matches":{"get":{"description":"Returns the scored product recommendations produced by matchVideoProducts, sorted by score (best first), plus a job-level status: `none` (matching never requested), `in_progress`, `completed`, or `failed`. No subscription feature is required to read matches.","parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"List a video's AI product-match recommendations","responses":{"200":{"description":"The matches and job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoProductMatchList"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Product Matching"],"operationId":"listVideoProductMatches","security":[{"oauth2":["videos:read"]}]},"post":{"description":"Starts an AI matching job over the business store's products for an approved video. Matching is asynchronous — poll listVideoProductMatches for results. With `auto_accept: true` every returned match is accepted automatically (attaching the products to the video) instead of waiting for acceptVideoProductMatches. Bounded by the per-business `max_product_matching` quota (429 when exhausted).","parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Start AI product matching for a video","responses":{"202":{"description":"Matching started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoProductMatchStatus"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Product Matching"],"operationId":"matchVideoProducts","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoProductMatchCreateParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/videos/{id}":{"get":{"parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"fields","description":"Comma-separated subset of response fields to return, e.g. `id,caption,duration`. `id` is always included. Use it to cut response size on list calls. Valid fields: id, access, audio_disabled, caption, content_generation_type, description, duration, hashtags, archived_at, published_at, is_published, action_type, action_type_translation, action_url, action_custom_label, product_ids, variant_ids, custom_fields, display_social_attributions, external_media, thumbnail_url, watch_url, video_posters.","required":false,"schema":{"type":"string"}}],"summary":"Get a video","responses":{"200":{"description":"The video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"showVideo","security":[{"oauth2":["videos:read"]}]},"delete":{"parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Delete a video","responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"deleteVideo","security":[{"oauth2":["videos:write"]}]},"patch":{"parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Update a video","responses":{"200":{"description":"Updated video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"updateVideo","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoUpdateParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/live_streams/{id}/end":{"patch":{"parameters":[{"in":"path","name":"id","description":"livestream ID","required":true,"schema":{"type":"string"}}],"summary":"End an active or paused livestream","responses":{"200":{"description":"Livestream ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamEnded"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["LiveStreams"],"operationId":"endLiveStream","security":[{"oauth2":["livestreams:write"]}]}},"/api/v1/insights/live_streams/{live_stream_id}":{"get":{"parameters":[{"in":"path","name":"live_stream_id","description":"livestream ID","required":true,"schema":{"type":"string"}}],"summary":"Get insights for a livestream","responses":{"200":{"description":"Livestream insights","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamInsights"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Insights"],"operationId":"showLiveStreamInsights","security":[{"oauth2":["insights:read"]}]}},"/api/v1/business_stores":{"get":{"parameters":[{"in":"query","name":"business_id","description":"business ID (optional for app tokens; defaults to the token's business)","required":false,"schema":{"type":"string"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List the business's e-commerce stores","responses":{"200":{"description":"Paginated stores","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessStoreList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Business Stores"],"operationId":"listBusinessStores","security":[{"oauth2":["business_stores:read"]},{"oauth2":["products:read"]}]},"post":{"description":"Creates a `local` provider store. Platform stores (shopify, woocommerce, ...) carry credentials provisioned by their integration install flows and cannot be created through this API.","summary":"Create a business store","responses":{"201":{"description":"Created store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessStoreDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Business Stores"],"operationId":"createBusinessStore","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessStoreCreateParams"}}}},"security":[{"oauth2":["business_stores:write"]}]}},"/api/v1/images/{id}/publish":{"post":{"description":"Publishes the image immediately, or — when `published_at` is a future time — schedules it (capped at 28 days from now; beyond that, or in the past, returns 422). Omit the body to publish now.","parameters":[{"in":"path","name":"id","description":"image ID","required":true,"schema":{"type":"string"}}],"summary":"Publish a library image, optionally at a scheduled time","responses":{"200":{"description":"Published image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"publishImage","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImagePublishParams"}}}},"security":[{"oauth2":["images:write"]}]}},"/api/v1/products":{"get":{"parameters":[{"in":"query","name":"business_store_id","description":"business store ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"search","description":"Full-text search term (omit to list all)","required":false,"schema":{"type":"string"}},{"in":"query","name":"brand","description":"Filter to products with this brand (case-insensitive exact match); omit to not filter by brand","required":false,"schema":{"type":"string"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List or search products in a store","responses":{"200":{"description":"Paginated products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"listProducts","security":[{"oauth2":["products:read"]}]},"post":{"description":"Upserts by external_id within the store. Sent `product_units` are merged in place — units omitted from the list are never deleted by this operation (use deleteProductUnit to remove one).","summary":"Create or update a product","responses":{"201":{"description":"Upserted product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Products"],"operationId":"upsertProduct","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpsertParams"}}}},"security":[{"oauth2":["products:write"]}]}},"/api/v1/videos/{id}/posters/{poster_id}":{"delete":{"parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"poster_id","description":"poster ID","required":true,"schema":{"type":"string"}}],"summary":"Remove a poster from a video","responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"deleteVideoPoster","security":[{"oauth2":["videos:write"]}]},"patch":{"parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"poster_id","description":"poster ID","required":true,"schema":{"type":"string"}}],"summary":"Update a poster's weight","responses":{"200":{"description":"Video with the updated poster","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Videos"],"operationId":"updateVideoPoster","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoPosterUpdateParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/channels/{channel_id}/ai_curation/feed":{"get":{"description":"Lists social videos the AI curation engine discovered for the channel, scored and summarized. An empty feed usually means the curation settings are not configured (updateAiCurationSettings) or no social account is connected (createAiCurationConnectUrl). Each item's `id` is the opaque handle to pass to importAiCuration; filter with `consent_status=approved` or `whitelist_only=true` to browse content that is cleared for importing. Forward-only pagination. Requires the `ai_content_curation` feature.","parameters":[{"in":"path","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"sort","description":"Feed order: `newest` (default) or `score` (best first).","required":false,"schema":{"type":"string"}},{"in":"query","name":"source","description":"Filter by platform: `tiktok` or `instagram`.","required":false,"schema":{"type":"string"}},{"in":"query","name":"consent_status","description":"Filter by creator-consent status: `approved`, `pending`, `need_review` or `denied`.","required":false,"schema":{"type":"string"}},{"in":"query","name":"whitelist_only","description":"Only posts by creators on the whitelist.","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"external_ids","description":"Comma-separated platform ids to re-fetch specific feed items; requires `source`.","required":false,"schema":{"type":"string"}},{"in":"query","name":"hashtags","description":"Comma-separated discovery hashtags to filter by.","required":false,"schema":{"type":"string"}},{"in":"query","name":"language","description":"Filter by content language.","required":false,"schema":{"type":"string"}},{"in":"query","name":"inserted_at_begin","description":"Only feed items discovered at or after this time (ISO 8601 timestamp).","required":false,"schema":{"type":"string"}},{"in":"query","name":"inserted_at_end","description":"Only feed items discovered at or before this time (ISO 8601 timestamp).","required":false,"schema":{"type":"string"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`).","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 50, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"Browse the AI-curation discovery feed","responses":{"200":{"description":"The discovery feed page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationFeedList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad gateway (the upstream AI-curation service failed or timed out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["AI Curation"],"operationId":"listAiCurationFeed","security":[{"oauth2":["videos:read"]}]}},"/api/v1/playlists/{id}/videos":{"get":{"parameters":[{"in":"path","name":"id","description":"playlist ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"archived","description":"Archived filter: omitted or false returns only non-archived videos; true returns only archived ones","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"fields","description":"Comma-separated subset of response fields to return, e.g. `id,caption,duration`. `id` is always included. Use it to cut response size on list calls. Valid fields: id, access, audio_disabled, caption, content_generation_type, description, duration, hashtags, archived_at, published_at, is_published, action_type, action_type_translation, action_url, action_custom_label, product_ids, variant_ids, custom_fields, display_social_attributions, external_media, thumbnail_url, watch_url, video_posters.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page","description":"Page number (default 1)","required":false,"schema":{"type":"integer"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List a playlist's videos","responses":{"200":{"description":"Paginated videos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoList"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"listPlaylistVideos","security":[{"oauth2":["playlists:read"]}]},"put":{"parameters":[{"in":"path","name":"id","description":"playlist ID","required":true,"schema":{"type":"string"}}],"summary":"Reorder a playlist's videos","responses":{"200":{"description":"Updated playlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Playlist"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"reorderPlaylistVideos","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistReorderParams"}}}},"security":[{"oauth2":["playlists:write"]}]},"post":{"parameters":[{"in":"path","name":"id","description":"playlist ID","required":true,"schema":{"type":"string"}}],"summary":"Add a video to a playlist","responses":{"200":{"description":"Updated playlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Playlist"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Playlists"],"operationId":"addPlaylistVideo","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistAddVideoParams"}}}},"security":[{"oauth2":["playlists:write"]}]}},"/api/v1/videos/{id}/product_matches/accept":{"post":{"description":"Accepts the matches for the given product ids, attaching those products to the video. **Every match not listed becomes rejected**, so pass the full set you want to keep; unknown ids fail the whole request.","parameters":[{"in":"path","name":"id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Accept a subset of a video's product matches","responses":{"200":{"description":"The updated matches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoProductMatchList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Product Matching"],"operationId":"acceptVideoProductMatches","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoProductMatchAcceptParams"}}}},"security":[{"oauth2":["videos:write"]}]}},"/api/v1/images":{"get":{"description":"Lists a business's images (newest first). Filter by `folder_id` (pass `unfiled` for images in no folder), `source`, `access`, `badge`, `hashtag`, `archived` and `published`. Requires the `images` feature.","parameters":[{"in":"query","name":"business_id","description":"business ID (optional for app tokens; defaults to the token's business)","required":false,"schema":{"type":"string"}},{"in":"query","name":"folder_id","description":"Folder ID, or \"unfiled\" for images with no folder","required":false,"schema":{"type":"string"}},{"in":"query","name":"source","description":"Filter by source (social_media, aigc, api)","required":false,"schema":{"type":"string"}},{"in":"query","name":"access","description":"Filter by access level (public, private, unlisted)","required":false,"schema":{"type":"string"}},{"in":"query","name":"badge","description":"Filter by badge (e.g. ad)","required":false,"schema":{"type":"string"}},{"in":"query","name":"hashtag","description":"Filter to images carrying this hashtag","required":false,"schema":{"type":"string"}},{"in":"query","name":"archived","description":"Filter by archived state","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"published","description":"Filter by published state","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List the business's library images","responses":{"200":{"description":"Paginated images","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"listImages","security":[{"oauth2":["images:read"]}]},"post":{"description":"Adds an image to the business's library. Provide the source exactly one of three ways: `s3_key` (after a direct-to-S3 upload via createImageUploadSignature), `url` (the server fetches it), or inline `file_base64` (short images only, ≤5MB decoded). Attach products in one call via the ordered `products` array (order sets product_sort_position). Requires the `images` feature.","summary":"Create a library image","responses":{"201":{"description":"Created image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Images"],"operationId":"createImage","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ImageCreateFromS3Key"},{"$ref":"#/components/schemas/ImageCreateFromUrl"},{"$ref":"#/components/schemas/ImageCreateFromBase64"}]}}}},"security":[{"oauth2":["images:write"]}]}},"/api/v1/channels/{channel_id}/ai_curation/creators":{"get":{"description":"Creators whose posts are pre-cleared for curation (their feed items report `whitelisted_creator: true`). Forward-only pagination.","parameters":[{"in":"path","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"platform","description":"Filter by platform: `tiktok` or `instagram`.","required":false,"schema":{"type":"string"}},{"in":"query","name":"username","description":"Filter by exact creator username.","required":false,"schema":{"type":"string"}},{"in":"query","name":"include_expired","description":"Include expired entries.","required":false,"schema":{"type":"boolean"}},{"in":"query","name":"after","description":"Opaque cursor for the next page.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 50, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List the creator whitelist","responses":{"200":{"description":"The whitelist page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationCreatorList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad gateway (the upstream AI-curation service failed or timed out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["AI Curation"],"operationId":"listAiCurationCreators","security":[{"oauth2":["channels:read"]}]},"post":{"parameters":[{"in":"path","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}}],"summary":"Add creators to the whitelist","responses":{"201":{"description":"The created entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationCreatedCreators"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad gateway (the upstream AI-curation service failed or timed out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["AI Curation"],"operationId":"addAiCurationCreators","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationCreatorCreateParams"}}}},"security":[{"oauth2":["channels:write"]}]}},"/api/v1/stats/playlists/{playlist_id}/video_views":{"get":{"description":"Returns the playlist's videos in the same order and pagination as the embed playlist feed, each with active and replay view counts. Non-livestream items and videos with no reporting data return zero views and a null live_stream_id. Note: this is a temporary wrapper over the reporting data and is expected to be deprecated once view metrics are available directly in the embed API.","parameters":[{"in":"path","name":"playlist_id","description":"playlist ID","required":true,"schema":{"type":"string"}},{"in":"query","name":"after","description":"Opaque cursor for the next page (from `pagination.cursor` or `links.next`); ascending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"before","description":"Opaque cursor for the previous page; descending order.","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","description":"Page size (default 10, max 100)","required":false,"schema":{"type":"integer"}}],"summary":"List active and replay view counts for a playlist's videos","responses":{"200":{"description":"Paginated playlist video views","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistVideoViewsList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Insights"],"operationId":"listPlaylistVideoViews","security":[{"oauth2":["insights:read"]}]}},"/api/v1/insights/videos/{video_id}":{"get":{"parameters":[{"in":"path","name":"video_id","description":"video ID","required":true,"schema":{"type":"string"}}],"summary":"Get insights for a video","responses":{"200":{"description":"Video insights","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoInsights"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Insights"],"operationId":"showVideoInsights","security":[{"oauth2":["insights:read"]}]}},"/api/v1/channels/{channel_id}/ai_curation/social_accounts":{"get":{"description":"The TikTok/Instagram accounts the curation engine crawls for this channel.","parameters":[{"in":"path","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}}],"summary":"List the connected social accounts","responses":{"200":{"description":"The connected accounts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationSocialAccountList"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad gateway (the upstream AI-curation service failed or timed out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["AI Curation"],"operationId":"listAiCurationSocialAccounts","security":[{"oauth2":["channels:read"]}]}},"/api/v1/channels/{channel_id}/ai_curation/settings":{"get":{"parameters":[{"in":"path","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}}],"summary":"Get the AI-curation settings","responses":{"200":{"description":"The curation settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationSettings"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad gateway (the upstream AI-curation service failed or timed out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["AI Curation"],"operationId":"showAiCurationSettings","security":[{"oauth2":["channels:read"]}]},"patch":{"description":"**This is how a discovery feed is created and configured**: the hashtags, mentioned usernames and brand description set here determine which TikTok/Instagram videos the curation engine surfaces in listAiCurationFeed. Array fields replace the stored value wholesale. Requires the `ai_content_curation` feature.","parameters":[{"in":"path","name":"channel_id","description":"channel ID","required":true,"schema":{"type":"string"}}],"summary":"Update the AI-curation settings","responses":{"200":{"description":"The updated settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationSettings"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (missing, invalid or expired OAuth token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (feature not enabled for the business)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (token lacks the required scope or business access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad gateway (the upstream AI-curation service failed or timed out)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["AI Curation"],"operationId":"updateAiCurationSettings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCurationSettingsUpdateParams"}}}},"security":[{"oauth2":["channels:write"]}]}}},"servers":[{"url":"/"}],"security":[{"oauth2":[]}],"openapi":"3.0.3"}