From b66248380c761de1386d794311229d5cf8496968 Mon Sep 17 00:00:00 2001 From: Yangliang Li Date: Fri, 26 Jun 2026 19:14:21 +0800 Subject: [PATCH] docs: add youtube and instagram apimux skills --- skills/apimux-instagram/SKILL.md | 318 +++++++++++++++++++++++++++++++ skills/apimux-youtube/SKILL.md | 273 ++++++++++++++++++++++++++ 2 files changed, 591 insertions(+) create mode 100644 skills/apimux-instagram/SKILL.md create mode 100644 skills/apimux-youtube/SKILL.md diff --git a/skills/apimux-instagram/SKILL.md b/skills/apimux-instagram/SKILL.md new file mode 100644 index 0000000..dc13b6e --- /dev/null +++ b/skills/apimux-instagram/SKILL.md @@ -0,0 +1,318 @@ +--- +name: apimux-instagram +description: "Instagram public content data. Search users, hashtags, and reels; inspect profiles, posts, reels, comments, and replies for creator research, brand monitoring, and audience feedback analysis." +metadata: + source: instagram + requires: + bins: ["apimux"] + cliHelp: "apimux schema capabilities | grep instagram" +--- + +# Instagram + +Search and inspect public Instagram users, hashtags, reels, profiles, posts, comments, and comment replies. Use this for creator research, brand monitoring, content sampling, and audience feedback analysis. + +**Before using:** Read [`../apimux-shared/SKILL.md`](../apimux-shared/SKILL.md) for response structure, error handling, pagination metadata, and CLI conventions. + +**CLI note:** Current `apimux-cli` does not expose `apimux instagram ...` source subcommands yet. Use the generic capability runner: + +```bash +apimux capability call instagram.search_reels --params-json '{"query":"desk setup","count":10}' +``` + +## What you can do + +- **Find users by keyword** -> `instagram.search_users` +- **Find hashtags by keyword** -> `instagram.search_hashtags` +- **Search public reels** -> `instagram.search_reels` +- **Inspect one profile** -> `instagram.get_user_profile` +- **List one user's posts** -> `instagram.get_user_posts` +- **List one user's reels** -> `instagram.get_user_reels` +- **Inspect one post or reel** -> `instagram.get_post_detail` +- **Collect comments** -> `instagram.get_post_comments` +- **Collect replies to one comment** -> `instagram.get_comment_replies` + +## Available capabilities + +| Capability | What it does | When to use | +|------------|--------------|-------------| +| `instagram.search_users` | Search public Instagram users | Creator discovery and profile lookup | +| `instagram.search_hashtags` | Search hashtags | Topic and hashtag sizing | +| `instagram.search_reels` | Search public reels by keyword | Reels discovery and content research | +| `instagram.get_user_profile` | Get one profile by username or user ID | Creator qualification and profile summary | +| `instagram.get_user_posts` | List public posts for one user | Profile content sampling | +| `instagram.get_user_reels` | List public reels for one user | Short-video content sampling | +| `instagram.get_post_detail` | Get one post/reel by shortcode, media ID, or URL | Inspect metadata, media, owner, and engagement | +| `instagram.get_post_comments` | List comments for one post/reel | Audience feedback and objection mining | +| `instagram.get_comment_replies` | List replies for one parent comment | Thread-level discussion analysis | + +## Common workflows + +- Creator discovery: use `instagram.search_users`, pick `username` or `user_id`, then call `instagram.get_user_profile`, `instagram.get_user_posts`, or `instagram.get_user_reels`. +- Reels research: use `instagram.search_reels` for topic discovery, then inspect promising results with `instagram.get_post_detail`. +- Post URL known: call `instagram.get_post_detail` by `url`, then use `instagram.get_post_comments`. +- Comment mining: use `instagram.get_post_comments`, then pass a returned `comment_id` into `instagram.get_comment_replies`. + +--- + +## instagram.search_users + +Search public Instagram users by keyword. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `query` | string | Yes | Instagram user search query | +| `cursor` | string | No | Pagination cursor | +| `count` | integer | No | Maximum users to return | + +### CLI usage + +```bash +apimux capability call instagram.search_users --params-json '{"query":"desk setup","count":10}' +apimux capability call instagram.search_users --params-json '{"query":"desk setup","cursor":"","count":10}' +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | string | Instagram numeric user ID | +| `username` | string | Username | +| `full_name` | string | Display name | +| `url` | string | Canonical profile URL | +| `bio` | string | Biography | +| `category` | string | Business/category label | +| `profile_pic_url` | string | Avatar URL | +| `follower_count` | integer | Follower count | +| `following_count` | integer | Following count | +| `media_count` | integer | Public media count | +| `is_business` | boolean | Business account indicator | +| `is_verified` | boolean | Verified badge | + +--- + +## instagram.search_hashtags + +Search Instagram hashtags by keyword. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `query` | string | Yes | Instagram hashtag search query | + +### CLI usage + +```bash +apimux capability call instagram.search_hashtags --params-json '{"query":"desksetup"}' +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `hashtag_id` | string | Hashtag ID | +| `name` | string | Hashtag name | +| `media_count` | integer | Public media count | + +--- + +## instagram.search_reels + +Search public Instagram reels by keyword. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `query` | string | Yes | Instagram reels search query | +| `cursor` | string | No | Pagination cursor | +| `count` | integer | No | Maximum reels to return | + +### CLI usage + +```bash +apimux capability call instagram.search_reels --params-json '{"query":"desk setup","count":10}' +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `media_id` | string | Instagram media ID | +| `shortcode` | string | Shortcode | +| `permalink` | string | Canonical Instagram URL | +| `caption` | string | Caption text | +| `media_type` | string | Media type | +| `media_url` | string | Media URL | +| `thumbnail` | string | Thumbnail URL | +| `taken_at` | string | Timestamp or provider display value | +| `like_count` | integer | Like count | +| `comment_count` | integer | Comment count | +| `view_count` | integer | View/play count | +| `owner` | object | Canonical owner summary | + +--- + +## instagram.get_user_profile + +Fetch one public Instagram profile by username or user ID. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Conditional | Instagram username | +| `user_id` | string | Conditional | Instagram numeric user ID | + +### CLI usage + +```bash +apimux capability call instagram.get_user_profile --params-json '{"username":"natgeo"}' +apimux capability call instagram.get_user_profile --params-json '{"user_id":"123456789"}' +``` + +### Notes + +- Provide at least one identity input: `username` or `user_id`. +- Output fields match `instagram.search_users` with fuller detail when the provider returns it. + +--- + +## instagram.get_user_posts + +List public posts for one Instagram user. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Conditional | Instagram username | +| `user_id` | string | Conditional | Instagram numeric user ID | +| `cursor` | string | No | Pagination cursor | +| `count` | integer | No | Maximum posts to return | + +### CLI usage + +```bash +apimux capability call instagram.get_user_posts --params-json '{"username":"natgeo","count":12}' +apimux capability call instagram.get_user_posts --params-json '{"user_id":"123456789","count":12}' +``` + +### Notes + +- Provide at least one identity input: `username` or `user_id`. +- Response fields match the media fields shown under `instagram.search_reels`. + +--- + +## instagram.get_user_reels + +List public reels for one Instagram user. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `username` | string | Conditional | Instagram username | +| `user_id` | string | Conditional | Instagram numeric user ID | +| `cursor` | string | No | Pagination cursor | +| `count` | integer | No | Maximum reels to return | + +### CLI usage + +```bash +apimux capability call instagram.get_user_reels --params-json '{"username":"natgeo","count":12}' +``` + +### Notes + +- Provide at least one identity input: `username` or `user_id`. +- Response fields match the media fields shown under `instagram.search_reels`. + +--- + +## instagram.get_post_detail + +Fetch one public Instagram post or reel by shortcode, media ID, or URL. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `shortcode` | string | Conditional | Instagram post shortcode | +| `media_id` | string | Conditional | Instagram media ID | +| `url` | string | Conditional | Instagram post/reel URL | + +### CLI usage + +```bash +apimux capability call instagram.get_post_detail --params-json '{"shortcode":"C0abc123xyz"}' +apimux capability call instagram.get_post_detail --params-json '{"url":"https://www.instagram.com/p/C0abc123xyz/"}' +``` + +### Notes + +- Provide at least one identity input: `shortcode`, `media_id`, or `url`. +- Response fields match the media fields shown under `instagram.search_reels`. + +--- + +## instagram.get_post_comments + +List comments for one public Instagram post or reel. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `shortcode` | string | Conditional | Instagram post shortcode | +| `media_id` | string | Conditional | Instagram media ID | +| `url` | string | Conditional | Instagram post/reel URL | +| `cursor` | string | No | Pagination cursor | +| `count` | integer | No | Maximum comments to return | + +### CLI usage + +```bash +apimux capability call instagram.get_post_comments --params-json '{"shortcode":"C0abc123xyz","count":20}' +apimux capability call instagram.get_post_comments --params-json '{"url":"https://www.instagram.com/p/C0abc123xyz/","count":20}' +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `comment_id` | string | Comment ID | +| `text` | string | Comment text | +| `create_time` | string | Timestamp or provider display value | +| `like_count` | integer | Like count | +| `reply_count` | integer | Reply count | +| `author` | object | Canonical author summary | + +--- + +## instagram.get_comment_replies + +List replies for one Instagram parent comment. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `comment_id` | string | Yes | Parent comment ID | +| `cursor` | string | No | Pagination cursor | +| `count` | integer | No | Maximum replies to return | + +### CLI usage + +```bash +apimux capability call instagram.get_comment_replies --params-json '{"comment_id":"18000000000000000","count":20}' +``` + +### Notes + +- `comment_id` is required. +- Use `meta.cursor` and `meta.has_more` for pagination when returned. diff --git a/skills/apimux-youtube/SKILL.md b/skills/apimux-youtube/SKILL.md new file mode 100644 index 0000000..7c7fc47 --- /dev/null +++ b/skills/apimux-youtube/SKILL.md @@ -0,0 +1,273 @@ +--- +name: apimux-youtube +description: "YouTube public content data. Search videos, inspect video and channel details, fetch transcripts, list channel videos, and collect comments or replies for brand monitoring, creator research, and content analysis." +metadata: + source: youtube + requires: + bins: ["apimux"] + cliHelp: "apimux schema capabilities | grep youtube" +--- + +# YouTube + +Search and inspect public YouTube videos, channels, transcripts, comments, and comment replies. Use this for brand monitoring, creator/content research, topic validation, and audience feedback analysis. + +**Before using:** Read [`../apimux-shared/SKILL.md`](../apimux-shared/SKILL.md) for response structure, error handling, pagination metadata, and CLI conventions. + +**CLI note:** Current `apimux-cli` does not expose `apimux youtube ...` source subcommands yet. Use the generic capability runner: + +```bash +apimux capability call youtube.search_videos --params-json '{"query":"standing desk","count":10}' +``` + +## What you can do + +- **Find videos by topic** -> `youtube.search_videos` +- **Inspect one video** -> `youtube.get_video_detail` +- **Fetch video captions/transcripts** -> `youtube.get_video_transcript` +- **Inspect one channel** -> `youtube.get_channel_detail` +- **List channel videos or Shorts** -> `youtube.get_channel_videos` +- **Collect video comments** -> `youtube.get_video_comments` +- **Collect replies to one comment** -> `youtube.get_comment_replies` + +## Available capabilities + +| Capability | What it does | When to use | +|------------|--------------|-------------| +| `youtube.search_videos` | Search public YouTube videos | Topic discovery, brand monitoring, competitor video discovery | +| `youtube.get_video_detail` | Get one video by `video_id` or URL | Inspect metadata, channel, engagement, description, and thumbnail | +| `youtube.get_video_transcript` | Get caption/transcript text | Summarize video content, extract talking points, compare claims | +| `youtube.get_channel_detail` | Get one channel by channel ID, handle, or URL | Creator/channel qualification and audience sizing | +| `youtube.get_channel_videos` | List videos or Shorts from one channel | Creator auditing and recent-content sampling | +| `youtube.get_video_comments` | List comments for one video | Audience feedback and objection mining | +| `youtube.get_comment_replies` | List replies for one parent comment | Thread-level discussion analysis | + +## Common workflows + +- Unknown video: use `youtube.search_videos`, pick a `video_id` or `url`, then call `youtube.get_video_detail`, `youtube.get_video_transcript`, or `youtube.get_video_comments`. +- Channel research: call `youtube.get_channel_detail` by `--handle`, `--channel-id`, or `--url`, then sample recent content with `youtube.get_channel_videos`. +- Shorts vs videos: set `content_type` to `shorts`, `video`, or `all` in `youtube.get_channel_videos`. +- Comment mining: use `youtube.get_video_comments`, then pass a returned `comment_id` into `youtube.get_comment_replies`. + +--- + +## youtube.search_videos + +Search public YouTube videos by query. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `query` | string | Yes | YouTube search query | +| `cursor` | string | No | Continuation cursor from a previous page | +| `count` | integer | No | Maximum number of videos to return | + +### CLI usage + +```bash +apimux capability call youtube.search_videos --params-json '{"query":"desk setup","count":10}' +apimux capability call youtube.search_videos --params-json '{"query":"desk setup","cursor":"","count":10}' +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `video_id` | string | YouTube video ID | +| `title` | string | Video title | +| `url` | string | Canonical watch URL | +| `description` | string | Video description or snippet | +| `published_time` | string | Publish timestamp or display text | +| `duration` | string | Duration display when available | +| `thumbnail` | string | Thumbnail URL | +| `view_count` | integer | View count | +| `like_count` | integer | Like count | +| `comment_count` | integer | Comment count | +| `channel` | object | Canonical channel summary | + +--- + +## youtube.get_video_detail + +Fetch one public YouTube video detail by `video_id` or URL. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `video_id` | string | Conditional | YouTube video ID. Use either `video_id` or `url`. | +| `url` | string | Conditional | YouTube video URL. Use either `video_id` or `url`. | + +### CLI usage + +```bash +apimux capability call youtube.get_video_detail --params-json '{"video_id":"dQw4w9WgXcQ"}' +apimux capability call youtube.get_video_detail --params-json '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}' +``` + +### Notes + +- Provide at least one identity input: `video_id` or `url`. +- Output fields match `youtube.search_videos` with fuller detail when the provider returns it. + +--- + +## youtube.get_video_transcript + +Fetch caption or transcript text for one public YouTube video. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `video_id` | string | Yes | YouTube video ID | +| `language` | string | No | Caption language code | +| `format` | string | No | `segments` or `plain`; default `segments` | + +### CLI usage + +```bash +apimux capability call youtube.get_video_transcript --params-json '{"video_id":"dQw4w9WgXcQ","format":"plain"}' +apimux capability call youtube.get_video_transcript --params-json '{"video_id":"dQw4w9WgXcQ","language":"en","format":"segments"}' +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `video_id` | string | YouTube video ID | +| `language` | string | Selected language code | +| `segments` | object[] | Timed caption segments when `format=segments` | +| `text` | string | Joined transcript text when `format=plain` | + +--- + +## youtube.get_channel_detail + +Fetch one YouTube channel summary by channel ID, handle, or URL. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `channel_id` | string | Conditional | Canonical YouTube channel ID | +| `handle` | string | Conditional | YouTube handle without `@` | +| `url` | string | Conditional | YouTube channel URL | + +### CLI usage + +```bash +apimux capability call youtube.get_channel_detail --params-json '{"handle":"mkbhd"}' +apimux capability call youtube.get_channel_detail --params-json '{"url":"https://www.youtube.com/@mkbhd"}' +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `channel_id` | string | Canonical channel ID | +| `title` | string | Channel title | +| `handle` | string | Public handle | +| `url` | string | Canonical channel URL | +| `description` | string | Channel description | +| `avatar` | string | Avatar URL | +| `subscriber_count` | integer | Subscriber count | +| `video_count` | integer | Video count | +| `view_count` | integer | Total view count | + +--- + +## youtube.get_channel_videos + +List videos or Shorts from one YouTube channel. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `channel_id` | string | Conditional | Canonical YouTube channel ID | +| `handle` | string | Conditional | YouTube handle without `@` | +| `url` | string | Conditional | YouTube channel URL | +| `content_type` | string | No | `video`, `shorts`, or `all`; default `video` | +| `cursor` | string | No | Continuation cursor | +| `count` | integer | No | Maximum items to return | + +### CLI usage + +```bash +apimux capability call youtube.get_channel_videos --params-json '{"handle":"mkbhd","content_type":"video","count":10}' +apimux capability call youtube.get_channel_videos --params-json '{"handle":"mkbhd","content_type":"shorts","count":10}' +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `video_id` | string | YouTube video ID | +| `title` | string | Video title | +| `url` | string | Canonical watch URL | +| `published_time` | string | Publish timestamp or display text | +| `duration` | string | Duration display when available | +| `thumbnail` | string | Thumbnail URL | +| `view_count` | integer | View count | + +--- + +## youtube.get_video_comments + +List comments for one public YouTube video by `video_id` or URL. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `video_id` | string | Conditional | YouTube video ID | +| `url` | string | Conditional | YouTube video URL | +| `cursor` | string | No | Continuation cursor | +| `count` | integer | No | Maximum comments to return | + +### CLI usage + +```bash +apimux capability call youtube.get_video_comments --params-json '{"video_id":"dQw4w9WgXcQ","count":20}' +apimux capability call youtube.get_video_comments --params-json '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","count":20}' +``` + +### Response fields + +| Field | Type | Description | +|-------|------|-------------| +| `comment_id` | string | YouTube comment ID | +| `text` | string | Comment text | +| `create_time` | string | RFC3339 timestamp or provider display text | +| `like_count` | integer | Like count | +| `reply_count` | integer | Reply count | +| `author` | object | Canonical author summary | + +--- + +## youtube.get_comment_replies + +List replies for one YouTube parent comment. + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `comment_id` | string | Yes | Parent comment ID | +| `video_id` | string | No | YouTube video ID | +| `cursor` | string | No | Continuation cursor | +| `count` | integer | No | Maximum replies to return | + +### CLI usage + +```bash +apimux capability call youtube.get_comment_replies --params-json '{"comment_id":"Ug...","count":20}' +apimux capability call youtube.get_comment_replies --params-json '{"video_id":"dQw4w9WgXcQ","comment_id":"Ug...","count":20}' +``` + +### Notes + +- `comment_id` is required. +- Use `meta.cursor` and `meta.has_more` for pagination when returned.